hop3.toml Reference¶

This document provides a complete reference for the hop3.toml configuration format.

Philosophy: Convention over Configuration¶

Hop3 follows the "Convention over Configuration" principle:

• Procfile is the convention (default, simple, Heroku-compatible)
• hop3.toml is the configuration (optional, advanced, full-featured)
• Precedence: hop3.toml > Procfile > defaults

You can use: - Procfile only - Simple, works out of the box - hop3.toml only - Full configuration control - Both together - Use Procfile for basics, override with hop3.toml for advanced features

Configuration Precedence¶

When both Procfile and hop3.toml are present:

1. Hop3 loads the Procfile first (convention)
2. Then loads hop3.toml (configuration)
3. hop3.toml values override Procfile values
4. Non-conflicting values are merged

Example:

# Procfile
web: gunicorn app:app
worker: celery worker

# hop3.toml
[run]
start = "uvicorn app:app"  # Overrides 'web' from Procfile

# Result:
# web: uvicorn app:app (from hop3.toml)
# worker: celery worker (from Procfile)

File Location¶

Place hop3.toml in one of these locations (checked in order): 1. src/hop3/hop3.toml 2. src/hop3.toml 3. hop3.toml (project root)

Sections¶

[metadata] - Application Metadata¶

Optional section for application identification.

[metadata]
id = "my-app"               # Unique application identifier
version = "1.0.0"           # Application version
title = "My Application"    # Human-readable title
author = "Your Name <you@example.com>"  # Author information

Fields: - id (string): Unique identifier for the application - version (string): Semantic version number - title (string): Display name for the application - author (string): Author name and email

[build] - Build Configuration¶

Controls how your application is built and prepared for deployment.

[build]
# Builder to use: "auto", "local", or "docker"
builder = "local"

# Commands to run during build
build = ["npm run build", "make"]

# Commands to run before build
before-build = "npm ci"

# Test commands (smoke tests)
test = "npm test"

# System packages needed for build
packages = ["nodejs", "gcc", "make"]

# Python packages to install during build
pip-install = ["setuptools", "wheel"]

Fields: - builder (string): Which builder to use for deployment: - "auto" (default): Auto-detect based on project files (Dockerfile → docker, otherwise local) - "local": Use native language toolchains (Python, Node, Ruby, etc.) directly on host - "docker": Build and run using Docker (requires Dockerfile) - build (string | array): Main build commands - before-build (string | array): Pre-build commands (maps to Procfile prebuild) - test (string | array): Test commands to run after build - packages (array): System packages required for building - pip-install (array): Python packages to install during build - ignore (array): Gitignore-style patterns excluded from the hop3 deploy upload (see below)

Procfile Mapping: - build.before-build → Procfile prebuild

ignore - Excluding files from the upload¶

When you run hop3 deploy, the CLI tars your working tree and uploads it. [build].ignore is the single, canonical way to say what not to upload:

[build]
ignore = ["*.log", "tmp/", "coverage/", "*.sqlite3"]

Patterns use gitignore syntax (including ! negation), and are added on top of Hop3's built-in defaults — VCS metadata and dependency/cache dirs that the server regenerates (.git/, node_modules/, .venv/, venv/, __pycache__/, *.py[cod], .idea/, .DS_Store, .mypy_cache/, .pytest_cache/, .ruff_cache/, *.egg-info/). So most apps need no ignore at all.

Other ignore files are scoped to their own deployment method — they do not affect the hop3 deploy upload:

• .gitignore applies to the git-push deploy path (git itself decides what reaches the server). It is not consulted for the hop3 deploy upload.
• .dockerignore applies to the server-side docker build context when builder = "docker" (Docker honors it there). It is not applied to the upload.

The legacy .hop3ignore sidecar and the [build].ignore-file pointer are removed. Move any .hop3ignore patterns into [build].ignore; a leftover .hop3ignore is still read for one transition release with a deprecation warning, and [build].ignore-file is now a hop3.toml validation error.

[run] - Runtime Configuration¶

Defines how your application runs.

[run]
# Main application start command
start = "gunicorn app:app --workers 4"

# Commands to run before starting
before-run = ["python manage.py migrate", "python manage.py collectstatic --noinput"]

# System packages needed at runtime
packages = ["postgresql", "redis"]

# Startup timeout in seconds (default: 60 = 1 minute)
start-timeout = 120

