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.

For: Administrators (the admin ability) · Last updated

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 ...").

  1. Create a new token your registry accepts. On ghcr.io that is a classic personal access token with the read:packages scope; fine-grained tokens do not work with GHCR.

  2. Log in on the host, always with sudo:

    echo "<your-token>" | sudo docker login <registry> -u <your-username> --password-stdin
    

    For GHCR, use ghcr.io and your GitHub username. Do not log in as a different user. The login must land in /root/.docker/config.json (or in the directory WI_DOCKER_CONFIG_DIR names), because that is the directory the application reads.

  3. Restart the application so it picks up the new login:

    sudo docker compose -p wi-prod restart app
    
  4. 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.json file. docker login replaces the file by renaming it, which a single-file mount would miss.
  • The application reads plain auths entries in config.json. A host configured with a credential helper (credsStore) keeps the login outside that file, and the app container has no copy of the helper, so it cannot use that login.
  • The login also serves install.sh when you re-run it on the host. See Day-two operations.