Docker Registries
Store a registry username and access token so container applications on this server can pull private images.
A container application pulls its image from a registry. Public images need nothing — the pull is anonymous and it works. Registry credentials exist for the other case: a private image, on Docker Hub, GitHub Container Registry, GitLab's registry, or a registry of your own.
You add the credential once here, then choose it on a container application — either on the create form or later in the application's Container settings. Applications left on None keep pulling anonymously.
This screen only exists on a container server
The stack is chosen when OSS Panel is installed and cannot be changed afterwards.
On a lemp, lamp, ols or mern server there are no containers, so there is
nothing for a registry credential to pull for — the panel removes the feature
entirely rather than offering a credential that can never be used.
The sidebar drops Docker Registries from the Integrations group, and the URL, if you have it bookmarked, answers like this:
The message is misleading here
On a non-container server the permission is withdrawn along with the feature, so
the page falls back to the generic "You don't have access" wording rather than
the "this server hosts no containers" explanation the screen has ready. If you
are an administrator and see this, your role is fine — the server simply does not
run containers. Install with --stack=docker to get the feature.
Everything below describes the screen on a server that does host containers.
What a credential holds
| Field | Notes |
|---|---|
| Name | Yours, for recognising it later — "GHCR", "Team Docker Hub". |
| Registry address | The host on its own: ghcr.io, not ghcr.io/your-org. No https://, no repository path. Add a port if yours uses one. |
| Username | Whatever that registry accepts for docker login. |
| Access token | A token, not your account password. Read-only access is enough — the panel only pulls. |
The form asks where the image is hosted first and then tailors the rest. It covers four cases:
- Docker Hub — the address is fixed. Your username is your Docker ID (the name in your profile URL), not your email. Create the token under Account settings → Personal access tokens with Read access. With two-factor authentication on, an account password will not work at all.
- GitHub Container Registry —
ghcr.io. Create a classic personal access token with theread:packagesscope. A fine-grained token cannot carryread:packages, so it is refused even though it looks valid. - GitLab Container Registry — create a deploy token with
read_registryunder Settings → Repository → Deploy tokens. The username is the deploy token's own username, shown once when the token is created — not your GitLab account name. - Other or self-hosted — anything else, including a private registry on your
own network:
registry.example.com:5000and whatever credentials it accepts.
For the three named providers the registry address is fixed and not editable. Docker stores credentials under one exact address, and any other spelling of it is ignored rather than rejected — which would look like a silently broken credential.
Add a credential
Open Integrations → Docker Registries and press Add registry.
Choose where the image is hosted. The "How to get this" panel changes with your answer and links to the right page at that provider.
Fill in the name, username and token, then press Test connection. The panel contacts the registry straight away rather than leaving you to discover a bad credential on your first deploy.
A failure is reported precisely: the registry refused this username and token, the registry could not be reached from this server, or the registry refused the connection without saying why.
Save, then pick the credential on a container application — on the create form, or in Container settings on an existing one. See Container applications.
Limits and caveats
- Pull only. This credential is never used to push an image.
- Short-lived tokens do not survive. AWS ECR issues credentials that last twelve hours; a token pasted here authenticates now and starts failing when it expires, because the panel does not refresh it. Use a registry with a long-lived token, or plan to update it by hand.
- The list shows how many applications use each credential. Deleting one that is in use does not delete or stop those applications — but their next pull becomes anonymous, and fails if the image is private.
- Editing a credential leaves the stored token in place unless you type a new one; the field is blank because the panel cannot show you the old value.
- Adding, editing and removing needs Docker Registries · Manage.
Screenshots pending
The screens on this page have not been captured yet — the documentation server
runs a PHP stack, where the feature does not exist. They will be added from a
--stack=docker server.