Fields: - start (string | array): Main application start command (maps to Procfile web) - before-run (string | array): Pre-run commands (maps to Procfile prerun) - packages (array): System packages required at runtime - start-timeout (number): Maximum time in seconds to wait for the app to start (default: 60)

Procfile Mapping: - run.start → Procfile web - run.before-run → Procfile prerun

Startup Timeout:

The start-timeout option controls how long Hop3 waits for your application to start before marking the deployment as failed. This is useful for applications with slow startup times (e.g., Java apps, apps with large dependency trees).

[run]
start-timeout = 120  # Wait up to 2 minutes for app to start

The server-wide default is 60 seconds (1 minute), configurable via the APP_START_TIMEOUT environment variable on the server. During the wait, Hop3 streams log output so you can see what's happening.

[env] - Environment Variables¶

Define environment variables for your application.

[env]
DATABASE_URL = "postgresql://localhost/mydb"
SECRET_KEY = "your-secret-key"
ALLOWED_HOSTS = "myapp.example.com"
LOG_LEVEL = "info"

Notes:

• Sensitive values should be injected through hop3 config set, not hardcoded in hop3.toml. For secrets the app needs to exist before its first boot, use a generated secret (below) instead of a manual config set.
• The DEBUG environment variable defaults to false. Only set DEBUG = "true" in development environments for troubleshooting—never in production.

Generated secrets¶

Some apps require a secret or key to exist before they boot (e.g. Phoenix SECRET_KEY_BASE, Laravel APP_KEY, Rails secret_key_base) — the release crashes without it, so there is no chance to set it afterwards. Declare such a value as a generated secret and Hop3 creates it for you on first deploy:

[env]
SECRET_KEY_BASE = { generate = "hex", length = 64 }
APP_KEY         = { generate = "base64", length = 32, prefix = "base64:" }
ADMIN_PASSWORD  = { generate = "password", length = 24, display = true }
SESSION_ID      = { generate = "uuid" }

Fields:

Semantics:

• The value is generated with a cryptographically secure RNG only when the variable is currently unset, then stored as a normal app env var (visible in hop3 config show).
• It is generated once and never rotated on redeploy — so redeploys stay idempotent and a regenerated secret never silently invalidates existing sessions or data. Setting _policy = "override" does not force rotation.
• To rotate a generated secret, run hop3 config unset <app> KEY and redeploy.
• A malformed spec (unknown generator, length < 1, unknown field) is a hop3.toml validation error — it fails the deploy loudly rather than producing a bad secret.

Dynamic references¶

Most apps need nothing here: attaching an addon already injects its standard variables (DATABASE_URL, PGHOST, REDIS_URL, …), and [env.computed] assembles custom strings from them. A reference is for the cases those can't express — copying one specific attribute, or reading an app fact:

[env]
# Copy one attribute from a declared addon's credentials. `key` is one of the
# addon's injected variable names (run `hop3 config show` to see them).
PRIMARY_DB_HOST = { from = "myapp-db", key = "PGHOST" }

# App facts (no `from`): "domain"/"hostname" → the app's first hostname,
# "name" → the app name.
APP_FQDN = { key = "domain" }

Fields:

Semantics:

• References are derived values resolved fresh on every deploy (like [env.computed]), so they overwrite. Resolution order is: addon auto-injection → static [env] → generated secrets → references → [env.computed]. A { key = "domain" } ref therefore sees the hostname from [domains], and a [env.computed] template can interpolate a resolved reference.
• Resolution fails the deploy loudly if the addon isn't attached, the key doesn't exist (the error lists the available keys), or the app fact is unknown — never a wrong or empty value.
• { from = ..., key = ... } resolves against this app's own addons only; it can't read another app's credentials.

[domains] - Application Hostnames¶

Declare the hostnames the reverse proxy should bind to your app.

[domains]
list = ["abilian.com", "www.abilian.com", "fermigier.com", "www.fermigier.com"]
_policy = "keep-existing"   # optional; "override" to overwrite on every deploy

Fields:

• list (array of strings, required when section is present): hostnames bound to this app, in declaration order. Each entry must be a valid RFC-1123 hostname. The special value "_" is the nginx catch-all and may only appear alone.
• _policy (string, optional, default "keep-existing"): merge policy. Mirrors [env]._policy. With "keep-existing", a manually set HOST_NAME (via hop3 config set or hop3 domains) is preserved across deploys. With "override", the value from hop3.toml is reapplied on every deploy.

Notes:

