FerryDocs
Help

Glossary

Each technical name in these docs, with a short definition.

Edit on GitHub

In a page, a name with a dotted line has a definition. Put the pointer on the name to read it.

account
The one administrator of a Ferry server: an email and a password. You sign in to the dashboard with it.
account endpoint
An API address below /api/v1/auth. These addresses control the password, the sessions and the API tokens.See also: endpoint
actual state
What runs at this moment: the containers and the ports that Docker reports.See also: desired state, reconciler
alias
A name that Docker gives to a container on a network. Other containers use this name, not an IP address.See also: private network
Alpine
A small Linux system. An image that is built on Alpine uses less disk space.See also: image
apex domain
The domain itself, with no name before it: example.com. DNS providers write it as @.See also: subdomain
API
Application programming interface: the HTTP addresses that programs call to control Ferry. The CLI and the dashboard use the API.See also: API token
API token
A secret text that proves who you are to the API. Programs send it with each request.
apply
The operation that reads a blueprint, then creates what is not there and updates what changed.See also: blueprint, dry run
archive
One file that contains many files and folders. A .tar.gz archive is also compressed.
Argon2id
A hash function for passwords. It is slow on purpose, so an attacker cannot try many passwords quickly.See also: SHA-256
arm64
A type of CPU. Many low-cost cloud servers and the newer Raspberry Pi boards use it. On Linux, uname -m calls it aarch64.See also: x86_64
auto-deploy
A setting of a service. When it is on, a push to the branch starts a deploy.See also: webhook
autoscaling
A system that changes the number of instances by itself when the load changes. Ferry does not have it.See also: scaling
background
A program in the background does not keep the terminal. You can close the terminal and the program continues.See also: foreground
background worker
A service that runs all the time and has no port. It does work that no request waits for.
backup
A copy of your data that you keep in a different place. You use it to get the data back after a loss.
base domain
The first domain of a Ferry server. It comes from ferryd --base-domain. Its default is localhost.See also: domain of the server
base image
The image that a Dockerfile starts from. It contains a small system and the tools of one language.See also: Dockerfile
base URL
The start of each URL of the API: the address of the server, then /api/v1.
bearer token
A token that a client sends in the header Authorization: Bearer <token>.See also: API token
binary
The program file that a compiler makes from Go or Rust code. It runs without the compiler.
blue-green deploy
A deploy that starts the new instances next to the old instances, then moves the traffic. It is the default.See also: zero downtime, recreate
blueprint
A YAML file (ferry.yaml or render.yaml) that describes your services and datastores. Ferry creates or updates them from the file.
body
The data of an HTTP request or answer. It comes after the headers.
branch
One line of work in a git repository. Ferry deploys the newest commit of the branch that you choose.
bridge network
A network that Docker makes inside one machine. The containers on it can call each other. Other machines cannot reach it.See also: private network
build
The step that makes an image from your code.See also: image, runtime
build cache
The layers that Docker keeps from earlier builds. Docker uses a layer again when its step did not change.
build context
The folder of files that Ferry gives to the build: the repository, or its root directory.See also: build
build secret
A value that Docker gives to one build step only. Docker does not record it in the image.
camelCase
A way to write a name of many words with no space. Each word after the first starts with a capital letter: healthCheckPath.See also: snake_case
capability
One special right that Linux gives to a program. CAP_NET_BIND_SERVICE lets a program listen on the ports below 1024.
cargo
The build tool of Rust. It makes the Ferry programs from the source code.
certificate
A file that proves that a server owns a domain. HTTPS needs one. Ferry gets certificates from Let’s Encrypt.See also: Let’s Encrypt
checksum
A short value calculated from a file. When one byte of the file changes, the checksum changes.See also: SHA-256
CI
Continuous integration: a system that runs your tests after each push. GitHub Actions is a CI system.
clear text
Data with no encryption. Each machine on the network path can read it.See also: HTTPS
CLI
Command-line interface: the ferry command. You type commands in a terminal and the CLI sends them to the server.See also: ferryd
command palette
A search box that opens on top of the page. You type a name, then it opens a page or starts an action.
commit
One saved version of the code in git. A commit has an identifier named SHA.
config file
The file where ferry login saves the server URL and the API token: ~/.config/ferry/config.json.See also: API token
connection pooler
A program between your apps and a database. With it, many app connections share a small number of database connections.
connection string
One URL that contains all that an app needs to connect to a database: user, password, host, port and database name.See also: datastore
container
A process that Docker starts from an image and keeps apart from the other processes of the machine.See also: image, instance
CORS
Cross-origin resource sharing: headers that let a page of another origin call an API from a browser. Ferry sends none.See also: origin
CPU limit
The most CPU time that one container can use. At the limit, the container becomes slower. It does not stop.
crate
A package of Rust code. A crate is a library that other crates use, or a program.
cron expression
Five fields that give a schedule: minute, hour, day of month, month and day of week.See also: schedule
cron job
A service that runs a command on a schedule (for example each night), then stops.
curl
A command that sends one HTTP request and prints the answer.
custom domain
One more hostname that you add to one service, for example www.example.com.See also: domain of the server
dashboard
The web pages of your Ferry server. You use them in a browser to create and control services.
dashboard host
The hostname on which the proxy serves the dashboard and the API. It comes from ferryd --dashboard-host.
data directory
The folder where ferryd keeps its state: the database, the logs, the uploads and the certificates. The default is ./ferry-data.
datastore
A Postgres or Redis database that Ferry runs for you, with its data on a volume.See also: volume
default domain
The domain of the server that Ferry uses when it shows the URL of a service.See also: domain of the server
degraded
The state of a service that runs fewer instances than you asked for.See also: reconciler
delivery
One webhook request from GitHub. The header X-GitHub-Delivery gives its id.See also: webhook
deploy
One release of a service. Ferry builds an image, starts new instances, tests them, then sends the traffic to them.See also: build, health check
deploy hook
A secret URL. A request to this URL starts a deploy of one service.
deploy log
The log of one deploy: the build output and the steps that Ferry does.See also: log, deploy
deploy worker
A background task of the engine. It runs the deploys of one service, one at a time, in order.
desired state
What must run, as written in the Ferry database: services, live deploys, number of instances.See also: reconciler
disk
Storage for one service that stays between deploys. It is a Docker volume at a path that you choose.See also: volume
DNS
Domain Name System: the directory of the internet. It gives the IP address of a server for a domain name.
DNS provider
The company where you manage the DNS records of your domain. Frequently, it is the company that sold you the domain.
DNS zone
All the DNS records of one domain at your DNS provider.See also: DNS provider
Docker
The program that builds images and runs containers. Ferry tells Docker what to do.See also: image, container
Docker context
A name in Docker for one daemon and its address. Colima and OrbStack each make a context.
Docker daemon
The part of Docker that stays in the background. It builds images and runs containers when a program asks.See also: Docker socket
Docker Desktop
The Docker app for macOS and Windows. It runs the containers in a virtual machine.See also: virtual machine
Docker root directory
The folder where Docker keeps its images, containers and volumes.
Docker socket
A special file on the machine. Programs talk to the Docker daemon through it.
Dockerfile
A text file with the steps that build an image.See also: image
domain of the server
A domain that Ferry serves all public services under. With example.com, a service named shop answers at shop.example.com.See also: base domain, custom domain
dry run
A test of a blueprint. It shows what Ferry will create or change, and it changes nothing.See also: blueprint
endpoint
One address of an API, for example /healthz.See also: API
engine
The part of ferryd that runs the deploys, the reconciler, the cron jobs and the datastores. Its crate is ferry-engine.See also: reconciler, deploy worker
env group
A set of environment variables with a name. You link it to all the services that need the same values.
environment
A group of services and datastores with its own private network, for example production or staging. Each environment can use the same names. Names do not resolve from one environment to another.See also: private network, staging
environment variable
A value with a name that Ferry gives to your app when it starts. Example: DATABASE_URL.See also: env group, reference
EventSource
The object of a browser that reads a Server-Sent Events stream. It connects again by itself. It cannot set headers.See also: Server-Sent Events
exit code
The number that a command gives to the shell when it stops. 0 is a success. Each other number is a failure.
external URL
The connection string for the server itself. Its host is 127.0.0.1, with a port of the server.See also: connection string, host port
Ferry key
A blueprint key that Ferry adds to the render.yaml format: port, memoryLimit and cpuLimit. Render has no such key.See also: blueprint
ferryd
The Ferry server. It is one program that runs on your machine and controls Docker.See also: CLI, dashboard
firewall
A filter that blocks the network connections to a machine, but not on the ports that you open.See also: port
foreground
A program in the foreground keeps the terminal and writes its output there until it stops.See also: background
generated secret
A random value of 64 hex characters (256 bits). Ferry makes it for a variable that has generateValue: true.
git connection
A GitHub or GitLab account that gave your Ferry server the permission to read its repositories.See also: repository
git submodule
A git repository that is a folder of another git repository.See also: repository
GitHub App
An application on GitHub that belongs to your account. Ferry creates one for your server. It reads only the repositories that you choose.See also: git connection
glibc
The C library of most Linux systems. A program built with one version runs with that version or a newer one.
grace period
The time that a container has to stop by itself. After that time, Docker stops it by force.See also: SIGTERM, SIGKILL
graceful shutdown
A stop in order: the server completes the requests in progress, then closes each part, then exits.
hash
A text that a program calculates from a password. The program can compare it, but nobody can read the password from it.
health check
The test that tells Ferry that a new instance can receive traffic.
hex character
One of the 16 characters 0 to 9 and a to f. Programs write random values and hashes with them.
HMAC
A signature that the sender calculates from a message and a shared secret. The receiver calculates it again and compares.See also: webhook
Host header
The header of a request that gives the hostname that the client wants. The proxy reads it to find the service.See also: hostname
host port
A port of the server that Docker connects to a port of a container.See also: port
hostname
The name of a machine or a site on a network, for example api.example.com.
HTTP-01 challenge
The test of ACME: the certificate authority asks the host for a secret file on port 80. A correct answer proves control of the hostname.
HTTPS
HTTP with encryption. The browser and the server use a certificate to keep the traffic private.See also: certificate
icon rail
The column of icons on the left side of the dashboard. Each icon opens one main page.See also: dashboard
id
The identifier that Ferry gives to a resource: a prefix and 20 hex characters, for example srv-60f5973b037e4478ae7b.
image
A package that contains your app and all that the app needs to run. Docker starts containers from an image.See also: container, build
image history
The list of the steps that made an image. Each person who has the image can read it.See also: image
install script
The file install.sh of each release. With one command, it installs Ferry on a server or upgrades it.
instance
One running container of a service. A service can have many instances that do the same work.See also: container
instance_id
The file of the data directory that holds the identity of one Ferry server.
internal URL
The connection string for the private network. Its host is the name of the datastore, for example app-db:5432.See also: connection string, private network
IP address
The number of a machine on a network, for example 203.0.113.10. Machines use it to find each other.See also: DNS
IPv6
The newer format of IP addresses, for example 2001:db8::10. An AAAA record gives an IPv6 address. An A record gives an IPv4 address.See also: IP address
job
A command that runs one time in a new container of a service, then stops.
job log
The output of one job run.See also: log, job
journal
The place where systemd keeps the output of the programs that it runs. The command journalctl reads it.See also: systemd
JSON
A text format for data that programs read. Example: {"name": "api", "state": "live"}.
kernel
The center of the operating system. It gives memory and CPU time to each process, and it applies the limits.
key value store
The name that Render gives to a Redis database. On Ferry, it is a Redis datastore.See also: datastore
KiB
Kibibyte: 1024 bytes. 32 KiB is 32,768 bytes.
label
A key and a value that Docker keeps on a container. Ferry reads the labels to find its own containers.
latency
The time that a service takes to answer a request. Ferry measures it until the headers of the answer go out.
Let’s Encrypt
A free service that gives HTTPS certificates. It first tests that your server controls the domain.
live deploy
The deploy of a service that gets the traffic now. A service has one live deploy at most.See also: deploy, snapshot
liveness probe
A small request that tells you if a program is alive.
local name
A name that has no public DNS: localhost, *.localhost, *.local, *.internal and *.test. It gets no certificate.See also: localhost
localhost
The name of your own machine. 127.0.0.1 is its address. Other machines cannot connect to it.
lock
A mark on a file that one program holds. It tells other programs that the folder is in use.
log
The lines of text that a program writes while it runs. You read them to know what occurred.
marker volume
The Docker volume <prefix>-owner. It records which data directory owns the name prefix.See also: instance_id
memory limit
The most memory that one container can use. Above it, the kernel stops the process of the container.See also: OOM kill, resource limit
merged environment
All the variables that a service gets: the injected variables, then its env groups, then its own variables.
MiB
A unit of memory and of disk space. 1 MiB is 1024 × 1024 bytes. 1 GiB is 1024 MiB.
migration
A script that changes the structure of a database, for example to create a table.
millicore
One thousandth of a CPU core. 500m is 500 millicores: half a core.
monorepo
One repository that contains many apps, each in its own folder.See also: root directory
mount path
The folder in the container where the disk shows, for example /data.See also: disk
name prefix
The start of the name of each Docker resource of one Ferry server. The default is ferry.
NAT
Network address translation: a router gives one public address to machines that have private addresses.
nginx
A web server program. Ferry uses it to send the files of a static site to the browser.See also: static site
npm
The package tool of Node.js. It gets the libraries of a project and runs its build.
OAuth application
An application that you create on GitLab for your server. After you authorize it, Ferry can read your repositories. Ferry never gets your password.See also: redirect URI
one-off job
A command that you start one time with ferry run. It runs in a new container of a service, then stops.See also: run
OOM kill
Out of memory: the system stops a container that uses more memory than its limit.
OOM watcher
A task of the engine that listens to the oom events of Docker. It writes a warning in the server log for each kill.See also: OOM kill
OpenAPI document
A file that describes each address of an API in a standard format. Tools such as Swagger UI read it.See also: API
origin
The scheme, the host and the port of a web page, for example https://ferry.example.com. A browser keeps pages of different origins apart.
orphan
A container of this server whose service or datastore does not exist. The reconciler removes it.
PATH
The list of folders where the terminal looks for a program when you type its name.
pg_dump
The Postgres tool that writes a full database into one file. The tool psql loads the file into another database.
pinned image
An image that Ferry keeps with a tag of its own for one deploy. This deploy always runs the same image.See also: tag
polling
To ask the server again at a fixed interval, to see if something changed.
port
A number that identifies one program on a machine for network connections. Your app listens on a port.
Postgres
A database that keeps data in tables. Apps read and change the data with SQL.See also: datastore
private key
The secret half of a pair of keys. The program that has it can prove its identity or read encrypted data.
private network
A Docker network that only your services and datastores are on. They call each other by name, for example api:3000.
private service
A service with a port but no public URL. Only your other services can call it.See also: private network
Procfile
A text file named Procfile. Each line has a name and a start command, for example web: python app.py.See also: start command
Prometheus
A monitoring program that you install yourself. It collects the numbers of your programs at regular intervals, keeps them, and sends alerts.
proxy
The part of Ferry that receives each HTTP request and sends it to an instance of the correct service.
psql
The command-line client of Postgres. It sends SQL to a database.
public URL
The address that a browser on the internet uses to open your service, for example https://shop.example.com.See also: hostname
push
The git command that sends your commits to the repository on GitHub or GitLab.See also: commit
query string
The part of a URL after the ?, for example ?key=abc.
quota
A limit on the disk space that one container or one volume can use. Ferry sets none.
rate limit
The largest number of requests that a service accepts in a period of time.
reconciler
The loop in Ferry that compares what must run with what Docker runs, then repairs the difference.
recreate
A deploy that stops the old instance before it starts the new instance. Ferry uses it for a service with a disk.See also: disk
redirect
An answer that tells the browser to go to another URL. Ferry uses the status code 308 to send HTTP to HTTPS.See also: status code
redirect URI
The address that the provider sends your browser back to after you authorize.
Redis
A database that keeps keys and values in memory. Apps use it as a cache or as a queue.See also: datastore
reference
A value written as ${{…}}. Ferry replaces it with the real value (for example a database URL) when the service starts.
registry
A server that stores images. Docker Hub is a registry.See also: image
Render
A company that runs apps on its own servers. Ferry does the same work on a server that you control.
replica
A second database server that keeps a copy of the data of the first server.
repository
A folder of code with its history, kept by git. Also called a repo.See also: branch, commit
resolve
A name resolves to an address when the DNS gives this address for the name.See also: DNS
resource limit
The most memory and CPU that one container can use.See also: OOM kill
REST API
An API that uses plain HTTP requests. The URL names a resource. The method (GET, POST, DELETE) names the action.See also: API
restart
A deploy that uses the live image again, with the current settings and variables. Nothing is built.
reverse proxy
A program that receives the requests from the internet and sends them to another program. nginx, Caddy and Traefik are reverse proxies.See also: proxy
RFC 3339
A standard text format for a date and a time, for example 2026-09-27T07:38:34.231568Z.See also: timestamp
rollback
A deploy that uses the image of an earlier deploy again.
root
The administrator account of a Linux machine. It can read, change and delete all things.See also: sudo
root directory
The folder of your code where Ferry builds the service. The default is the top of the repository.See also: monorepo
round-robin
A rule of turns: the first request goes to the first instance, the next request to the next instance, then the list starts again.
route table
A list in the memory of ferryd. For each hostname, it gives the addresses of the instances. The proxy reads it for each request.See also: proxy
route watcher
The loop in Ferry that lists the instances each second and updates the routes of the proxy.
run
One execution of a job: one new container, one command, one log and one exit code.See also: job, one-off job, cron job
runtime
The language environment of your app (Node, Python, Go, Rust, Ruby, static). Ferry finds it from your files and writes the Dockerfile.
runtime log
What the containers of a service write while they run. Docker keeps it as long as the containers exist.See also: log, stdout, stderr
scaling
A change of the number of instances of a service.See also: instance, autoscaling
schedule
The times at which a cron job runs. You write it as a cron expression, for example 0 3 * * *.See also: cron job, cron expression
scheduler
The part of Ferry that starts a run of a cron job at each time of its schedule.See also: schedule
secret file
On Render, a file with secret text that the host puts in the container of a service.
self-hosted
You run the program on a machine that you control, not on the machines of a company.
self-signed certificate
A certificate that a server makes for itself. No certificate authority signed it, thus browsers show a warning.See also: certificate
server log
The log that ferryd writes about its own work: failed deploys, OOM kills, proxy warnings.See also: ferryd
server token
An API token that ferryd writes in its data directory at the first start. Scripts on the server use it.See also: API token
Server-Sent Events
SSE: one HTTP answer that stays open. The app sends new lines of data to the browser when it has them.
service
One app that Ferry builds and runs for you. A service has a name, a type, a source and settings.See also: instance, deploy
service lock
A lock that each service has. Only the operation that holds it can change the containers of the service.See also: reconciler
service manager
A system program that starts other programs and starts them again after a crash: systemd on Linux, launchd on macOS.See also: systemd
service type
The kind of a service: web service, private service, background worker, cron job or static site.See also: service
session
The time that one browser stays signed in to the dashboard. A cookie in the browser identifies it.
setup code
A secret code that ferryd makes while the server has no account. You need it to create the account.
SHA-256
A function that calculates a fixed value (a hash) from a text. Nobody can get the text back from the hash.See also: Argon2id
shell
The program that reads the commands that you type in a terminal, for example bash or zsh.
SIGKILL
The signal that stops a process immediately. The process cannot refuse it.See also: exit code
SIGTERM
The signal that asks a program to stop. The program can save its work first.See also: SIGKILL, grace period
snake_case
A way to write a name of many words: lower case, with _ between the words, for example base_domain.See also: camelCase
snapshot
The exact image, variables, command and limits of a live deploy. Ferry saves them and uses them for each new container of that deploy.
source
Where the code of a service comes from: a git repository, a Docker image or an upload.See also: repository, image
SQLite
A small database that is one file. Ferry keeps its own data (services, deploys, settings) in it.
SSH tunnel
A safe connection through SSH that makes a port of the server available as a port of your machine.
staging
A second copy of your setup where you test a change before it goes to production.
start command
The command that starts your app in each container, for example npm start.See also: Procfile
static site
A service that is only files (HTML, CSS, JavaScript). Ferry serves the files with nginx.
status code
The number at the start of an HTTP answer. 200 is a success, 404 is "not found", 503 is "not available".
stderr
Standard error: the channel where a program writes its errors and its progress messages.See also: stdout
stdout
Standard output: the channel where a program writes its results. A pipe (|) sends it to the next command.See also: stderr
store
The part of Ferry that reads and writes the SQLite file ferry.db. It has the desired state.See also: SQLite, desired state
subdomain
A name under a domain. shop.example.com is a subdomain of example.com.
sudo
A Linux command that runs one other command as root.See also: root
Swagger UI
A web page that lists each endpoint of an API. You can try the endpoints from the page.
system user
A Linux account for a program, not for a person. No person can log in with it.
systemd
The Linux program that starts services when the machine boots and starts them again after a crash.
tag
The part of an image name after the :. It names one version of the image, for example alpine in nginx:alpine.See also: image
timestamp
The date and time when a line was written.
trigger
The cause of a deploy: a command, a push to git, a change of variables, and so on.
unit
A file that tells systemd how to start, stop and supervise one program.See also: systemd
UTC
Coordinated Universal Time: the reference time of the world. It has no summer time.
virtual machine
A computer that software makes inside a real computer. It has its own system, CPUs and memory.
volume
A folder that Docker keeps on the server when a container is removed. Data on a volume stays.See also: disk
web service
A service that answers HTTP requests and has a public URL.
webhook
An HTTP request that one system sends to another when something occurs. GitHub sends a webhook to Ferry after each push.
webhook secret
A secret text that GitHub and ferryd share. GitHub signs each webhook with it.See also: webhook
wildcard DNS record
A DNS record for *.example.com. It answers for each name under the domain, thus a new service needs no new record.
x-ferry-error
A header that the proxy adds when it answers with its own error page. Your app does not send it.See also: proxy
x86_64
The type of CPU in most PCs and servers, from Intel and AMD. It is also called amd64.See also: arm64
YAML
A text format for settings. Each line is key: value. The indentation shows what is inside what.See also: blueprint
YAML anchor
A name for a block of YAML, written &defaults. <<: *defaults copies the block to another place of the file.See also: YAML
zero downtime
Your app answers during the full deploy. The old instances stop only after the new ones are ready.

Troubleshooting

Find the message that you see, then read its cause and the fix.