Core concepts
The main names of Ferry, from services and deploys to logs and self-healing, each with its guide.
Ferry is a self-hosted alternative to Render. It runs your apps on one server that you control. It has the same service types as Render and reads the same blueprint file, render.yaml. Ferry v1 has no autoscaling, no pull request previews and no teams.
This page gives each main name of Ferry in a few sentences, with a link to the guide of the task.
Services
A service is one app that Ferry builds and runs as one or more Docker containers. Each service has a name that is unique in its environment, a type, a source, settings and environment variables. The source is a git repository, a Docker image or a folder that you upload. The type tells who can reach the service.
A browser reaches a web service or a static site through the proxy.
| Type | --type | Who can reach it |
|---|---|---|
| web service | web | Each browser, through the proxy |
| static site | static | Each browser, through the proxy |
| private service | pserv | Only your other services |
| background worker | worker | Nothing: it has no port |
| cron job | cron | Nothing: it runs on a schedule |
See Deploy an app.
Deploys
A deploy is one release of a service. Ferry starts the new version next to the old version and tests it with a health check. Then the proxy moves the traffic, and Ferry stops the old version. If the new version fails, Ferry removes it, and the old version stays online. Ferry keeps each deploy, thus a rollback can bring an earlier version back.
See Deploys and rollbacks and Auto-deploy from GitHub.
Builds
A build makes a Docker image from your code. It is the first step of each deploy from git or from an upload. Ferry finds the runtime of your code: Node.js, Python, Go, Rust, Ruby or static files. Then it writes the Dockerfile for you. If your code has its own Dockerfile, Ferry uses it.
A service from a prebuilt image has no build. See Deploy an app.
Networking and domains
Each server runs one proxy. The proxy receives all the public traffic and sends each request to a container of the correct service. Behind the proxy, the containers of an environment share a private network. There, a service calls another service by its name and port, for example api:3000. Each web service and static site gets a URL. You can add your own domain with automatic HTTPS.
See Domains and HTTPS.
Environments
Each service and each datastore belongs to one environment. Each server has production. Create staging next to it to test a change before it goes live. Staging can use the same names as production. The containers of staging cannot reach production by name. Outside production, the URL of a service has the name of its environment: shop.staging.example.com.
See Environments.
Variables
Each service has its own environment variables. To share variables, put them in an env group and link the group to your services. A value can be a reference to a datastore or to another service, in the form ${{…}}. Ferry puts the real value there when the service starts. ferry env set restarts the service to apply a change.
Datastores
A datastore is a Postgres or Redis server that Ferry runs for you. It is one container, with its data on one Docker volume. Your services reach it by its name on the private network: this is its internal URL. Ferry makes no backup of a datastore. Make your backups yourself.
See Databases.
Jobs
A run is one container that runs one command, then stops. You start a one-off job with ferry run, for example for a database migration. A cron job starts on its schedule, for example each day at 03:00 UTC. Each run ends as succeeded, failed or canceled, and has its own log.
See Jobs.
Scaling and limits
A service can run more than one instance, and the proxy shares the requests between them. ferry scale api 3 changes the number of instances, with no new build. ferry suspend stops all the instances, and ferry resume starts them again. Each container also has a resource limit of memory and CPU, by default 512 MiB and 1 CPU. Thus an app with a bug cannot stop the server, ferryd or your databases.
See Scaling and limits.
Logs
Ferry keeps three logs. The deploy log has the build output and the steps of one deploy. The runtime log has what your instances write while they run. The job log has the output of one job run. You can read a log when it is complete, or follow it live with -f.
See Logs.
Self-healing
Ferry keeps the desired state in its database: the services, their live deploys, their number of instances and the datastores. Each 10 seconds, the reconciler compares it with the actual state in Docker and repairs each difference. Thus you do not restart a crashed app, and you do not remove old containers. If ferryd stops, your containers continue to run.
See Architecture.