• [domains].list is mutually exclusive with HOST_NAME under [env]. Setting both is a hop3.toml validation error — use one or the other.
• At deploy time, the section is translated into the HOST_NAME env var that the reverse-proxy plugins (nginx / caddy / traefik) read.
• An empty list (list = []) is a no-op: HOST_NAME is not unset. Use hop3 domains clear <app> to remove the binding explicitly.
• For CRUD from the CLI, see hop3 domains in the CLI reference.

[port] - Port Configuration¶

Specify ports for different services.

[port]
web = 8000
api = 8080
metrics = 9090

[[ports]] - Fixed Host Ports (non-HTTP)¶

For HTTP/HTTPS apps you don't declare ports at all — Hop3 assigns a dynamic $PORT and the reverse proxy routes by hostname, so any number of apps share :80/:443. But non-HTTP services (SMTP, XMPP, RTMP, Matrix federation, …) have no proxy and no virtual hosting: the app binds a fixed host port directly, so exactly one app can own a given port on the server.

Declare those ports with [[ports]]. Hop3 records each in a host-wide registry, refuses a second app that declares the same port — before it builds — with a clear error, opens the firewall for it on a successful deploy, and closes it on teardown.

[[ports]]
number = 1935
protocol = "tcp"
name = "rtmp"        # optional label, for diagnostics

[[ports]]
number = 8448
protocol = "tcp"
name = "federation"

Fields:

Notes:

• Don't list your HTTP port here — that one is dynamic ($PORT) and proxied. [[ports]] is only for ports the app binds directly to the host.
• Two apps declaring the same (number, protocol) cannot coexist (there is no proxy to multiplex them). The second deploy is rejected up front with a message naming the app that already holds the port.
• Ports 22, 80, and 443 are reserved by Hop3 (SSH and the reverse proxy) and rejected — HTTP apps use $PORT and are proxied.
• A declared port is opened to the whole internet (source = any). Restricting it to a CIDR is a planned enhancement; for now declare a port only if it is meant to be publicly reachable.
• Native/Nix builds only. A Docker-deployed app's container does not yet publish declared ports to the host, so for Docker apps the port is claimed (conflict-checked) but the firewall is not opened. Use a native or Nix build for an app that needs a fixed host port.
• Opening the firewall needs the hop3-rootd daemon. If it isn't running the port is still claimed (so the conflict check works), but it won't be reachable externally until rootd applies the rule.

[[volumes]] - Persistent Volumes¶

Each deploy replaces your app's source tree (src/ is wiped and re-extracted), so anything written inside it is lost on the next deploy. A [[volumes]] declares a directory that must survive redeploys:

[[volumes]]
name = "uploads"
target = "data/uploads"

Hop3 stores the data under the app's data root (<app>/volumes/<name>/) — outside src/ — and links target to it on every deploy, so writes persist. On the first deploy, if your source ships content at target, it seeds the (empty) volume once; afterwards the volume is the source of truth.

Fields:

Notes:

• target must be a directory path relative to the app's source tree; absolute paths and .. are rejected. A file already at target is an error — volume targets are directories.
• Persist volumes need no hop3-rootd: the link lives under the app's own directories. tmpfs/bind will need privileged mounts and are deferred.
• Volumes are included in hop3 backup create by default; set [volumes.backup] include = false to opt a volume out.

[limits] - Resource Caps¶

Cap an app's resource use so one app can't starve others on the same server:

[limits]
memory = "512M"     # hard memory cap
cpu = 1.5           # CPU cores (fractional allowed)
processes = 256     # max processes/threads

Fields:

Notes:

• A declared limit is a safety guarantee: if it can't be enforced, the deploy fails loudly rather than running an app that only looks capped.
• Enforcement is implemented for the Docker builder (compose mem_limit / cpus / pids_limit). Native/Nix enforcement needs cgroups via hop3-rootd and isn't available yet, so declaring [limits] on a non-Docker app aborts the deploy with a clear message until then.

[healthcheck] - Health Check Configuration¶

Configure health check endpoints for monitoring.

[healthcheck]
path = "/health/"          # Health check endpoint path
timeout = 30              # Request timeout in seconds
interval = 60             # Check interval in seconds

Fields: - path (string): HTTP path for health checks - timeout (number): Timeout for health check requests - interval (number): How often to run health checks

[backup] - Backup Configuration¶

