Multiple servers

More than one ferryd can share one Docker daemon. For example, run a staging server next to your production server on the same machine. Or run a temporary server for tests next to your real server. To test changes on one server with one account, an environment is simpler.

ferryd --data-dir /var/lib/ferry-staging \
  --name-prefix staging \
  --api-addr 127.0.0.1:7879 \
  --proxy-addr 0.0.0.0:8081 \
  --base-domain staging.localhost

This command starts a second server, staging. The production server keeps the defaults: the prefix ferry, the API on port 7878 and the proxy on port 8080.

Run a second serverCopy Anchor Link

Each server must have its own values for these options:

After the start:

• Account. Each server has its own account, sessions and API tokens, in its own data directory. At its first start, the staging server prints its own Create your account link, at its own API address: http://127.0.0.1:7879/setup?code=….
• Apps. The apps of the staging server are at http://<name>.staging.localhost:8081.
• Stop, status, logs. ferryd stop, ferryd status and ferryd logs act on the server of the data directory that you give.

ferryd stop --data-dir /var/lib/ferry-staging

This command stops staging. Production continues to run.

On a public server, give the second server its own base domain, for example --base-domain staging.example.com. Put it on a different port or on another IP address.

Choose the server in the CLICopy Anchor Link

The CLI saves one server when you run ferry login. A command with no option goes to this server. A flag or an environment variable sends one command to another server:

FERRY_SERVER=http://127.0.0.1:7879 FERRY_TOKEN=$(cat /var/lib/ferry-staging/api_token) ferry ls
ferry --server http://127.0.0.1:7879 --token fy_… ls

The saved server does not change. The next command with no option goes to production again. A token works only on the server that it belongs to.

ferry login --server http://127.0.0.1:7879 also works. But it replaces the saved server.

Give each server its own name prefixCopy Anchor Link

The name prefix (default ferry) is part of each Docker name that a server creates:

Outside production, <service> and <name> also have the name of the environment: api.staging. Thus the same name in two environments gets two sets of Docker names.

Each container also has the label ferry.instance=<prefix>. A server lists and controls only the containers with its own prefix.

Two servers must never share a prefix. The reconciler of a server removes the containers under its prefix that it does not know. Each such container is an orphan. With the same prefix, each server deletes the apps of the other.

With different prefixes, the servers stay apart. They have different networks, thus their services cannot call each other by name. They also have different images and volumes.

The safety checksCopy Anchor Link

At each start, ferryd makes sure that no other server uses its data directory or its prefix. If a check fails, ferryd does not start.

One server for each data directory. ferryd holds a lock on <data-dir>/ferryd.lock.

Error: another ferryd is already running with data directory /var/lib/ferry

One data directory for each prefix. At its first start, a server writes its identity and its data directory on the marker volume <prefix>-owner. Its identity is the file <data-dir>/instance_id. After that, a server with another data directory refuses the prefix.

Error: Docker resources with prefix 'ferry' belong to another Ferry server (data dir /var/lib/ferry). Run this server with a different --name-prefix, stop the other server, or pass --take-over to adopt the resources (the other server's containers will then be managed — and possibly removed — by this one).

An empty data directory. The server refuses to start if its data directory is empty and no marker explains the containers under its prefix.

Error: found 3 Docker container(s) with prefix 'ferry' that this (empty) data dir /home/you/projects/ferry-data doesn't know. They probably belong to another Ferry server. Run this server with a different --name-prefix, …

This check finds a common mistake: you start ferryd from another folder, with the default data directory ./ferry-data. Start it again with the correct --data-dir.

Move a server to another data directoryCopy Anchor Link

This procedure moves the data directory on the same machine.

1. Stop ferryd.
2. Move or copy the full directory. Keep its permissions: mode 0700, and the owner is the user that runs ferryd.
3. Start ferryd with the new --data-dir and the same --name-prefix.

The file instance_id moves with the directory. Thus the server keeps its identity, and it still owns the prefix.

If the server refuses the prefix, the file instance_id did not move. For example, you restored only ferry.db. Then start the server one time with --take-over. The server replaces the marker with its own identity.

Remove a serverCopy Anchor Link

The volumes hold the datastores and the disks of the server. A removal deletes them. If you need this data, back it up first. See Back up the data.

ferryd stop --data-dir /var/lib/ferry-staging

docker ps -aq --filter label=ferry.instance=staging | xargs docker rm -f
docker volume ls -q --filter label=ferry.instance=staging | xargs docker volume rm
docker image ls --filter reference='staging/*' --format '{{.Repository}}:{{.Tag}}' | xargs docker rmi
docker network rm staging