Skip to content

How it fits together ​

One page for the questions before the first command: what the parts are, which of them you need, in what order a fresh server comes together, and what tends to go wrong.

The picture ​

Your laptop with the shipwick CLI, one server running Caddy, the agent and your containers, and a browser for your users; the laptop talks to the server over HTTPS with a token, and users reach the applications through Caddy
Your laptop or CI on the left, one server in the middle, your users on the right. The same picture as text, for copying:
text
 Your laptop, or CI                          One Linux server (a VPS)
 ┌──────────────────────┐                    ┌────────────────────────────────────────────────────────────┐
 │  shipwick (the CLI)  │  HTTPS + token     │  Caddy ── ports 80 and 443 ── the internet                 │
 │  deploy.yaml         │ ─────────────────► │    │                                                       │
 │  Dockerfile          │                    │    ├─► agent ── socket proxy ── Docker ── your containers  │
 │  (docker, if build:) │                    │    │      └── SQLite (one file)                            │
 └──────────────────────┘                    │    └─► dashboard (optional)                                │
                                             └────────────────────────────────────────────────────────────┘
        Your browser ──── HTTPS ────► dashboard.example.com ─► Caddy ─► dashboard ─► agent
        Your users   ──── HTTPS ────► api.example.com       ─► Caddy ─► your containers

Everything on the server is started by one command, the installer, as four containers next to Docker: Caddy, the agent, the socket proxy the agent reaches Docker through (since 1.1; before, the agent held the Docker socket itself), and the dashboard. Everything on your side is one binary, shipwick.

The parts, and which you need ​

PartWhereRequired?What it does
DockerserveryesRuns the containers. shipwick server install installs it for you when it is missing; the installer run on the server itself stops if it is not there.
AgentserveryesThe one process that is Shipwick: takes deploy.yaml, pulls or loads the image, starts the replicas, checks their health, tells Caddy what to route, supervises what runs, keeps its state in one SQLite file. Serves the REST API that the CLI and the dashboard talk to.
CaddyserveryesThe reverse proxy in front of your applications. Holds ports 80 and 443, obtains and renews certificates, balances across replicas, serves static sites from disk. Installed and configured by Shipwick; you never edit its configuration. Since 0.5 the image is Shipwick's own build, ghcr.io/shipwick/caddy: Caddy with the Cloudflare DNS module and, since 0.8, its own way of finding replicas, and nothing else added.
DashboardservernoThe same information and everyday actions in a browser, with a sign-in through your company's accounts if you configure one. Skip it by leaving its hostname empty when the installer asks; add it later by setting SHIPWICK_DASHBOARD_DOMAIN in /opt/shipwick/.env.
shipwickyour laptop, CIyesThe command-line client. Validates deploy.yaml, builds the image on your machine when the file says build: ., sends it, waits for the result and tells you what happened. Also installs the server over SSH and checks the setup with doctor.
A DNS nameyour DNS providerfor HTTPSOne record per hostname you use: the API, the dashboard, and every application with a domain. Plain A (and AAAA) records pointing at the server, "DNS only", not proxied through a CDN — unless the agent has a Cloudflare API token, with which records can stay proxied by Cloudflare.
A registryanywherenoOnly if you want to docker push images and have the server pull them. With build: . the CLI builds on your machine and sends the image straight to the server. CI pipelines usually keep a registry.
A Cloudflare API tokenCloudflarenoOnly to keep hostnames behind Cloudflare's proxy, or to use wildcard hostnames. Caddy then obtains certificates through a DNS record; the agent checks what the token can do when it starts. See Put Cloudflare in front.
A bucketany S3-compatible servicenoOnly to keep backups off the server. The agent takes backups on a schedule and keeps them on the server's disk; with a bucket configured it sends each one there as well. See Back up and restore volumes.

Nothing else: no database to provision, no queue, no second server.

What the server connects to ​

Visitors and the CLI come in through ports 80 and 443. Going out, the server reaches the registries it pulls images from and the certificate authority, and a few more places only when you configure them:

ConnectionWhen
Your webhookSHIPWICK_WEBHOOK_URL is set: the agent posts notifications there.
Cloudflare's APISHIPWICK_CLOUDFLARE_API_TOKEN is set: Caddy creates and removes the DNS records that prove a hostname is yours, and since 0.9 the agent checks the token when it starts and when shipwick doctor asks, by creating and removing a TXT record of its own in each zone.
The S3 bucketThe SHIPWICK_BACKUP_S3_* variables are set: the agent sends backups there, and reads them back to restore.
Your sign-in providerSHIPWICK_OIDC_ISSUER is set: the agent reads the provider's keys and redeems sign-ins there.

To decide whether a hostname is ready, the agent also asks public DNS resolvers — Cloudflare's, Google's, Quad9's — rather than the server's own, and falls back to the server's own when they cannot be reached. All of these are listed in Agent configuration. A server that goes out through a proxy, or not at all, is covered in Run behind a corporate proxy or without internet.

From an empty VPS to a running application ​

  1. Get a server with a public IPv4 address and root SSH access. Ubuntu or Debian is the well-trodden path; any Linux with Docker works. 1 vCPU and 2 GB of memory run Shipwick and a handful of small applications.
  2. Point DNS at it. Create A records for the API hostname and the dashboard hostname (agent.example.com, dashboard.example.com), and for the domain of the first application. Do this before installing: certificates are issued only once a name resolves to the server.
  3. Open ports 80 and 443 (and 443/udp) in the provider's firewall, and nothing else. Port 9000, the agent's own, must never be reachable from the internet.
  4. Install the CLI on your laptop:
    bash
    curl -fsSL https://get.shipwick.com | sh -s -- --cli     # or: brew install shipwick/tap/shipwick
    See Install the CLI.
  5. Install the server, from your laptop:
    bash
    shipwick server install [email protected] --agent-domain agent.example.com --dashboard-domain dashboard.example.com
    It installs Docker if it is missing, runs the installer over SSH, saves the API token for you and prints the DNS records to create. Nothing to type on the server. On the server itself, the same thing is curl -fsSL https://get.shipwick.com | sh, followed by shipwick login --url https://agent.example.com on your laptop with the token it prints. See Install on a server.
  6. Check the setup before deploying anything:
    bash
    shipwick doctor
    One line per check — versions, token, Docker, proxy, ports, every domain's DNS and HTTPS — each with what to do about it.
  7. Deploy. In your project, shipwick init writes a Dockerfile and a deploy.yaml; shipwick deploy builds, sends and runs it. See Your first deployment.

From the second application on, only step 7 repeats.

Problems you may meet ​

Each of these was met on a real server. The message you see is in the first column.