Backups are created on demand with hop3 backup create <app> and restored with hop3 backup restore <id>. A backup captures the app's source, environment variables, attached addons (e.g. a Postgres dump), the app's data/ directory, and every [[volumes]] volume (each archived as its own unit) — so persistent data round-trips through restore.

[backup]
paths = ["data", "var/state"]   # extra directories to include
exclude = ["*.tmp", "cache/"]    # patterns to leave out

Fields: - paths (array): extra directories to include beyond the defaults. - exclude (array): glob patterns to exclude.

Notes: - A [[volumes]] volume can opt out of backup with [volumes.backup] include = false. - Automated scheduling and retention are not implemented yet; run hop3 backup create from a cron job if you need a schedule. (The paths / exclude fields are reserved and not yet consumed.)

[[addons]] - Backing Services¶

Declare backing services your application needs (databases, caches, object storage). Each [[addons]] entry auto-provisions the addon on first deploy if it doesn't already exist, and injects connection env vars into the app runtime.

[[addons]]
type = "postgres"

[[addons]]
type = "redis"

[[addons]]
type = "mysql"

[[addons]]
type = "s3"

Note: Use [[addons]] (double brackets) for arrays in TOML. The legacy [[provider]] section name is deprecated; prefer [[addons]].

Common fields:

Addon-specific fields:

postgres:

Example:

[[addons]]
type = "postgres"
extensions = ["postgis", "pgvector"]

Injected environment variables (per addon type):

For CLI-level addon management (addon create, addon attach, addon detach, addon destroy) and end-to-end examples, see Addons Guide.

[test] - Test Harness Metadata¶

Optional section for the hop3-test framework. Holds fields that are genuinely test-specific; everything else (app name, description, addons, healthcheck path) is derived from the rest of hop3.toml. Replaces the separate test.toml file (removed 2026-04-21 — one source of truth per app).

[test]
priority = "P1"                        # P0 | P1 | P2
tier = "medium"                        # fast | medium | slow | very-slow (display label only)
targets = ["docker", "remote"]         # which hop3-test targets can run this app
author = "hop3-team"
covers = ["python", "flask", "postgres"]

[[test.validations]]                   # Additional HTTP probes beyond [healthcheck]
path = "/api/health"
status = 200
contains = "ok"

[[test.validations]]
path = "/"
status = 200

Fields:

Notes:

• The [test] section is entirely optional. When absent, hop3-test uses sensible defaults (priority P1, single healthcheck-path HTTP probe at status 200).
• Derived automatically from the rest of hop3.toml — do not duplicate in [test]:
• Test name: from [metadata].id or directory path.
• Category: from [build].builder ("nix" → nix-app, "docker" → docker-app, "local" → deployment).
• Required services: from [[addons]] plus implicit nix / docker based on builder.
• Base healthcheck path: from [healthcheck].path.

Command Format¶

Commands can be specified as:

1. Single string:

   start = "python app.py"
   

2. Array of strings (executed with &&):

   before-run = ["python manage.py migrate", "python manage.py collectstatic"]
   # Equivalent to: python manage.py migrate && python manage.py collectstatic
   

Examples¶

Minimal Configuration¶

[metadata]
id = "my-app"

[run]
start = "python app.py"

Python/Django Application¶

[metadata]
id = "django-blog"
version = "1.0.0"

[build]
before-build = "pip install -r requirements.txt"

[run]
start = "gunicorn blog.wsgi:application --workers 4"
before-run = "python manage.py migrate --noinput"

[env]
DJANGO_SETTINGS_MODULE = "blog.settings.production"

[[addons]]
type = "postgres"

Node.js/Express Application¶

[metadata]
id = "express-api"
version = "1.0.0"

[build]
before-build = ["npm ci", "npm run build"]
test = "npm test"

[run]
start = "node dist/server.js"
packages = ["nodejs"]

[port]
web = 3000

[[addons]]
type = "postgres"

[nix] — Template-Based Nix Builds¶

When builder = "nix" is set in [build], Hop3 can generate a Nix expression automatically from a [nix] section instead of requiring a hand-crafted hop3.nix file. This removes the Nix learning curve for most deployments.

How It Works¶

1. If a hop3.nix file exists in the source directory, it is used directly (hand-crafted mode).
2. If no hop3.nix exists but [nix].template is set, Hop3 generates one at build time from the template.
3. Run hop3 nix eject <app> to materialize the generated file for manual customization.

Template Types¶

Eight templates are available. Prefer the higher tiers when possible — see Nix reference for the reproducibility implications.

