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.

Basic settings

PORT Optional Unused in Railway

The port number to listen on. 3000 by default.

BIND Optional Unused in Railway

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

DATABASE_URL Unused in Railway

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

SECRET_KEY Unused in Railway

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

TZ Optional

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.

NODE_TYPE Optional

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

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

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.

Note

For most single-user instances, the default all mode is sufficient. Worker separation is primarily beneficial for instances with thousands of followers or heavy federation activity.

When using web mode, ensure at least one worker node is running to process incoming activities and send outgoing posts.

BEHIND_PROXY Optional Unused in Railway

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.

Note

With this option, Hollo will trust the X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers from the reverse proxy. This is important for security reasons.

HANDLE_HOST Optional

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.

WEB_ORIGIN Optional

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

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

Turn on to test in local network.

Turned off by default.

Note

Turning on this option is dangerous security-wise. Only use this option in a trusted environment and never in production.

Additional features

HOME_URL Optional

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.

REMOTE_ACTOR_FETCH_POSTS Optional

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

The number of remote reply levels to scrape in background worker jobs. Set this to 0 to disable remote replies scraping.

2 by default.

REMOTE_REPLIES_SCRAPE_MAX_ITEMS Optional

The maximum number of reply items to persist from a single remote replies scraping job.

100 by default.

REMOTE_REPLIES_SCRAPE_INTERVAL_SECONDS Optional

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

5 by default.

REMOTE_REPLIES_SCRAPE_BACKOFF_SECONDS Optional

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

The time window during which completed remote replies scraping jobs suppress duplicate jobs for the same replies collection.

300 by default.

MEDIA_PROXY Optional

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

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

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

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.

TIMELINE_INBOXES Optional

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.

ALLOW_HTML Optional

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.

Logging and debugging

LOG_LEVEL Optional

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

info by default.

LOG_QUERY Optional

Set this to true to log SQL queries.

Turned off by default.

LOG_FILE Optional

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

LOG_FILE_FORMAT Optional

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.

SENTRY_DSN Optional

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

FEDIFY_DEBUG Optional

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.

Caution

The Fedify debugger is intended for development use only. Enabling it in production exposes internal trace data, which is a security risk.

Asset storage

DRIVE_DISK

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.

Caution

If you change the DRIVE_DISK and related settings of a running Hollo during production, existing files are not moved; only new files are stored according to the new settings.

Also, keep in mind that existing files will still be served according to the old settings, so if you change S3_BUCKET, for example, they will still be served from the old bucket and should not be deleted.

STORAGE_URL_BASE

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.

Caution

• HTTPS is required in production environments.
• Must be publicly accessible for federation to work correctly.
• Recommend using a CNAMEd domain rather than the actual domain of an object storage for flexibility.

Local filesystem settings

FS_STORAGE_PATH Required with FS driver

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

Note

• Directory must exist and be writable by the Hollo process.
• Recommended permissions: 755 for directories, 644 for files.
• Ensure sufficient storage capacity for your use case.
• Regular backups are strongly recommended.
• When using Docker, ensure the path is properly mounted.

S3-compatible object storage settings

Note

These settings are only required when DRIVE_DISK=s3.

Ensure your AWS IAM policy grants the following permissions:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket

S3_REGION Required with S3 driver

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

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

S3_ENDPOINT_URL Required with S3 driver

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

S3_FORCE_PATH_STYLE Optional

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

The access key for S3-compatible object storage.

AWS_SECRET_ACCESS_KEY Required with S3 driver

The secret key for S3-compatible object storage.