Registry credentials for updates
How the in-app updater authenticates to the image registry (ghcr.io by default), and what to do when the token expires, the registry refuses it, or you move to a different registry.
The application images are private packages. By default they are served from the GitHub
Container Registry, ghcr.io; WI_IMAGE_REGISTRY in .env names a different registry host
(see Configuration reference). The Docker
daemon stores no registry credentials of its own. Each client sends them with every request,
taken from its own Docker config file.
For the in-app updater, that file is the host's. The compose file mounts the host's Docker
config directory, /root/.docker by default, read-only into the app container at
/run/host-docker-config and points DOCKER_CONFIG at it. The login that install.sh made
with sudo docker login <registry> is therefore the login that Check for updates and
Install update use. The updater checks and pulls from the registry the running containers
came from. If you keep the config elsewhere, set WI_DOCKER_CONFIG_DIR in .env.
Renew or replace the login#
When the token expires or is revoked, the update check and the image pull fail with an
unauthorized message from the registry (the check shows it as "docker registry inspection
failed for image ..."; a pull shows "failed to pull ...").
-
Create a new token your registry accepts. On
ghcr.iothat is a classic personal access token with theread:packagesscope; fine-grained tokens do not work with GHCR. -
Log in on the host, always with
sudo:echo "<your-token>" | sudo docker login <registry> -u <your-username> --password-stdinFor GHCR, use
ghcr.ioand your GitHub username. Do not log in as a different user. The login must land in/root/.docker/config.json(or in the directoryWI_DOCKER_CONFIG_DIRnames), because that is the directory the application reads. -
Restart the application so it picks up the new login:
sudo docker compose -p wi-prod restart app -
Return to Settings > Updates and select Check for updates.
Move to a different registry#
An in-app update does not change the registry. To switch, re-run install.sh with the new
registry host, the image namespace on that host and credentials. For Workforce Intelligence's
registry, harbor.getwi.com, the namespace is wi: set both
WI_IMAGE_REGISTRY=harbor.getwi.com and WI_IMAGE_OWNER=wi. If .env
already has a WI_IMAGE_REGISTRY or WI_IMAGE_OWNER line, edit it to the new value first (or
delete it to return to the default); the script stops rather than leave the box split between
two image paths.
WI_IMAGE_REGISTRY=<registry-host> \
WI_IMAGE_OWNER=<namespace> \
REGISTRY_USER=<your-username> \
REGISTRY_TOKEN=<your-token> \
./install.sh
The installer logs in to the new
host as root, pulls the image, saves WI_IMAGE_REGISTRY and WI_IMAGE_OWNER to .env when they are not
the defaults, and recreates the stack from images pulled there. See
Day-two operations.
Notes#
- The mount is a directory, not the single
config.jsonfile.docker loginreplaces the file by renaming it, which a single-file mount would miss. - The application reads plain
authsentries inconfig.json. A host configured with a credential helper (credsStore) keeps the login outside that file, and theappcontainer has no copy of the helper, so it cannot use that login. - The login also serves
install.shwhen you re-run it on the host. See Day-two operations.