Skip to content

Environment variables

Hollo is configured using environment variables. You can set them in an .env file in the root directory of the project, or you can set them using Docker’s -e/--env option or Railway’s environment variables.

PORT Optional Unused in Railway

Section titled “PORT ”

The port number to listen on. 3000 by default.

BIND Optional Unused in Railway

Section titled “BIND ”

The address to listen on. Must be a valid IP address or localhost.

DATABASE_URL Unused in Railway

Section titled “DATABASE_URL ”

The URL of the PostgreSQL database, e.g., postgresql://hollo:password@localhost/hollo.

SECRET_KEY Unused in Railway

Section titled “SECRET_KEY ”

The secret key for securing the session. Must be at least 44 characters long. You can generate a random secret key using the following command:

openssl rand -hex 32

The time zone of the application. It has to be a valid time zone identifier, e.g., UTC, America/New_York, Asia/Tokyo.

UTC by default.

Controls which components run in this process. Valid values are:

  • all (default): Run web server, Fedify message queue, import worker, cleanup worker, remote replies scrape worker, and poll notifications
  • web: Run only the web server (HTTP API)
  • worker: Run only workers (Fedify message queue + import worker + cleanup worker + remote replies scrape worker + poll notifications)

This allows separating the web server from background workers for better scalability. When running high-traffic instances with many followers, separating workers can improve performance.

all by default.

Import, cleanup, remote replies scraping, and poll notifications use the dedicated task queue described in Separating worker nodes. All nodes must run compatible task definitions.

BEHIND_PROXY Optional Unused in Railway

Section titled “BEHIND_PROXY ”

Set this to true if Hollo is behind a reverse proxy. If you place the Hollo behind an L7 load balancer (you usually should do this), turn this on.

Turned off by default.

When enabled, Hollo uses the first nonempty value in comma-separated X-Forwarded-Host and X-Forwarded-Proto headers. Invalid forwarded hosts are ignored in favor of the original Host header. Configure your proxy to replace client-supplied forwarded headers and allow only trusted proxies to connect directly to Hollo.

The fediverse handle domain when running a split-domain WebFinger setup. When set, fediverse handles take the form @user@HANDLE_HOST even though Hollo itself is served at WEB_ORIGIN.

Must be set together with WEB_ORIGIN; setting only one is a startup error. Configure both before creating the first account — changing the handle domain after federation has begun breaks remote follow relationships.

Not set by default.

The origin (scheme + host) where Hollo’s ActivityPub server actually runs in a split-domain WebFinger setup, e.g. https://ap.example.com. Actor URIs, inbox URLs, and other federation endpoints are built under this origin.

Must be set together with HANDLE_HOST; setting only one is a startup error.

Not set by default.

ALLOW_PRIVATE_ADDRESS Optional

Section titled “ALLOW_PRIVATE_ADDRESS ”

Setting this to true disables SSRF (Server-Side Request Forgery) protection.

Turn on to test in local network.

Turned off by default.

If present, the home page will redirect to this URL. If not set, the home page will show the list of accounts on the instance.

MARKDOWN_EXTENSIONS Optional

Section titled “MARKDOWN_EXTENSIONS ”

A comma-separated list of optional Markdown extensions for local posts: footnote, deflist, sub, sup, mark, ruby, ins, abbr, tasklist, and math. For example, MARKDOWN_EXTENSIONS=footnote,ruby,math enables footnotes, ruby annotations, and mathematics. Surrounding whitespace is ignored, duplicate names are accepted, and unknown names prevent startup. Unset or empty means all optional extensions are disabled. Tables and strikethrough remain available without this setting.

Extensions apply when local posts are created or explicitly edited, not to profile biographies or fields. Changing this setting does not change stored source or HTML, or send updates for existing posts. Editing a post renders it with the current setting, so disabling an extension can make its syntax appear literally after an edit.

See the Markdown guide for syntax, escaping, and federation limitations.

A comma-separated list of locale tag patterns for local posts that should have Hangul readings added to Hanja by Gukhanmun. Matching is case-insensitive, and * can stand for any sequence of characters. For example, GUKHANMUN=ko,ko-* matches ko, ko-KR, ko-Kore-KR, and ko-KP.

The ko-* pattern does not match the bare ko tag, so list both when both forms should be processed. Locales with a KP region subtag use the ko-kp conversion preset; other matching locales use ko-kr. The selected dictionaries determine the word readings; see GUKHANMUN_DICTS below.

If this variable is unset or empty, Gukhanmun is not loaded. It processes only local posts when they are created or edited. Existing and remote posts are not changed. A loading or conversion error causes the post request to fail.

A comma-separated list of dictionaries for Gukhanmun, in priority order. The first matching dictionary wins. For example, GUKHANMUN_DICTS=loanwords,stdict prefers loanword spellings over the Standard Korean Dictionary.