Tier 1 = source-built and reproducible (use when available). Tier 2 = source-built but not fully hermetic (depends on PyPI, Packagist, etc. at build time). Tier 3 = pre-built binary download (x86_64-linux only, not reproducible from source — use only when nothing in nixpkgs fits).

Common Fields¶

[nix]
template = "prebuilt-binary"   # Required: template type
url = "https://..."            # Source URL (supports ${version} interpolation)
sha256 = "abc123..."           # SHA-256 hash for source verification
executable = false             # true for single-binary downloads
archive = "tar-gz"             # "tar-gz", "tar-bz2", "tar-xz", "zip", or omit
binary-name = "myapp"          # Name of the binary (prebuilt-binary)
exec-target = "myapp"          # What to exec in the wrapper
exec-args = ["serve"]          # Arguments appended to exec
extra-paths = ["${php}/bin"]   # PATH entries for runtime.json

Wrapper Script Fields¶

These configure the shell wrapper that runs at application startup:

[nix.local-vars]               # Shell variables (not exported)
PORT = "${PORT:-8080}"

[nix.env-exports]              # Exported environment variables
NODE_ENV = "production"

[nix.runtime-env]              # Default env vars in runtime.json
APP_ENV = "production"

[[nix.conditional-env]]        # Set only if not already defined
name = "DATABASE_URL"
condition-var = "DATABASE_URL"
value = "postgres://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}"

Config File Generation¶

Generate config files at startup with runtime variable substitution:

[[nix.config-files]]
path = "custom/conf/app.ini"
format = "ini"                  # "ini" or "raw"
create-if-missing = false       # Only create if file doesn't exist

[nix.config-files.sections.server]
HTTP_PORT = "${PORT}"

[nix.config-files.sections.database]
HOST = "${PGHOST}:${PGPORT}"

For JSON, YAML, or complex configs, use format = "raw":

[[nix.config-files]]
path = "config.json"
format = "raw"
raw-content = """
{
  "port": ${PORT},
  "db": "postgres://${PGUSER}@${PGHOST}/${PGDATABASE}"
}
"""

PHP-Specific Fields¶

[nix]
template = "php-app"
php-version = "php82"
php-extensions = ["mysqli", "gd", "mbstring", "xml"]
needs-composer = true
composer-extra-flags = ["--ignore-platform-reqs"]
serve-mode = "builtin"         # "builtin" (php -S) or "artisan"
web-root = "htdocs"            # Subdirectory for document root
post-install-dirs = ["storage/logs", "bootstrap/cache"]

Complete Example (Gitea via nixpkgs-wrapper — Tier 1)¶

This is the recommended pattern: wrap a nixpkgs source build with a startup script that generates the app.ini config from environment variables.

[metadata]
id = "gitea"
description = "Self-hosted Git service"

[build]
builder = "nix"

[nix]
template = "nixpkgs-wrapper"
nixpkgs-package = "gitea"
exec-target = "gitea"
exec-args = ["web"]
extra-paths = ["${gitea}/bin"]
pre-exec = ["mkdir -p custom/conf data"]

[nix.local-vars]
PORT = "${PORT:-8080}"
DB_HOST = "${PGHOST:-localhost}"
DB_PORT = "${PGPORT:-5432}"
DB_NAME = "${PGDATABASE:-gitea}"
DB_USER = "${PGUSER:-gitea}"
DB_PASS = "${PGPASSWORD:-}"

[nix.env-exports]
GITEA_WORK_DIR = "$PWD"

[[nix.config-files]]
path = "custom/conf/app.ini"
format = "ini"

[nix.config-files.sections.server]
HTTP_PORT = "${PORT}"
ROOT_URL = "http://localhost:${PORT}/"

[nix.config-files.sections.database]
DB_TYPE = "postgres"
HOST = "${DB_HOST}:${DB_PORT}"
NAME = "${DB_NAME}"
USER = "${DB_USER}"
PASSWD = "${DB_PASS}"

[nix.config-files.sections.security]
INSTALL_LOCK = "true"
SECRET_KEY = "$(head -c 32 /dev/urandom | base64)"

[[addons]]
type = "postgres"

Migration from Procfile¶

Use the migration command to convert an existing Procfile:

hop3 config migrate procfile /path/to/app --dry-run

This will generate a hop3.toml from your Procfile. Review and customize as needed.

See Also¶

• Procfile Reference
• Migration Guide
• Examples