Docker - rejetto/hfs GitHub Wiki

HFS has an official Docker image on Docker Hub: rejetto/hfs.

Quick start

Run (persists config under /data, mounts a share, and uses host networking for real client IPs):

docker run -d --name hfs --network host \
  -v /path/to/hfs-data:/data \
  -v /path/to/share:/shares \
  -e HFS_INITIAL_ADMIN_PASSWORD=YOUR_PASSWORD \
  rejetto/hfs:latest

Replace both host paths with your own directories and YOUR_PASSWORD with your chosen password. Open http://SERVER_IP/~/admin/ and log in with username admin and that password.

Admin account

HFS_INITIAL_ADMIN_PASSWORD sets the password for username admin only when the Docker entrypoint creates a missing config.yaml. It does not change existing configurations, including empty files. Keep /data persistent and manage subsequent password changes in HFS. Other environment settings, such as HFS_PORT, continue to apply; do not enable HFS_ENV_BOOTSTRAP for this purpose.

The initial password can be removed from your container settings after setup. HFS does not automatically remove it from Docker or from a NAS app's saved settings. A non-empty HFS_CREATE_ADMIN takes precedence if both variables are provided. If neither is non-empty, a new configuration uses please-change.

Legacy password override

HFS_CREATE_ADMIN takes only a password, not username:password. For example, HFS_CREATE_ADMIN=alice:secret sets the password of admin to the entire string alice:secret; it does not create a user named alice.

By default, this variable creates or updates admin at every container start, including with an existing configuration. Password changes made in the Admin panel are overwritten on the next start while this variable remains set. To manage the password in HFS, remove the variable from your container settings after setup and recreate the container, keeping the same persistent configuration volume. If you cannot log in and the variable is no longer set, add create-admin: 'YOUR_NEW_PASSWORD' to the existing config.yaml, preserving its other settings. HFS processes this entry automatically and removes it; log in as admin with the new password.

create-admin is a command for the running HFS console, not a shell executable. docker exec hfs create-admin ... therefore does not work. Running ./hfs inside the container starts a second server; use the config-file method above when the HFS console is unavailable.

Shared folders

The initial config points the VFS root ("Home folder" in Admin) at /shares inside the container. Mount your host share at that path, as in the example above.

If you mount it elsewhere, such as /media-storage, change the root's source in the existing config to match, keeping other VFS settings:

vfs:
  source: /media-storage

Reload the Admin page after changing the config. The source must point to a directory that exists inside the container and is readable by HFS.

Notes

  • When initializing a new configuration without either password variable, the Docker image creates an admin account with password please-change. Change it immediately!
  • Config, data, and logs are stored under /data (so keep /data persistent).
  • If no config exists, the container creates one with a VFS entry for /shares.
  • The default Docker config exposes /shares if it is mounted. Add other folders in the Admin panel.
  • The container listens on port 80 by default.

Real client IPs

You’ll only see real client IPs on Linux with host networking. On macOS/Windows (Docker Desktop) they stay masked unless you use a reverse proxy that forwards X-Forwarded-For and configure HFS to trust it. See: https://github.com/rejetto/hfs/wiki/Reverse-proxy

Environment variables

  • HFS_INITIAL_ADMIN_PASSWORD: password for admin when creating a missing configuration file; ignored for existing configurations.
  • HFS_CREATE_ADMIN: creates or updates the admin account at every container start. Its value is only the password; see the account section above.
  • HFS_CWD: overrides the configuration directory. Otherwise the image uses /home/hfs/.hfs if that legacy directory exists, or /data. Keep the directory you use mounted persistently.
  • HFS_PORT: HTTP listening port inside the container (default 80).

HFS_ENV_BOOTSTRAP: applies environment configuration only when the configuration loaded at startup is empty. It affects all HFS configuration variables, not just the admin password. Missing, empty, or comments-only configuration files count as empty; command-line configuration arguments still apply. Unset HFS_ENV_BOOTSTRAP to disable it: the string false also enables it.

The Docker entrypoint creates a non-empty configuration before HFS starts. Enabling HFS_ENV_BOOTSTRAP therefore ignores environment configuration such as HFS_PORT even on a fresh Docker installation.

HFS also supports configuration through HFS_* variables; see the configuration documentation.