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, and import worker
• web: Run only the web server (HTTP API)
• worker: Run only workers (Fedify message queue + import 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.

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_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 true lets your timelines work like inboxes: 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.

As of Hollo 0.4.0, it is experimental and may have several bugs, but it is epxected to be the default behavior in the future after it is stabilized.

Turned off 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 is written in JSON Lines format which is suitable for structured logging.

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.