Pull from private registries
An image in a private registry needs a credential on the server. This page covers how to give the agent one with shipwick registry login, which exists since 0.5, what the agent does with it, what happens when a pull is refused, the older way through docker login on the server, which still works, and how to keep a credential current for Amazon ECR and Google Artifact Registry, whose tokens expire.
If the image is built from a Dockerfile in your project, no registry is needed at all: with build: . in deploy.yaml, shipwick deploy builds the image on your machine and sends it to the server, and nothing below applies. See build. A registry stays the right tool when CI builds the image, or when the image is somebody else's.
Log in
From wherever you run shipwick, with a token that has the admin role:
shipwick registry login ghcr.io --username octocat✓ Logged in to ghcr.io as octocat
The server pulls images from ghcr.io with this credential from now on.The password or token is asked for without echo. It is never an argument, because arguments leak through ps and shell history. In a script or a pipeline, pipe it in:
printf '%s' "$GHCR_TOKEN" | shipwick registry login ghcr.io --username octocatOutside a terminal the password is read from standard input by itself; --password-stdin is accepted for those used to Docker's flag, and reads it from there even in a terminal.
The registry is named the way image references name it: ghcr.io, registry.example.com:5000, docker.io for Docker Hub. There is nothing to put in deploy.yaml. The image reference is enough:
image: ghcr.io/company/my-api:1.4.2Use a token that may only read. The server pulls images; it never pushes.
What the agent does with it
Before it stores the credential, the agent has the Docker daemon check it against the registry. A mistyped token is refused at once, and not by the next deployment:
Error: ghcr.io refused the login: denied: denied
Nothing was stored. Check the username and the token, and that the token may read images; then log in again.The first line ends with the registry's own answer. A registry that cannot be asked, because its name does not resolve or it does not answer within 30 seconds, is refused the same way, with Check the registry's name, and that the server can reach it.
An accepted credential is kept in the agent's database with the password encrypted, like a secret; see Secrets at rest. The agent sends it with every pull from that registry: deployments, rollbacks, scheduled jobs and one-off commands, and a replica whose image was pruned from the server.
Nobody reads the password back. The list shows registries and usernames, and needs only the read role:
shipwick registry lsREGISTRY USERNAME UPDATED
ghcr.io octocat 2h agoLogging in again replaces the credential. To remove it (since 0.10 the command asks first in a terminal; --yes skips the question, and outside a terminal it is required):
shipwick registry logout ghcr.io✓ Logged out of ghcr.io
Running applications are not affected; the server pulls from there without this credential from now on.Up to 50 registries can be stored.
When a pull is refused
A deployment whose image cannot be pulled fails before anything is started, and the running version is not affected. When the registry refused the pull for want of a credential, the reason names the command to run:
✗ Deployment failed
pull access denied for ghcr.io/company/my-api: run shipwick registry login ghcr.io (or check the image name)Registries answer the same way for an image that does not exist as for one you may not see, which is why the image name is worth a look too. When a credential is stored and the registry refuses it for this image, the reason says so instead:
pull access denied for ghcr.io/company/my-api: the credential stored for ghcr.io does not give access to it; replace it with shipwick registry login ghcr.io (or check the image name)One exception: if the pull fails but the image already exists on the server — it was built there, or pulled earlier — the agent uses the local copy and records a warning with the deployment:
! Could not pull ghcr.io/company/my-api:1.4.2, using the local copy (…)The alternative: docker login on the server
For a registry without a stored credential, the agent reads the Docker CLI's configuration file, as it did before registry login existed. A stored credential takes precedence over it.
The file is ~/.docker/config.json, in the home directory of the user the agent runs as. The standard DOCKER_CONFIG variable is honored: if it is set, the agent reads config.json from that directory instead. On the server, as root:
docker login ghcr.ioIn the installer's setup the agent runs in a container, and the file on the host has to be mounted into it. Add the mount in /opt/shipwick/compose.override.yml (create the file if it does not exist). Compose merges it with compose.yml, and unlike compose.yml it is never replaced by an upgrade:
services:
agent:
volumes:
- /root/.docker/config.json:/root/.docker/config.json:roThen recreate the agent:
cd /opt/shipwick && docker compose up -dRun docker login before you start the agent with this mount, so that the file exists. Recreating the agent does not restart your applications.
Credential helpers are not supported
Only a username with a password or token works, in both ways. Credential helpers (credsStore in the Docker configuration, docker-credential-* programs) are not supported, and support for them is not planned: a helper is a program on the server, which the agent's container does not have, and the agent executes nothing.
Nor would the Docker daemon step in: it pulls with the credential a request hands it and with none otherwise, whatever the configuration of the user who installed it says. A config.json that names a credsStore holds no passwords at all, only the registries' names, so mounting it gives the agent nothing.
If docker login wrote a credsStore key and left the entry under auths empty, the credential went to a helper, and the agent cannot use it. Use shipwick registry login instead, as the next section shows for the two registries people use a helper for.
Registries with tokens that expire
Amazon ECR and Google Artifact Registry are the registries people use a helper for, and what the helper does there is fetch a short-lived token. The same token can be handed to the agent from wherever the cloud's own CLI is signed in — the pipeline that deploys, or a scheduled job:
# Amazon ECR: the token is valid for 12 hours
aws ecr get-login-password --region eu-central-1 \
| shipwick registry login 123456789012.dkr.ecr.eu-central-1.amazonaws.com --username AWS
# Google Artifact Registry: an access token, valid for an hour
gcloud auth print-access-token \
| shipwick registry login europe-west1-docker.pkg.dev --username oauth2accesstoken
# Google Artifact Registry: a service account's key, which does not expire
cat key.json | shipwick registry login europe-west1-docker.pkg.dev --username _json_keyThese are the commands Amazon and Google document for docker login, with shipwick registry login in its place: the same user names, the password on standard input, the registry without https://. The account, the region and the location are yours.
Logging in as the step before shipwick deploy covers the deployment: the agent pulls the image while the token is fresh. The server needs the registry again later only for an image it no longer has — a rollback to a version whose image was pruned, a replica recreated after its image was removed — and then a token from the last deployment has expired. Where that matters:
- Renew it on a schedule shorter than the token's life: every few hours for ECR.
- Or use a credential that does not expire: a service account key for Artifact Registry, with a role that only reads.
Storing a registry credential needs an admin token; give the job one of its own, with an end. A pull that fails for an expired token says which command to run.
What's next
- Deploy from CI, where images usually come from a private registry.
- Security, for how stored credentials are encrypted, and Rotate the encryption key.
shipwick registryin the CLI reference.- Use the dashboard: the Registries page does the same from a browser.