Web UI, authentication service and event recorder for private docker registry v2.

• Browsing repositories, tags and images in docker registry v2
• Optional token based authentication provider with role-based permissions
• Docker registry notification recording and audit

Migrating configuration from 0.0.4 to 0.1.x

docker pull hyper/docker-registry-web

Do not use registry as registry container name, it will break REGISTRY_NAME environment variable.

docker run -d -p 5000:5000 --name registry-srv registry:2
docker run -it -p 8080:8080 --name registry-web --link registry-srv -e REGISTRY_URL=http://registry-srv:5000/v2 -e REGISTRY_NAME=localhost:5000 hyper/docker-registry-web 

docker run -it -p 8080:8080 --name registry-web --link registry-srv \
           -e REGISTRY_URL=https://registry-srv:5000/v2 \
           -e REGISTRY_TRUST_ANY_SSL=true \
           -e REGISTRY_BASIC_AUTH="YWRtaW46Y2hhbmdlbWU=" \
           -e REGISTRY_NAME=localhost:5000 hyper/docker-registry-web

1. Create configuration file config.yml

   (Any property in this config may be overridden with environment variable, for example property registry.auth.enabled will become REGISTRY_AUTH_ENABLED)

   registry:
     # Docker registry url
     url: http://registry-srv:5000/v2
     # Docker registry fqdn
     name: localhost:5000
     # To allow image delete, should be false
     readonly: false
     auth:
       # Disable authentication
       enabled: false
   

2. Run with docker

   docker run -p 5000:5000 --name registry-srv -d registry:2
   docker run -it -p 8080:8080 --name registry-web --link registry-srv -v $(pwd)/config.yml:/conf/config.yml:ro hyper/docker-registry-web
   

3. Web UI will be available on http://localhost:8080

Token authentication requires RSA private key in PEM format and certificate matched with this key

1. Generate private key and certificate

   mkdir conf
   openssl req -new -newkey rsa:4096 -days 365 -subj "/CN=localhost" \
           -nodes -x509 -keyout conf/auth.key -out conf/auth.cert
   

2. Create registry config conf/registry-srv.yml

   version: 0.1    
   
   storage:
     filesystem:
       rootdirectory: /var/lib/registry
       
   http:
     addr: 0.0.0.0:5000   
       
   auth:
     token:
       # external url to docker-web authentication endpoint
       realm: http://localhost:8080/api/auth
       # should be same as registry.name of registry-web
       service: localhost:5000
       # should be same as registry.auth.issuer of registry-web
       issuer: 'my issuer'
       # path to auth certificate
       rootcertbundle: /etc/docker/registry/auth.cert
   

3. Start docker registry

   docker run -v $(pwd)/conf/registry-srv.yml:/etc/docker/registry/config.yml:ro \
               -v $(pwd)/conf/auth.cert:/etc/docker/registry/auth.cert:ro -p 5000:5000  --name registry-srv -d registry:2    
   

4. Create configuration file conf/registry-web.yml

   registry:
     # Docker registry url
     url: http://registry-srv:5000/v2
     # Docker registry fqdn
     name: localhost:5000
     # To allow image delete, should be false
     readonly: false
     auth:
       # Enable authentication
       enabled: true
       # Token issuer
       # should equals to auth.token.issuer of docker registry
       issuer: 'my issuer'
       # Private key for token signing
       # certificate used on auth.token.rootcertbundle should signed by this key
       key: /conf/auth.key
   

5. Start registry-web

   docker run -v $(pwd)/conf/registry-web.yml:/conf/config.yml:ro \
              -v $(pwd)/conf/auth.key:/conf/auth.key -v $(pwd)/db:/data \
              -it -p 8080:8080 --link registry-srv --name registry-web hyper/docker-registry-web
   

6. Web UI will be available on http://localhost:8080 with default admin user/password admin/admin.

After first start you will have following roles:

• UI_ADMIN
• UI_USER
• UI_DELETE
• read-all
• write-all

You can't delete or modify UI_ADMIN and UI_USER role, they are special roles and allows admin or user access to UI respectively.
User access allows to browse registry, admin access allows to create, delete and modify users and roles in addition to user access.

UI_DELETE role allows deleting images in the UI based on ACLs.

Every non-special role has a list of ACLs, each of ACL grants permission grants permission to pull, pull+push or pull+push+delete based on IP and image name glob matching. For example read-all role matches any IP and any image name with glob * and grants pull permission and write-all role grants pull+push permission for any IP and any image name.

registry-web supports triggering backend registry GC from the tags page (Run GC).

Add GC command in config.yml:

registry:
  gc:
    # SAFE (recommended)
    command: /bin/registry garbage-collect /etc/docker/registry/config.yml
    timeout:
      seconds: 300

Or use environment variables:

• REGISTRY_GC_COMMAND
• REGISTRY_GC_TIMEOUT_SECONDS

For multi-arch images (manifest list / OCI index), do not use --delete-untagged by default.

Risky command example:

/bin/registry garbage-collect /etc/docker/registry/config.yml --delete-untagged

This may remove child platform manifests (linux/amd64, linux/arm64) while tag/index still exists, causing UI entries with 0 layers / 0 size or pull failures.

Registry v2 commonly deletes by manifest digest. If multiple tags reference the same digest, deleting one tag by digest removes all tags that reference it.

registry-web now applies safer logic:

1. Try tag-reference delete first (DELETE .../manifests/<tag>)
2. If backend doesn't support tag-only delete:
   • if digest is shared by multiple tags, block deletion and show warning
   • if digest is unique, fallback to digest delete

This avoids accidental removal of all tags that point to the same image.

If your command uses docker exec from inside registry-web, make sure:

1. Image contains Docker CLI
2. /var/run/docker.sock is mounted into registry-web
3. Target registry container name in command is correct

Example command:

/usr/bin/docker exec registry /bin/registry garbage-collect /etc/docker/registry/config.yml

• UI flash message should show success/failure
• Logs include explicit exit code now:
  • Executing GC command: ...
  • GC finished for <repo>: exit=<code>, stdout='...', stderr='...'
• Optional API check: POST /repo/runGcApi/<repoId> returns JSON with ok/success/exit/stdout/stderr