Supported names are loanwords (NIKL loanword spelling examples), stdict (Standard Korean Dictionary), and opendict:general, opendict:north-korean, opendict:dialect, and opendict:archaic (Open Korean Dictionary categories). opendict expands to all four categories in that order, at its position in the list.

Defaults to loanwords,opendict:general,opendict:dialect,stdict. The same list applies to every locale. To prefer North Korean dictionary readings, put opendict:north-korean first.

Whitespace around names and empty list items are ignored. An empty value loads no word dictionaries; Unihan character readings still apply. An unknown name makes conversion fail. This setting does not enable conversion by itself; set GUKHANMUN to select the locales to process.

REMOTE_ACTOR_FETCH_POSTS Optional

Section titled “REMOTE_ACTOR_FETCH_POSTS ”

The number of recent public posts to fetch from remote actors when they are encountered first time.

10 by default.

REMOTE_REPLIES_SCRAPE_DEPTH Optional

Section titled “REMOTE_REPLIES_SCRAPE_DEPTH ”

The number of remote reply levels to scrape in background jobs. Hollo first reads a remote post’s FEP-f228 context collection, when present, and uses replies collections as a fallback. Set this to 0 to disable both. Missing ancestors outside the context collection are not fetched. Posts with missing parents are stored, but remain disconnected from those parents in the status-context reply tree.

2 by default.

REMOTE_REPLIES_SCRAPE_MAX_ITEMS Optional

Section titled “REMOTE_REPLIES_SCRAPE_MAX_ITEMS ”

The maximum number of items yielded by one context backfill attempt, including already stored posts. For a replies job, this limits persisted reply items. Reaching the cap leaves the context partial and enables the seed posts’ replies fallback.

100 by default.

REMOTE_REPLIES_SCRAPE_MAX_REQUESTS Optional

Section titled “REMOTE_REPLIES_SCRAPE_MAX_REQUESTS ”

The maximum number of document-loader calls in one backfill attempt, shared by collection traversal and post/actor persistence. Cached documents and built-in JSON-LD contexts do not count; custom JSON-LD contexts do. This does not limit redirects or signature retries inside the loader, WebFinger, NodeInfo, media downloads, or preview-card requests. Reaching the cap leaves the context partial and enables the replies fallback.

200 by default.

REMOTE_EMOJI_REACTIONS_FETCH_MAX_ITEMS Optional

Section titled “REMOTE_EMOJI_REACTIONS_FETCH_MAX_ITEMS ”

The maximum number of emoji reaction items to import from a remote emojiReactions collection when a remote post is persisted. Set this to 0 to disable remote emoji reaction imports.

100 by default.

REMOTE_REPLIES_SCRAPE_INTERVAL_SECONDS Optional

Section titled “REMOTE_REPLIES_SCRAPE_INTERVAL_SECONDS ”

The minimum delay between remote replies scraping requests to the same origin.

5 by default.

REMOTE_REPLIES_SCRAPE_BACKOFF_SECONDS Optional

Section titled “REMOTE_REPLIES_SCRAPE_BACKOFF_SECONDS ”

The fallback delay before retrying a remote replies scraping job after an HTTP 429 response when the remote server does not provide Retry-After.

300 by default.

REMOTE_REPLIES_SCRAPE_COOLDOWN_SECONDS Optional

Section titled “REMOTE_REPLIES_SCRAPE_COOLDOWN_SECONDS ”

The time window during which completed remote scraping jobs suppress duplicates for the same collection. Failed context jobs also observe this cooldown; their seeds can still fall back to replies collections.

300 by default.

Controls how Hollo serves media that lives on remote servers (avatars, headers, attachments, custom emojis, preview-card images). Valid values are:

  • off (default): the Mastodon API and web UI hand the original remote URL to clients, matching the historical behaviour.
  • proxy: every remote media URL is rewritten to a signed /proxy/<sig>/<b64url> path served by Hollo itself. Hollo streams the upstream bytes through on each request and does not write them to disk. Clients see only the Hollo origin, sidestepping remote CORS configuration and leaks of the visitor’s IP address.
  • cache: same URL rewriting as proxy, but the streamed body is persisted to the configured storage backend as proxy/<sha256>.bin alongside a content-type sidecar at proxy/<sha256>.json. Subsequent requests skip the upstream fetch. Remote actor avatars for accounts with an approved follow relationship to the local account are also prefetched into this cache when the actor is stored or refreshed. The admin dashboard at /thumbnail_cleanup can purge the cache on demand.

The boolean synonyms true / on / 1 are accepted as aliases for proxy, and false / off / 0 as aliases for off. Disk caching must be requested explicitly with cache.

