Skip to content

Install Shipwick on a server ​

Wick, the Shipwick flame, with tools: setting up the server

One command sets up a server: from your laptop over SSH, or on the server itself. This page covers both, what the installer needs and puts on the machine, the API token, DNS, Cloudflare and the firewall, and the ways to install without it.

Before you begin ​

You need:

  • A Linux server you can reach as root over SSH, with a public address. Ubuntu or Debian is the well-trodden path; any Linux with Docker works. Create the server with your SSH public key selected, so that it is in /root/.ssh/authorized_keys from the first boot: on Ubuntu images root has no password and logs in with a key only. And open ports 80 and 443 over TCP and 443 over UDP in the firewall the provider offers beside the machine, before the first command: a closed one is silence, not a refusal, and no certificate is ever issued through it. Both are set at the provider; see Prepare a server.
  • Docker Engine with the Compose plugin on it, the plugin in version 2.23.1 or later: see What the server needs. shipwick server install, from your laptop, installs Docker when it is missing. The installer run on the server itself does not: that decision belongs to the server's owner there, and it stops and points you to curl -fsSL https://get.docker.com | sh.
  • curl or wget on the server.
  • Ports 80 and 443 free on the server and reachable from the internet. Automatic HTTPS depends on them, so Shipwick cannot share a server with another web server, reverse proxy or deployment platform that holds them. The installer checks this first and changes nothing if a port is taken.
  • Two DNS names that point at the server: one for the API, one for the dashboard. Both are optional, and both are what makes the rest comfortable: without the first, shipwick reaches the server only through an SSH tunnel. Every application you give a domain later needs a DNS record too.

A server whose way to the internet is a proxy, or that has none, is covered in Run behind a corporate proxy or without internet. To run the agent as a systemd service of the host instead of a container, see Install from a package.

Run the installer from your laptop ​

The shortest way: nothing to type on the server, and the token is saved for you. With the CLI installed on your machine:

bash
shipwick server install [email protected] \
  --agent-domain agent.example.com \
  --dashboard-domain dashboard.example.com

