Server options
Every ferryd command and option, with its environment variable and default, generated from the server itself.
ferryd is the Ferry server: one process that runs the REST API and the dashboard, the public reverse proxy, the build and deploy engine and the reconciler. This page lists its commands and all of its options. It is generated from ferryd --dump-markdown-help and ferryd --help, so it matches the binary built from this repository.
ferryd alone starts the server: in the background when you run it from a terminal (like ferryd start), in the foreground otherwise (like ferryd run). ferryd stop, ferryd status and ferryd logs find that server through its data directory. See Background and foreground.
Every option of the server except --take-over can also be set with the environment variable shown under it. When both are set, the command-line flag wins.
One data directory per server
Only one ferryd can use a data directory at a time, and each Docker name prefix (--name-prefix) belongs to one data directory. A server refuses to start on a prefix that another data directory owns unless you pass --take-over. A data directory you moved keeps its instance_id and starts with the same --name-prefix without --take-over: the flag is only for a data directory that lost its instance_id, and never while another server uses the prefix, since the server that takes over removes the other one's containers. See Multiple servers.
ferryd
Ferry server: a self-hosted Render alternative.
Without a command, ferryd starts the server in the background when it is run from a terminal (ferryd start), and in the foreground otherwise (ferryd run): under a service manager, in a container, in a pipe.
Usage
ferryd [OPTIONS]
ferryd <COMMAND>Subcommands
start— Start the server in the backgroundrun— Run the server in the foregroundstop— Stop the serverstatus— Say whether the server runsreset-password— Replace the password of the server's accountlogs— Print the log of a server started in the background
Options
| Option and environment variable | Description | Default |
|---|---|---|
--data-dir <DATA_DIR>FERRY_DATA_DIR | Directory for the database, logs, build scratch space and certificates | ./ferry-data |
--api-addr <API_ADDR>FERRY_API_ADDR | API + dashboard listen address | 127.0.0.1:7878 |
--proxy-addr <PROXY_ADDR>FERRY_PROXY_ADDR | Public HTTP proxy listen address | 0.0.0.0:8080 |
--https-addr <HTTPS_ADDR>FERRY_HTTPS_ADDR | Public HTTPS proxy listen address (enables TLS together with --acme-email) | |
--base-domain <BASE_DOMAIN>FERRY_BASE_DOMAIN | Services are reachable at <name>.<base-domain>. More domains are connected while the server runs (dashboard: Server → Domains, or ferry domains connect) | localhost |
--public-ip <IP>FERRY_PUBLIC_IP | Public address of this server: the value of the DNS records shown for a domain, and what a domain is expected to resolve to. Repeat it (or separate with commas) for an IPv4 and an IPv6 address. Default: its IPv4 address is found out — the address of the outbound interface when it is a public one, else asked from api.ipify.org, ipv4.icanhazip.com or checkip.amazonaws.com | |
--public-port <PUBLIC_PORT>FERRY_PUBLIC_PORT | Port shown in public URLs (defaults to the proxy port) | |
--dashboard-host <DASHBOARD_HOST>FERRY_DASHBOARD_HOST | Host that serves the dashboard + API through the public proxy ("none" to disable). Default: ferry.<base-domain> when the base domain is local (e.g. localhost), otherwise disabled — enable it explicitly, ideally with HTTPS, since it exposes the admin API | |
--name-prefix <NAME_PREFIX>FERRY_NAME_PREFIX | Prefix for Docker resources; lets several Ferry servers share one daemon | ferry |
--api-token <API_TOKEN>FERRY_API_TOKEN | The server token: an API token that always works, for the CLI and automation on the server itself. Default: read from / generated into <data-dir>/api_token | |
--github-webhook-secret <GITHUB_WEBHOOK_SECRET>FERRY_GITHUB_WEBHOOK_SECRET | Secret for GitHub webhook signatures (enables POST /hooks/github) | |
--acme-email <ACME_EMAIL>FERRY_ACME_EMAIL | Email for Let's Encrypt; enables automatic HTTPS with --https-addr | |
--acme-stagingFERRY_ACME_STAGING | Use the Let's Encrypt staging environment | |
--acme-directory <ACME_DIRECTORY>FERRY_ACME_DIRECTORY | Custom ACME directory URL (e.g. Pebble for testing) | |
--build-concurrency <BUILD_CONCURRENCY>FERRY_BUILD_CONCURRENCY | Maximum concurrent builds | 2 |
--default-port <DEFAULT_PORT>FERRY_DEFAULT_PORT | Container port used when nothing else specifies one | 10000 |
--keep-images <KEEP_IMAGES>FERRY_KEEP_IMAGES | Built images kept per service (for rollbacks) | 5 |
--keep-job-runs <KEEP_JOB_RUNS>FERRY_KEEP_JOB_RUNS | Finished job runs (and their logs) kept per service | 100 |
--docker-bin <DOCKER_BIN>FERRY_DOCKER_BIN | docker CLI used for builds | docker |
--health-check-timeout <HEALTH_CHECK_TIMEOUT>FERRY_HEALTH_TIMEOUT | Seconds a new deploy has to pass its health check | 120 |
--advertise-host <ADVERTISE_HOST>FERRY_ADVERTISE_HOST | Host name printed in external datastore connection strings | 127.0.0.1 |
--default-memory-limit <SIZE>FERRY_DEFAULT_MEMORY_LIMIT | Memory limit of each service, job and datastore container that sets none of its own (e.g. 512M, 1G; 0 = unlimited) | 512M |
--default-cpu-limit <CPUS>FERRY_DEFAULT_CPU_LIMIT | CPU limit of each service, job and datastore container that sets none of its own (e.g. 0.5, 2, 500m; 0 = unlimited) | 1 |
--pids-limit <N>FERRY_PIDS_LIMIT | Max processes + threads per container, a fork-bomb guard (0 = unlimited) | 1024 |
--log-max-size <SIZE>FERRY_LOG_MAX_SIZE | Rotate each container's Docker log at this size, with the json-file driver (e.g. 10M; 0 = keep the Docker daemon's log configuration). A daemon whose default log driver isn't json-file keeps its driver | 10M |
--log-max-files <N>FERRY_LOG_MAX_FILES | Log files kept per container when rotating (current one included) | 3 |
--min-free-disk <SIZE>FERRY_MIN_FREE_DISK | Deploys and new datastores fail early when less disk than this is free on the data directory's (or the local Docker root's) filesystem (e.g. 1G; 0 = no check). Recreating an existing datastore's container isn't blocked | 1G |
--oom-score-adj <N>FERRY_OOM_SCORE_ADJ | Linux: OOM-killer score adjustment of ferryd itself, -1000..=1000 (negative = killed after the containers when the host runs out of memory; 0 = leave unchanged). Lowering it needs root or CAP_SYS_RESOURCE (or OOMScoreAdjust= in a systemd unit) | -500 |
--take-over | Take ownership of Docker resources (with this name prefix) that another Ferry data directory owns — e.g. after restoring a backup into a new data directory or losing the old one (moving a data directory keeps ownership) |
ferryd start
Start the server in the background.
Gives the terminal back once the server listens, or says why it didn't start. The server's output goes to <data-dir>/ferryd.log.
Usage
ferryd start [OPTIONS]Options
The same options as ferryd without a command.
ferryd run
Run the server in the foreground.
Until Ctrl-C or SIGTERM: for a service manager (systemd, launchd), a container, or to watch the server's log in the terminal.
Usage
ferryd run [OPTIONS]Options
The same options as ferryd without a command.
ferryd stop
Stop the server.
Asks the server that uses the data directory to shut down, and waits until it has. Running it again while the server shuts down forces the server to exit at once, like a second Ctrl-C.
Usage
ferryd stop [OPTIONS]Options
| Option and environment variable | Description | Default |
|---|---|---|
--data-dir <DATA_DIR>FERRY_DATA_DIR | Data directory of the server | ./ferry-data |
ferryd status
Say whether the server runs.
Prints where the server that uses the data directory listens. The exit code is 0 when a server runs and 3 when none does.
Usage
ferryd status [OPTIONS]Options
| Option and environment variable | Description | Default |
|---|---|---|
--data-dir <DATA_DIR>FERRY_DATA_DIR | Data directory of the server | ./ferry-data |
ferryd reset-password
Replace the password of the server's account.
For an administrator who forgot it: asks for the new password (or reads it from standard input when that isn't a terminal) and signs every browser out. Works while the server runs.
Usage
ferryd reset-password [OPTIONS]Options
| Option and environment variable | Description | Default |
|---|---|---|
--data-dir <DATA_DIR>FERRY_DATA_DIR | Data directory of the server | ./ferry-data |
ferryd logs
Print the log of a server started in the background
Usage
ferryd logs [OPTIONS]Options
| Option and environment variable | Description | Default |
|---|---|---|
--data-dir <DATA_DIR>FERRY_DATA_DIR | Data directory of the server | ./ferry-data |
-f, --follow | Keep printing what the server logs, until Ctrl-C | |
-n, --lines <N> | Lines to print from the end of the log | 100 |