In proxy and cache modes, Hollo refuses non-HTTP(S) schemes, runs SSRF checks on each upstream URL and every redirect target, enforces a 32 MiB body cap, and never proxies image/svg+xml — SVG could carry inline scripts that execute under the Hollo origin.

off by default.

REMOTE_MEDIA_THUMBNAILS Optional

Section titled “REMOTE_MEDIA_THUMBNAILS ”

Controls whether Hollo downloads remote media attachments to generate a local WebP thumbnail when it ingests a post. Accepts on / true / 1 (the historical behaviour) or off / false / 0.

When set to off, Hollo skips the upstream fetch and Sharp pipeline entirely for incoming attachments, storing the remote URL itself as the thumbnail URL. Combined with MEDIA_PROXY=proxy or cache, clients still see a same-origin URL at render time; with MEDIA_PROXY=off, they receive the upstream URL directly. This frees up significant disk space on instances that ingest many media-heavy posts.

on by default.

REMOTE_ACTOR_STALENESS_DAYS Optional

Section titled “REMOTE_ACTOR_STALENESS_DAYS ”

The number of days after which a remote actor’s cached data is considered stale. When a stale actor is encountered during activity processing (e.g., receiving a boost or a new post), their profile data will be refreshed asynchronously.

7 by default.

REFRESH_ACTORS_ON_INTERACTION Optional

Section titled “REFRESH_ACTORS_ON_INTERACTION ”

When set to true, checks for stale actor data on all incoming activities (likes, emoji reactions, follows, etc.). When false (default), only checks on activities that appear in timelines (Announce, Create).

Turned off by default.

Setting this to false disables timeline inbox mode. When enabled (the default), all posts visible to your timeline are physically stored in the database, rather than being filtered in real-time as they are displayed. This is useful for relatively larger instances with many incoming posts.

This option defaults to true as of Hollo 0.9.0. It will be removed entirely in Hollo 1.0.0, when timeline inbox mode will be the only behavior.

Turned on by default.

Setting this to true allows raw HTML inside Markdown, which is used for formatting posts, bio, etc. This is useful for allowing users to use broader formatting options outside of Markdown, but to avoid XSS attacks, it is still limited to a subset of HTML tags and attributes.

Turned off by default.

The log level for the application. debug, info, warning, error, and fatal are available.

info by default.

Set this to true to log SQL queries.

Turned off by default.

The path to the log file. Unlike console output, the log file uses structured logging format (JSON Lines by default).

The format of the log file set by LOG_FILE. Valid values are:

  • jsonl (default): JSON Lines format, one JSON object per line. Suitable for log aggregation tools that parse structured JSON.
  • logfmt: logfmt format, a key=value pair per line. Human-readable and compatible with tools like Loki and Heroku’s log drains.

jsonl by default.

The DSN of the Sentry project to send error reports and traces to.

Set this to true to enable the Fedify debugger, an embedded real-time debug dashboard for inspecting ActivityPub traces and activities. When enabled, the debug dashboard is available at /__debug__/.

Turned off by default.

The disk driver used by Hollo to store blobs such as avatars, custom emojis, and other media.

Valid values are fs (local filesystem) and s3 (S3-compatible object storage).

Defaults to s3 for backward compatibility, but it is recommended to explicitly configure the driver as the default value will be removed in the future.

See the FlyDrive docs for details about the drivers.

The public URL base of the asset storage, e.g., https://media.hollo.social.

When using DRIVE_DISK=fs, you should set this to serve local filesystem files via web access, typically in the format https://<host>/assets, e.g., https://hollo.example.com/assets.

FS_STORAGE_PATH Required with FS driver

Section titled “FS_STORAGE_PATH ”

The path in the local filesystem where blob assets are stored, e.g., /var/lib/hollo.

S3_REGION Required with S3 driver

Section titled “S3_REGION ”

The region of the S3-compatible object storage, e.g., us-east-1. On some non-S3 services, this can be omitted.

S3_BUCKET Required with S3 driver

Section titled “S3_BUCKET ”

The bucket name of the S3-compatible object storage, e.g., hollo.

S3_ENDPOINT_URL Required with S3 driver

Section titled “S3_ENDPOINT_URL ”

The endpoint URL for S3-compatible object storage, e.g., https://s3.us-east-1.amazonaws.com.

S3_FORCE_PATH_STYLE Optional

Section titled “S3_FORCE_PATH_STYLE ”

Whether to force path-style URLs for S3-compatible object storage. true to turn on, false to turn off. Useful for non-AWS S3-compatible services. Turned off by default.

AWS_ACCESS_KEY_ID Required with S3 driver

Section titled “AWS_ACCESS_KEY_ID ”

The access key for S3-compatible object storage.

AWS_SECRET_ACCESS_KEY Required with S3 driver

Section titled “AWS_SECRET_ACCESS_KEY ”

The secret key for S3-compatible object storage.