This project aims to provide a simple and complete user interface for your private docker registry. You can customize the interface with various options. The major option is SINGLE_REGISTRY
which allows you to disable the dynamic selection of docker registeries (same behavior as the old static tag).
You may need the migration guide from 1.x to 2.x or the 1.x readme
This web user interface uses Riot the react-like user interface micro-library and riot-mui components.
If you like my work and want to support it, don't hesitate to sponsor me.
latest
: image with the latest release of Docker Registry UI based onnginx:alpine
latest-debian
: image with the latest release of Docker Registry UI based onnginx:debian
main
,master
: image with the beta version of Docker Registry UI based onnginx:alpine
main-debian
,master-debian
: image with the beta version of Docker Registry UI based onnginx:debian
2
: image with the latest release of Docker Registry UI v2 (includes latest minor and patch version)2.x
: image with the latest release of Docker Registry UI v2.x (includes latest patch version)2.x.y
: image with the specific release of Docker Registry UI v2.x.y
Hidden Features
- Many ways to delete multiple images at once
- Select multiple tags to delete with checkboxes (see #29 and #79). Since 1.2.0
- Select all tags of the page with
ALT + Click
on the indeterminate checkbox (see #80 and #81). Since 1.2.1 - Select all contigous tags between two tags with
Shift + Click
on the first tag thenShift + Click
on the second tag (see #287). Since 2.4.0
- Show sha256 for specific tag (hover image tag).
- Sort the tag list with number compatibility (see #45 and #46). Since 0.4.0
- Share your docker registry UI without installation or when you are deploying a UI with
SINGLE_REGISTRY=false
.- Use the public demo and the query parameter
url
(e.g.https://joxit.dev/docker-registry-ui/demo?url=https://registry.example.com
). If you need credentials on your private registry, you must set theAccess-Control-Allow-Origin
tohttps://joxit.dev
. - You can use a single interface with many registry, add them in the menu in the top right of the page.
- Use the public demo and the query parameter
- Filter images and tags with the search bar.
- You can select the search bar with the shortcut
CRTL + F
orF3
. When the search bar is already focused, the shortcut will fallback to the default behavior (see #213). Since 2.1.0
- You can select the search bar with the shortcut
- Multi arch support in history page (see #130 and #134). Since 1.5.0
- Show the content of the dockerfile (see #286). Since 2.4.0
- The UI will cache requests from your registry, such as blobs and some manifests (URL with
sha256:
).
Checkout all options in Available options section.
- What is the difference between
SINGLE_REGISTRY=false
andSINGLE_REGISTRY=true
options ?- When
SINGLE_REGISTRY
is set to false, a menu appears on the interface allowing you to dynamically change docker registry URLs.
- When
- Why, when I delete all tags of an image, the image is still in the UI ?
- This is a limitation of docker registry, the garbage collector don't remove empty images. If you want to delete dangling images, you will need to delete the folder in your registry data. (see #77)
- Why the image size in the UI is not the same as displayed during
docker images
?- The UI displays the compressed size of the image and not the extracted size version.
- Can I use HTTPS on the UI ?
- Yes, put your favourite reverse proxy on the front of the UI. Your reverse proxy will take care of HTTPS connection.
- Does the UI support authentication ?
- Yes, but it supports only basic auth. It's a simple standalone frontend, it will use your browser window for authentication.
- Can I use the UI and docker client with an insecure registry (registry url without https) ?
- Yes you can, you must first configure your docker client. (see #76)
- What does Mixed Content error mean ?
- This means you are using a UI with HTTPS and your registry is using HTTP (unsecured). When you are on a HTTPS site, you can't get HTTP content. Upgrade you registry with a HTTPS connection.
- Why the default nginx
Host
is set to$http_host
? - Why OPTIONS (aka preflight requests) and DELETE fails with 401 status code (using Basic Auth) ?
- This is caused by a bug in docker registry, it returns 401 status requests on preflight requests, this breaks W3C preflight-request specification. I suggest to have your UI on the same domain than your registry e.g. registry.example.com/ui/ or use
NGINX_PROXY_PASS_URL
or configure a nginx/apache/haproxy in front of your registry that returns 200 on each OPTIONS requests. (see #104, #204, #207, #214, #266).
- This is caused by a bug in docker registry, it returns 401 status requests on preflight requests, this breaks W3C preflight-request specification. I suggest to have your UI on the same domain than your registry e.g. registry.example.com/ui/ or use
- Can I use the docker registry ui as a standalone application (with Electron) ?
- I deleted images through the UI, but they are still present on the server. How can I delete them?
- Why when I delete one tag, all tags with the same SHA are deleted ?
- This a docker registry API limitation, there is only one way to delete images with tag, it's by its
name
and itsmanifest
(it's a sha of the content). So when you delete a tag, this will delete all tags of this image with the same SHA/manifest.
- This a docker registry API limitation, there is only one way to delete images with tag, it's by its
- Can I run the container with an unprivileged user ?
- Can I use the UI with a docker hub mirror and show
library/*
images ?- Yes but it is at your own risk using two regstry servers, check the comment #155.
- How to fix CORS issue on s3 bucket ?
- You should add a CORS Policy on your bucket, check the issue #193.
- Why my docker registry server is returning an error
pagination number invalid
?- Since docker registry server 2.8.2 there is default limit of 1000 images in catalog. If you need more images update the configuration
REGISTRY_CATALOG_MAXENTRIES
with your max value and check the issue #306.
- Since docker registry server 2.8.2 there is default limit of 1000 images in catalog. If you need more images update the configuration
Need more informations ? Try my examples or open an issue.
You can run the container with the unprivileged user nginx
, see the discussion #224.
Some env options are available for use this interface for only one server (when SINGLE_REGISTRY=true
).
REGISTRY_URL
: The default url of your docker registry. You may need CORS configuration on your registry. This is usually the domain name or IP of your registry reachable by your computer (e.ghttps://registry.example.com
). (default: derived from the hostname of your UI).REGISTRY_TITLE
: Set a custom title for your user interface. (default: value derived fromREGISTRY_URL
) (see #28 and #32). Since 0.3.4PULL_URL
: Set a custom url when you copy thedocker pull
command (see #71). (default: value derived fromREGISTRY_URL
). Since 1.1.0DELETE_IMAGES
: Set if we can delete images from the UI. (default:false
)SHOW_CONTENT_DIGEST
: Show/Hide content digest in docker tag list (see #126 and #131). (default:false
). Since 1.4.9CATALOG_ELEMENTS_LIMIT
: Limit the number of elements in the catalog page (see #39, #127, #132) and #306. (default:1000
). Since 1.4.9SINGLE_REGISTRY
: Remove the menu that show the dialogs to add, remove and change the endpoint of your docker registry. (default:false
). Since 2.0.0NGINX_PROXY_PASS_URL
: Update the default Nginx configuration and set the proxy_pass to your backend docker registry (this avoid CORS configuration). This is usually the name of your registry container in the formhttps://registry:5000
. Since 2.0.0NGINX_PROXY_HEADER_*
: Update the default Nginx configuration and set custom headers for your backend docker registry via environment variable and file (/etc/nginx/.env
). Only whenNGINX_PROXY_PASS_URL
is used (see #89). Since 1.2.3NGINX_PROXY_PASS_HEADER_*
: Update the default Nginx configuration and forward custom headers to your backend docker registry via environment variable and file (/etc/nginx/.env
). Only whenNGINX_PROXY_PASS_URL
is used (see #206). Since 2.1.0NGINX_LISTEN_PORT
: Listen on a port other than 80, you can also change the default user and set to nginx--user nginx
(see #224 and #234). (default:80
when the user is root,8080
otherwise). Since 2.2.0DEFAULT_REGISTRIES
: List of comma separated registry URLs (e.ghttps://registry.example.com,https://registry:5000
), available only whenSINGLE_REGISTRY=false
(see #219). (default:READ_ONLY_REGISTRIES
: Deactivate dialog for remove and add new registries, available only whenSINGLE_REGISTRY=false
(see #219). (default:false
). Since 2.1.0SHOW_CATALOG_NB_TAGS
: Show number of tags per images on catalog page and hide images with 0 tags. This will produce + nb images requests, not recommended on large registries (see #161 and #239). (default:false
). Since 2.2.0HISTORY_CUSTOM_LABELS
: Expose custom labels in history page, custom labels will be processed like maintainer label (see #160 and #240). Since 2.2.0USE_CONTROL_CACHE_HEADER
: UseControl-Cache
header and set tono-store, no-cache
. This will avoid some issues on multi-arch images (see #260 and #265). This option requires registry configuration:Access-Control-Allow-Headers
withCache-Control
. (default:false
). Since 2.3.0THEME
: Chose your default theme, could bedark
,light
orauto
(see #283). When auto is selected, you will have a switch to manually change from light to dark and vice-versa (see #291). (default:auto
). Since 2.4.0THEME_*
: See table in Theme options section (see #283). Since 2.4.0TAGLIST_ORDER
: Set the default order for the taglist page, could benum-asc;alpha-asc
,num-desc;alpha-asc
,num-asc;alpha-desc
,num-desc;alpha-desc
,alpha-asc;num-asc
,alpha-asc;num-desc
,alpha-desc;num-asc
oralpha-desc;num-desc
(see #307). (default:alpha-asc;num-desc
). Since 2.5.0CATALOG_DEFAULT_EXPANDED
: Expand by default all repositories in catalog (see #302). (default:false
). Since 2.5.0CATALOG_MIN_BRANCHES
: Set the minimum repository/namespace to expand (e.g.joxit/docker-registry-ui
joxit/
is the repository/namespace). Can be 0 to disable branching. (see #319). (default:1
). Since 2.5.0CATALOG_MAX_BRANCHES
: Set the maximum repository/namespace to expand (e.g.joxit/docker-registry-ui
joxit/
is the repository/namespace). Can be 0 to disable branching. (see #319). (default:1
). Since 2.5.0TAGLIST_PAGE_SIZE
: Set the number of tags to display in one page. (default:100
). Since 2.5.0REGISTRY_SECURED
: By default, the UI will check on every requests if your registry is secured or not (you will see401
responses in your console). Set totrue
if your registry uses Basic Authentication and divide by two the number of call to your registry. (defaultfalse
). Since 2.5.0
There are some examples with docker-compose and docker-registry-ui as proxy here or docker-registry-ui as standalone here.
This featureswas added to version 2.4.0. See more about this in #283.
Environment variable | light theme value | dark theme value |
---|---|---|
THEME_PRIMARY_TEXT |
#25313b |
#8A9EBA |
THEME_NEUTRAL_TEXT |
#777777 |
#36527A |
THEME_BACKGROUND |
#ffffff |
#22272e |
THEME_HOVER_BACKGROUND |
#eeeeee |
#30404D |
THEME_ACCENT_TEXT |
#6680a1 |
#5684FF |
THEME_HEADER_TEXT |
#ffffff |
#ffffff |
THEME_HEADER_BACKGROUND |
#25313b |
#333A45 |
THEME_FOOTER_TEXT |
#ffffff |
#ffffff |
THEME_FOOTER_NEUTRAL_TEXT |
#999999 |
#999999 |
THEME_FOOTER_BACKGROUND |
#555555 |
#555555 |
Here is a simple usage of Docker Registry UI with Docker Registry Server using docker-compose. This example should work for most of your use case and your UI will be on the same domain as you registry.
version: '3.8'
services:
registry-ui:
image: joxit/docker-registry-ui:main
restart: always
ports:
- 80:80
environment:
- SINGLE_REGISTRY=true
- REGISTRY_TITLE=Docker Registry UI
- DELETE_IMAGES=true
- SHOW_CONTENT_DIGEST=true
- NGINX_PROXY_PASS_URL=https://registry-server:5000
- SHOW_CATALOG_NB_TAGS=true
- CATALOG_MIN_BRANCHES=1
- CATALOG_MAX_BRANCHES=1
- TAGLIST_PAGE_SIZE=100
- REGISTRY_SECURED=false
- CATALOG_ELEMENTS_LIMIT=1000
container_name: registry-ui
registry-server:
image: registry:2.8.2
restart: always
environment:
REGISTRY_HTTP_HEADERS_Access-Control-Allow-Origin: '[https://registry.example.com]'
REGISTRY_HTTP_HEADERS_Access-Control-Allow-Methods: '[HEAD,GET,OPTIONS,DELETE]'
REGISTRY_HTTP_HEADERS_Access-Control-Allow-Credentials: '[true]'
REGISTRY_HTTP_HEADERS_Access-Control-Allow-Headers: '[Authorization,Accept,Cache-Control]'
REGISTRY_HTTP_HEADERS_Access-Control-Expose-Headers: '[Docker-Content-Digest]'
REGISTRY_STORAGE_DELETE_ENABLED: 'true'
volumes:
- ./registry/data:/var/lib/registry
container_name: registry-server
Your server should be configured to accept CORS.
If your docker registry does not need credentials, you will need to send this HEADER:
Access-Control-Allow-Origin: ['*']
If your docker registry need credentials, you will need to send these HEADERS (you must add the protocol http
/https
and the port when not default 80
/443
):
http:
headers:
Access-Control-Allow-Origin: ['https://registry.example.com']
Access-Control-Allow-Credentials: [true]
Access-Control-Allow-Headers: ['Authorization', 'Accept', 'Cache-Control']
Access-Control-Allow-Methods: ['HEAD', 'GET', 'OPTIONS'] # Optional
An alternative for CORS issues is a plugin on your browser, more info here (thank you xmontero).
For deleting images, you need to activate the delete feature in the UI with DELETE_IMAGES=true
and in your registry:
storage:
delete:
enabled: true
And you need to add these HEADERS:
http:
headers:
Access-Control-Allow-Methods: ['HEAD', 'GET', 'OPTIONS', 'DELETE']
Access-Control-Allow-Headers: ['Authorization', 'Accept', 'Cache-Control']
Access-Control-Expose-Headers: ['Docker-Content-Digest']
Example of docker registry configuration file:
version: 0.1
log:
fields:
service: registry
storage:
delete:
enabled: true
cache:
blobdescriptor: inmemory
filesystem:
rootdirectory: /var/lib/registry
http:
addr: :5000
headers:
X-Content-Type-Options: [nosniff]
Access-Control-Allow-Origin: ['https://127.0.0.1:8000']
Access-Control-Allow-Methods: ['HEAD', 'GET', 'OPTIONS', 'DELETE']
Access-Control-Allow-Headers: ['Authorization', 'Accept', 'Cache-Control']
Access-Control-Max-Age: [1728000]
Access-Control-Allow-Credentials: [true]
Access-Control-Expose-Headers: ['Docker-Content-Digest']
auth:
htpasswd:
realm: basic-realm
path: /etc/docker/registry/htpasswd
If you do not want to install the docker-registry-ui on your server, you may check out the Electron standalone application (not updated).
- Use docker-registry-ui as a proxy (use REGISTRY_URL)
- Use docker-registry-ui as standalone (use URL)
- Use docker-registry-ui with traefik
- Use docker-registry-ui with docker registry and Amazon s3 (#75)
- FIX revproxy to registry does not work when published under non-root url (#73)
- Use docker-registry-ui with HTTPS (#20)
- Unable to push image when docker-registry-ui is used as a proxy on non 80 port (#88)
- Add custom headers bases on environment variable and/or file when the ui is used as proxy (#89)
- UI showing same sha256 content digest for all tags + Delete is not working (#116)
- Electron-based Standalone Application (#129)
- Use docker-registry-ui as proxy with read-only right (#47)
- Use DEFAULT_REGISTRIES and READ_ONLY_REGISTRIES (#219)