You seeWhyDo
Port 80 is already in use by … from the installerSomething else on the server holds port 80 or 443: another web server, another deployment platform, a leftover container. Automatic HTTPS needs both ports.Stop or remove what holds them, or use a fresh server. The installer changed nothing yet.
Docker is not installedThe installer, run on the server itself, does not install Docker on its own.curl -fsSL https://get.docker.com | sh, then run the installer again. Or use shipwick server install, which does this step.
Routing https://api.example.com is waiting for DNS: does not resolve yet; add an A record: api.example.com → 203.0.113.10The deployment succeeded, but the hostname does not point at the server yet, so Caddy was not asked for a certificate.Create the record as the message says. Within a minute the agent notices and the site is served; nothing to redo.
… resolves to Cloudflare's proxy (104.21.5.6), not to this server: turn the proxy off for this record (DNS only), or set SHIPWICK_CLOUDFLARE_API_TOKEN on the agent to keep it onThe record is proxied ("orange cloud"). The proxy takes the TLS handshake away from Caddy, and no certificate can be issued from the server itself.In Cloudflare, switch the record to "DNS only" (grey cloud). Or give the agent a Cloudflare API token, and the certificate is obtained through a DNS record instead: Put Cloudflare in front.
The browser shows a certificate error minutes after the record was createdCaddy tried to get a certificate while the record was missing, failed, and is waiting before it retries.Wait a few minutes. If it persists: cd /opt/shipwick && docker compose restart caddy. Deploying before DNS exists is what the DNS check above prevents.
Docker Compose … does not accept this release's compose file from the installerThe Compose plugin on the server is older than 2.23.1 and cannot read Shipwick's compose file.Upgrade the plugin, docker-compose-plugin from Docker's repository, and run the installer again. The compose file in use was not replaced.
Deployment failed … did not become healthy within 30sThe container started but did not answer the health check: wrong port, a path that returns non-2xx, or an application that needs longer to start.Read the "Last output of replica 1" lines under the message. Fix port or health.path; a slow starter gets health.start_period: 60s. The version that was running kept serving throughout.
pull access denied for ghcr.io/company/api: run shipwick registry login ghcr.io (or check the image name)The server has no credentials for the registry the image is in.shipwick registry login <registry> --username <name> once, see Pull from private registries. Or use build: . and skip the registry.
The agent rejected the API tokenThe token is wrong, revoked, or belongs to another server.shipwick login with the token from /opt/shipwick/.env on the server. Several servers: shipwick context ls.
The token ci expired on …The token was created with an end, and it has passed.An admin creates a new one with shipwick token create; see Create tokens for CI and teammates.
A pull fails with a message about /etc/docker/daemon.jsonThe server goes out through a proxy, and the Docker daemon, which pulls the images, does not know it.Give Docker the proxy: Run behind a corporate proxy.
cannot reach the Shipwick agent at …The URL is wrong, the API hostname was left empty at install, or DNS for it is missing.shipwick doctor. If you chose not to expose the API, use the SSH tunnel: Reach the API without a hostname. On the server itself, shipwick is signed in by the installer when the API has a hostname; without one it says that the agent publishes no port, and how to give it a hostname.
429 RATE_LIMITED / "Too many failed attempts from this address"Twenty wrong tokens within a minute from one address.Wait a minute. A valid token is never refused; only wrong ones are answered this way.
The site answers 503The application is stopped (shipwick stop), or no replica is healthy.shipwick status <app> says which. shipwick start, or read the replicas' output with shipwick logs.
refers to ${DATABASE_PASSWORD}, which is not setA placeholder in deploy.yaml has no value on your machine and no secret on the server.shipwick secret set DATABASE_PASSWORD --app my-api once, or pass --env-file. See Keep secrets on the server.
Port 443 on … timed out after 3s from shipwick doctor or shipwick server installThe firewall the provider offers beside the machine drops the packets; a closed one is silence, not a refusal.Open 80 and 443 TCP and 443 UDP there. See Prepare a server.
… does not know the SSH key this machine offered from shipwick server installThe server's authorized_keys lacks the key ssh offered; the command names the key.Select the key when the server is created, paste it through the provider's console, or ssh-copy-id where the server also takes a password. See Install on a server.
… sends its visitors to www.example.com, which redirects sends back: every request loopsThe application redirects its domain to a hostname that redirects sends back.Make that hostname the domain and the other a redirect, or stop the application redirecting. See A redirect loop is caught.
After delete, the data is still on diskVolumes outlive the application on purpose.shipwick volumes lists them; shipwick volumes rm <name> removes one you no longer want.
I lost the tokenIt is printed once, but kept on the server.grep SHIPWICK_AGENT_TOKEN /opt/shipwick/.env as root.
The server's disk is full (…). Nothing was changed.The disk the agent's database and Docker's images are on has no room.On the server, docker system df shows what takes it and docker image prune -a removes the images nothing uses; then run the command again. See When things break.
Docker does not answer on the serverThe Docker daemon is not running, or is running and stuck. Applications that are running keep running.On the server, systemctl status docker. Shipwick goes on by itself when the daemon answers. See When things break.
The server rebootedUsually nothing to do: Docker starts the agent and the proxy, and the agent starts every application according to its restart policy. An application with restart.policy: never, or with on-failure and a process that exits with 0 when it is asked to stop, stays stopped.shipwick ps shows which are not HEALTHY; shipwick start <app> for one that stayed stopped. See When things break.

When something is not on this list, shipwick doctor is the first command to run, and shipwick status <app> the second.

What's next ​