It connects with your own ssh (a key that logs in without a password; the command runs ssh with BatchMode=yes and fails instead of asking for one, and accepts a server's host key on first contact while refusing one that changed), installs Docker with get.docker.com when it is missing, runs the installer with those hostnames, saves the token it prints as a context named after the host and makes it current, probes ports 80 and 443 from your machine, and ends with the DNS records to create and how to sign in to the dashboard:

text
✓ Connected to [email protected] (x86_64)
✓ Docker 29.8.0
Running the Shipwick installer...
  ✓ Installed /opt/shipwick/compose.yml
  ✓ Wrote /opt/shipwick/.env
  ✓ Started the Shipwick services
  ✓ The agent is healthy
  ...
✓ Shipwick is running on [email protected]
✓ Saved the API token as context 203.0.113.10 (https://agent.example.com), now current
✓ Port 80 open on 203.0.113.10
✓ Port 443 open on 203.0.113.10

Create these DNS records, DNS only (not proxied):
  A     agent.example.com  →  203.0.113.10
  A     dashboard.example.com  →  203.0.113.10

Dashboard: https://dashboard.example.com
  It asks for a token; make it one of its own: shipwick token create dashboard --role admin
  (not the root token from /opt/shipwick/.env, which is root on the server and never leaves it)

Next: in your project, run: shipwick init
      once the records exist, check the setup with: shipwick doctor
Flag
--agent-domain <host>Hostname for the API. Without it the API is not exposed, and the context points at http://127.0.0.1:9000 for the SSH tunnel
--dashboard-domain <host>Hostname for the dashboard
--name <name>Name to save the server under; default: its hostname. Since 0.10; it was --context, which shadowed the global flag
--version <tag>Release to install, such as v1.1.0; default: the latest

The remote commands are fixed; the hostnames and the version are validated first and reach the installer as environment assignments. Running the command again upgrades the server: the token is then unchanged and not printed again, and the context keeps the one it has.

The two port lines are a probe from your machine, made once the installer is done, since 0.9: a connection to 80 and to 443 at the server's address, with nothing sent. A port that answers is open; one that refuses the connection has nothing listening, which right after a healthy agent means the proxy is not up yet; one that stays silent for three seconds is behind a firewall that drops the packets — on a server that was just created, the provider's firewall beside the machine (Hetzner Cloud Firewall, an AWS security group, a DigitalOcean cloud firewall), which has to admit 80 and 443 over TCP and 443 over UDP. Certificates cannot be obtained until it does, and the command says so rather than leaving it to Caddy's log.

When ssh itself fails, before any command runs, the command says what the failure means and what to do (since 0.9). Permission denied is a server that does not know the key ssh offered: the command runs ssh once more with -v, names the key files it offered — the public half, with its fingerprint — and gives the three ways to put a key on a server nothing of yours gets into yet: select it when the server is created at the provider, paste it through the provider's console or rescue system, or use the provider's own key installation. Where the server would also take a password, ssh-copy-id is named as the way to put the key there once; shipwick never types one. A host key that changed is a server that was rebuilt, with the ssh-keygen -R line to forget the old key — or something in the middle, which only you can tell. A connection refused is a server still starting or SSH on another port, named in ~/.ssh/config; a connection that times out is a wrong address, another port, or a firewall that admits SSH from certain addresses only; a name that does not resolve is said as such.

Then go on to Your first deployment; the rest of this page is for when you want to know more.

Change a setting later ​

The agent's settings are the SHIPWICK_* variables of /opt/shipwick/.env, listed below. Changing one by hand is SSH, an editor and a compose command; since 0.9 it is one command from your machine:

bash
shipwick server configure [email protected] SHIPWICK_WEBHOOK_URL=https://hooks.example.com/shipwick SHIPWICK_WEBHOOK_SECRET=…
shipwick server configure [email protected] --unset SHIPWICK_WEBHOOK_SECRET      # or SHIPWICK_WEBHOOK_SECRET=
text
✓ /opt/shipwick/.env on [email protected]: SHIPWICK_WEBHOOK_URL changed, SHIPWICK_WEBHOOK_SECRET added
✓ The agent is healthy

Each KEY=value sets or replaces that line of .env, KEY= or --unset KEY removes it; then docker compose up -d runs there, which recreates the agent with the new environment, and the command waits for it to be healthy the way the installer does. It ends with what changed, by name; values are never printed, and never become part of a command — they go to the server as data, on the standard input of a fixed script, so a value may hold anything but a line break. The file keeps its mode, 0600; the token in it is not touched. A name has to be one of the settings compose.yml reads from .env — the ones install.sh --help lists, and the two hostnames; a misspelt one, or one the compose file does not pass on, would sit in the file and change nothing — and a value is checked as the installer checks it, in the installer's words: a Cloudflare token with a quote in it, a hostname with https:// in front, the same hostname for the API and the dashboard. SHIPWICK_AGENT_TOKEN and SHIPWICK_ENCRYPTION_KEY are not settings (shipwick token create, shipwick server rotate-key). When nothing in the file would change, the agent is not restarted, and the command says so. A setting with a next step gets its line: a Cloudflare token is checked with shipwick doctor, a new hostname wants its DNS record. See server configure in the CLI reference.

Run the installer ​

The same installation on the server itself, as root:

bash
curl -fsSL https://get.shipwick.com | sh

The installer asks two questions. Both are optional; press Enter to skip either.

QuestionStored asEffect
Hostname for the API, used by the shipwick CLISHIPWICK_AGENT_DOMAINThe agent's API is served over HTTPS at this hostname, through Caddy
Hostname for the dashboardSHIPWICK_DASHBOARD_DOMAINThe dashboard is served over HTTPS at this hostname, through Caddy

Give bare hostnames such as agent.example.com: no https://, no port, no path. The two must be different. Hostnames are validated before anything is written.

Without a terminal, the installer asks nothing and takes the hostnames from the environment:

bash
curl -fsSL https://get.shipwick.com | SHIPWICK_AGENT_DOMAIN=agent.example.com SHIPWICK_DASHBOARD_DOMAIN=dashboard.example.com sh

The installer prints the API token once; you sign in from your laptop with it, shipwick login --url https://agent.example.com. The output looks like this:

text
Shipwick installer (shipwick/shipwick@latest)

✓ Docker 29.8.0 with Compose 5.5.1
  The release's signature was not checked: cosign is not installed. Every file is checked against the release's checksums.
✓ Installed /opt/shipwick/compose.yml
✓ Wrote /opt/shipwick/.env
✓ Started the Shipwick services
✓ The agent is healthy
✓ Installed the shipwick CLI to /usr/local/bin/shipwick
✓ shipwick on this server is signed in

Shipwick is running.

  API token (also in /opt/shipwick/.env — it is root on this server, treat it so):

      <64 hexadecimal characters>

  From your laptop or CI:   shipwick login --url https://agent.example.com
  On this server:           shipwick ps
  Dashboard:                https://dashboard.example.com
                            It asks for a token; make it one of its own:  shipwick token create dashboard --role admin
                            (not the root token from /opt/shipwick/.env, which is root on this server and never leaves it)
  Open ports 80 and 443 (and 443/udp) — and nothing else — in your firewall.
  DNS records must point straight at this server (at Cloudflare: DNS only). To keep
  Cloudflare's proxy on, add SHIPWICK_CLOUDFLARE_API_TOKEN to /opt/shipwick/.env
  and run:   cd /opt/shipwick && docker compose up -d
  Upgrade later by running this installer again.

To keep hostnames behind Cloudflare's proxy from the start, give the installer a Cloudflare API token the way the hostnames are given:

bash
curl -fsSL https://get.shipwick.com | SHIPWICK_CLOUDFLARE_API_TOKEN=... sh

The installer checks that the value has the form of a token — letters, digits, - and _ only, without quotes — before it writes anything, keeps it in /opt/shipwick/.env, and ends with Certificates are obtained through Cloudflare DNS: hostnames may be proxied by Cloudflare. Set the zone's SSL/TLS mode to Full (strict). instead of the three lines about DNS records above. Since 0.9 the agent checks what the token can do when it starts — whether Cloudflare accepts it from the server's address, which zones it sees, and whether it can create a DNS record in each — and the installer prints what it found, the lines shipwick doctor prints about the token, once the agent is up. See Put Cloudflare in front for the token's permissions and the check.

The second line is there on every server without cosign, which is every new one: since 0.8.0 a release is signed, and the installer verifies the signature where cosign is installed. See The signature.

What the server needs ​

Docker Engine and the Compose plugin, the plugin in version 2.23.1 or later: an older Compose cannot read Shipwick's compose file, and the installer says so before it changes anything.

text
Docker Compose 2.17.3 does not accept this release's compose file:
  …
  A Compose older than 2.23.1 cannot read it: upgrade the Compose plugin ('docker-compose-plugin' from Docker's
  repository) and run this installer again. The compose file in use was not replaced.

The Engine may be as old as 20.10, the one Debian 12 packages. Its package brings no Compose plugin, which then comes from Docker's repository.

Before every release the agent's integration tests are run against Docker 20.10, 26.1, 28 and 29, and the installer on Debian 12 and 13, Ubuntu 22.04, 24.04 and 26.04, Rocky Linux 8, 9 and 10, Fedora and Alpine, on amd64 and arm64. The distributions are run as containers there: what is tested is the installer with their shell and tools, not their kernels or their own packages of Docker.

What the installer does not do, and the server needs before it carries real data — SSH keys, security updates, swap, a firewall, backups elsewhere — is in Prepare a server.

What the installer does ​

  1. Checks for Linux, root, a running Docker and the Compose plugin, and that the HTTP and HTTPS ports are free, unless its own Caddy holds them, which is an upgrade.
  2. Resolves latest to a release's tag, once, so that every file comes from that release (since 0.10; before, each file was fetched through GitHub's latest redirect separately). Downloads the release's checksums.txt and, where cosign is installed, verifies the release's signature of it; see The signature. Since 0.10 a download from GitHub that fails is tried again before the installer gives up (curl --retry 3, or wget --tries=3).
  3. Writes /opt/shipwick/compose.yml. This is the release's compose.production.yml, in which the three Shipwick images — the agent, the dashboard and the proxy, Shipwick's build of Caddy — are pinned to the release's version, and, since 1.1, the socket proxy's image, which the agent reaches Docker through, to a version of its own. The file is verified against the release's checksums.txt, and Compose is asked to read it, before it replaces anything.
  4. On the first run only, writes /opt/shipwick/.env with a freshly generated API token and the two hostnames. Settings given in the environment of that run are written there too, so that an upgrade does not lose them: the webhook, the Cloudflare token, the backup passphrase and bucket, the ports, images of your own. The file has mode 0600 and the directory 0700.
  5. Pulls the images and, since 0.10, compares each one's digest with the release's signed image-digests.txt: an image the registry serves under the release's tag that is not the release's is removed again, the compose file that ran is put back and the installer stops with the installation as it was. Since 1.1 the socket proxy's image, pulled from Docker Hub, is held against the release's digests like Shipwick's own three. Images of your own, named in .env, are not compared, and the output says so; releases before 0.7.0 published no digests, so the installer says so and goes on, or stops under SHIPWICK_REQUIRE_SIGNATURE=1. Then starts the services and waits for the agent to report healthy.
  6. On an upgrade, removes the agent, dashboard and proxy images of earlier releases, once the upgraded agent is healthy: Removed 2 image(s) of earlier Shipwick releases. The images that are running, and anything else on the server, are kept.
  7. Installs shipwick to /usr/local/bin, verified the same way. A checksum mismatch installs nothing and leaves a running installation as it was.
  8. With a hostname for the API, signs that shipwick in: see The CLI on the server.
  9. Prints the token, only in the run that generated it, and the next steps.

Four containers run afterwards, defined in /opt/shipwick/compose.yml (three before 1.1, without the socket proxy):

ServiceWhat it is
agentThe Shipwick agent. Since 1.1 it does not hold the Docker socket: it reaches Docker through the filtered socket of socket-proxy, in a volume the two share, and has no other way to the daemon. It publishes no port: the only ways in are Caddy and the server itself. Since 0.8 it listens on a network of its own, shipwick-control, which Caddy and the dashboard are on and no application is; see Who can reach the API.
caddyThe reverse proxy. It publishes ports 80 and 443 (TCP) and 443 (UDP), obtains and renews certificates on its own, and serves the folders of static applications itself. Since 0.5 its image is Shipwick's own build of Caddy, ghcr.io/shipwick/caddy: Caddy with the Cloudflare DNS module and, since 0.8, Shipwick's own way of finding replicas, and nothing else added, on every installation whether or not a Cloudflare token is set.
dashboardThe web dashboard. It is reached only through Caddy, at the dashboard hostname, and has no credentials of its own.
socket-proxySince 1.1. wollomatic/socket-proxy, between the agent and Docker. It holds /var/run/docker.sock, which is root on the server, and answers the agent the calls on its list — a method and a path each — with 403 for every other. It has no network, no capabilities and a read-only filesystem. What that takes away and what it does not: The Docker socket.

State lives in Docker volumes: the agent's SQLite database shipwick.db and its encryption.key in agent-data, certificates in caddy-data, the folders of static applications in caddy-static. The agent creates encryption.key on its first start and encrypts every deployment's env values, and every secret, registry password and certificate key stored on the server, with it before they are written to the database; without the key the database cannot be read, and the agent refuses to start against it. Back up encryption.key together with shipwick.db, back up caddy-data, and do not delete either volume casually. With SHIPWICK_BACKUP_PASSPHRASE set, the agent backs up the database and the key itself, encrypted, once a day, and shipwick doctor says when it does not; the backups it takes are kept in agent-data too, and in a bucket when one is configured. See Back up and restore volumes. caddy-static holds nothing you cannot upload again with shipwick deploy.

The installer accepts these environment variables:

VariableDefault
SHIPWICK_VERSIONlatestRelease to install
SHIPWICK_REQUIRE_SIGNATURE—Since 0.8. Set to 1: install nothing unless cosign is here and verifies the release's signature. Unset, the signature is verified when cosign is installed, and the installer says so when it is not. See The signature
SHIPWICK_AGENT_DOMAIN—Hostname for the API; asked for when run in a terminal
SHIPWICK_DASHBOARD_DOMAIN—Hostname for the dashboard; likewise
SHIPWICK_INSTALL_DIR/opt/shipwickWhere compose.yml and .env are written
SHIPWICK_BIN_DIR/usr/local/binWhere shipwick is installed
SHIPWICK_WEBHOOK_URL—Where the agent posts notifications: a Slack or Discord webhook, or any HTTPS endpoint. Kept in .env when given on the first run; see Get notified
SHIPWICK_WEBHOOK_SECRET—Signs each notification, so your endpoint can tell it came from the agent. Likewise
SHIPWICK_CLOUDFLARE_API_TOKEN—A Cloudflare API token (Zone → Zone → Read and Zone → DNS → Edit, those two exactly): certificates through DNS, so hostnames can stay behind Cloudflare's proxy and can be wildcards. The agent checks what the token can do when it starts, and shipwick doctor on request. Likewise; see Put Cloudflare in front
SHIPWICK_BACKUP_DIR<data dir>/backupsWhere the backups the agent takes are kept, a path inside the agent's container; the host directory is mounted in compose.override.yml. Likewise, since 0.10; before, it had to be set in .env by hand
SHIPWICK_BACKUP_PASSPHRASE—Encrypts the backups the agent takes, and lets it back up its own database and key. Likewise; see Back up and restore volumes
SHIPWICK_BACKUP_S3_ENDPOINT, _BUCKET, _ACCESS_KEY_ID, _SECRET_ACCESS_KEY, _REGION, _PREFIX—An S3-compatible bucket the backups are also sent to. Likewise

SHIPWICK_HTTP_PORT, SHIPWICK_HTTPS_PORT, SHIPWICK_AGENT_IMAGE, SHIPWICK_DASHBOARD_IMAGE, SHIPWICK_CADDY_IMAGE, SHIPWICK_EXPORT_SCHEDULE, SHIPWICK_EXPORT_KEEP and SHIPWICK_STANDBY_SCHEDULE are kept in .env the same way when they are set for the first run, and since 0.7 SHIPWICK_LOG_RETENTION_DAYS, SHIPWICK_LOG_RETENTION_SIZE, SHIPWICK_OIDC_NAME_CLAIM, SHIPWICK_OIDC_TENANTS and SHIPWICK_UPDATE_CHECK, and since 1.1 SHIPWICK_SOCKET_PROXY_IMAGE. What each means is in Agent configuration.

All of these can also be added to /opt/shipwick/.env later, followed by cd /opt/shipwick && docker compose up -d — or, since 0.9, with one command from your machine, shipwick server configure [email protected] SHIPWICK_WEBHOOK_URL=…, which does both; see Change a setting later.

The API token ​

The installer generates the token and prints it once, in the run that created it. It is also in /opt/shipwick/.env.

This is the root token: it has the admin role, its name is root, and it is the one to keep for yourself. Every other token is created from it with shipwick token create, named and given a role — read sees everything, deploy also deploys, rolls back, stops and starts, admin also deletes applications, manages tokens, secrets, registry credentials and certificates, and rotates the encryption key. Give CI a deploy token and put the root token in a password manager. See Create tokens for CI and teammates.

An admin token is root on the server

The agent controls the Docker daemon, and whoever controls the Docker daemon controls the host. Treat the root token, and every admin token, like root SSH access to the server: keep it in a password manager, and keep /opt/shipwick/.env private.

The agent itself keeps only the SHA-256 of each token. Read Security for the full picture.

The CLI on the server ​

The installer puts shipwick on the server too, and since 0.5, with a hostname for the API, it signs it in: it saves https://<that hostname> and the token from .env as a context of the user who runs the installer, root, in the CLI's own configuration file. shipwick ps then works on the server as it does on a laptop, and the summary says so: On this server: shipwick ps.

  • The token goes to the CLI on standard input, never as an argument, through shipwick login --token-stdin --no-check. The context is saved without a request to the agent, so it is there before the hostname's DNS record and certificate are; until they are, commands on the server fail the way they would on a laptop.
  • Run again, on an upgrade, the installer puts the current token back into a context that points at this server, and leaves every other context, and which one is current, as they were. When the context for this server is not the current one, the summary shows the command with it: shipwick --context <name> ps.
  • When only other servers are saved there, it adds nothing and prints the line to add this one: shipwick login --context here --url https://agent.example.com.
  • Without a hostname for the API nothing is saved: the agent publishes no port for the CLI to reach. A command run on the server then says that the agent publishes no port, and how to give it a hostname: set SHIPWICK_AGENT_DOMAIN in /opt/shipwick/.env and run the installer again. See Reach the API without a hostname for the other way.

The agent also knows where the dashboard is: GET /server reports its URL when the dashboard has a hostname, shipwick server status shows it, and shipwick open --dashboard opens it. See Open the dashboard.

DNS and firewall ​

Point DNS at the server for the API hostname, the dashboard hostname, and the domain of every application you deploy: an A record with the server's IPv4 address, and an AAAA record when it has an IPv6 address, both "DNS only", not proxied through a CDN. Caddy obtains a certificate for a hostname once its DNS record resolves to the server and ports 80 and 443 are reachable. A deployment whose hostname is not ready yet succeeds and says which record to create; see DNS first.

At Cloudflare the records must be DNS only, unless the agent has a Cloudflare API token: SHIPWICK_CLOUDFLARE_API_TOKEN, given to the installer like the hostnames, or added to /opt/shipwick/.env later and followed by cd /opt/shipwick && docker compose up -d. Caddy then obtains certificates through a DNS record, and a record may stay proxied. Set the zone's SSL/TLS mode to Full (strict). See Put Cloudflare in front.

In your firewall, open ports 80 and 443 (and 443/udp, for HTTP/3), and nothing else. The agent's own port, 9000, speaks plain HTTP and must never be exposed to the internet. The firewall that matters most is the one the provider offers beside the machine: a firewall on the server does not close a port Docker has published, and a provider's firewall that is closed is silence, not a refusal — the installer finishes, the agent is healthy, and no certificate is ever issued. shipwick server install probes the two ports from your machine when it is done and names that firewall when they are silent; so does shipwick doctor. The commands, and what Docker does to a firewall on the server, are in Prepare a server.

Once the records exist, shipwick doctor from your laptop checks the whole path in one screen: the versions, the token, Docker, the proxy, ports 80 and 443, and for every domain whether DNS points at the server and HTTPS answers. It exits non-zero when something is broken and says what to do about each line; see Your first deployment.

If you skipped the API hostname, the API is not exposed at all. See Reach the API without a hostname.

Install a specific version ​

Everything the installer fetches comes from one release — never from a branch — and each file is verified against that release's checksums; since 0.10 latest is resolved to a release's tag before the first download, so two files cannot come from two releases, and the images the pull brought are compared with the digests the release published. By default that is the latest release. To choose one:

bash
curl -fsSL https://get.shipwick.com | SHIPWICK_VERSION=v1.1.0 sh

Because the images are pinned in the compose file, a server runs the version it installed until you run the installer again. That is also how you upgrade, and how you go back. From your laptop, shipwick server install user@host --version v1.1.0 does the same over SSH.

The signature ​

From 0.8.0 on, a release's checksums.txt is signed by the workflow that published it. Where cosign (2.5 or later) is installed, the installers verify that signature before they use the checksums, and stop if it is not the workflow's:

text
✓ The release is signed by the release workflow of github.com/shipwick/shipwick

Where it is not, which is every new server, the installer says so in one line and goes by the checksums alone, as before. Nothing installs cosign for you, and nothing needs it. Cosign 2.4 does not read the release's signature; 2.5.0 and later do.

To make the check a condition, set SHIPWICK_REQUIRE_SIGNATURE=1 for the installer: it then installs nothing without cosign, from a release without a signature, or from one whose signature does not verify. Without that setting a release that has no signature is installed with a warning — releases before 0.8.0 have none, and the installer cannot tell one of those from a release whose signature somebody removed.

What the signature proves, and the commands to check it yourself, images included: Verify a release.

Other ways to install ​

The compose file, by hand ​

The installer's setup is one file, configs/compose.production.yml, plus a .env next to it:

bash
SHIPWICK_AGENT_TOKEN=<output of: openssl rand -hex 32>
SHIPWICK_AGENT_DOMAIN=agent.example.com
SHIPWICK_DASHBOARD_DOMAIN=dashboard.example.com
SHIPWICK_WEBHOOK_URL=https://hooks.slack.com/services/...   # optional
SHIPWICK_CLOUDFLARE_API_TOKEN=...                           # optional
bash
docker compose -f compose.production.yml up -d

Generate the token yourself, as shown. The token must be at least 16 characters. If you let the agent generate one, it prints it to its log, and under Docker that log stays readable through docker logs for as long as the container exists. On its first start the agent also creates encryption.key in its data directory; back it up together with the database, or manage the key yourself with SHIPWICK_ENCRYPTION_KEY (64 hexadecimal characters). The compose file gives Caddy a caddy-static volume, mounted at /srv/shipwick, where the agent puts the folders of static applications. The backup, export and alert variables it passes to the agent are all optional; see Agent configuration.

The compose file attached to a release pins the three Shipwick images — agent, dashboard and Caddy — to that release, and the socket proxy's to a version of its own. The copy in the repository refers to latest.

A compose file of your own needs the shipwick-control network as that file has it since 0.8 — the agent on it alone, Caddy on all three networks, the dashboard on it alone — and no SHIPWICK_LISTEN_ADDR for the agent's container. Without them the API is open to the containers of applications, protected by the token alone, and shipwick doctor says so; see Who can reach the API.

Since 1.1 the file puts a socket proxy between the agent and Docker, so the agent never holds the Docker socket; before, the proxy was an overlay to put in by hand. Two overlays of the repository change the arrangement: compose.direct-socket.yml takes the proxy out and gives the agent the socket itself, compose.rootless.yml hands the proxy a rootless daemon's socket. A third arrangement, since 0.9, is not an overlay: Docker's authorization plugin with a policy of the repository's, installed into the daemon. See The Docker socket.

From source ​

Build the images on the server from a checkout of the repository, then run the installer from that checkout. It uses the compose file next to it instead of downloading one.

bash
docker build -t ghcr.io/shipwick/agent .
docker build -t ghcr.io/shipwick/dashboard dashboard/
docker build -t ghcr.io/shipwick/caddy -f Dockerfile.caddy .
sh scripts/install.sh

Build the CLI with make build.

A package: the agent as a service of the host ​

Since 0.7 the agent is published as a Debian and an RPM package, for a server where it should be started by systemd and upgraded by the package manager instead of running in a container. The proxy and the dashboard stay containers, started from a compose file the package brings. Since 0.9 the packages are installed and put through everything an installation does on Debian and Rocky Linux, by a script of the repository. See Install from a package.

As a process of the host the agent listens on 127.0.0.1:9000 by default and keeps its data — shipwick.db, encryption.key and the uploaded folders of static applications until they are deployed — in /var/lib/shipwick; from a checkout, make build builds the same binary. The proxy stays a container: Caddy finds the replicas of an application by name on a Docker network, which a Caddy installed on the host cannot do. All variables are listed in Agent configuration.

What's next ​