Skip to main content

Docker Repository Reverse Proxy Strategies

Peter
Updated

Docker Repository + Reverse Proxy Intended Use Case

Using a reverse proxy in front of Nexus for Docker repositories is an option to consider for the following use cases:

  • multiple connectors inside of Eclipse Jetty/Nexus would cause performance issues
  • the number of open ports needs to be limited for infrastructure or security reasons
  • managing secure connectors/ports/hosts inside an external reverse proxy aligns with organizational goals and infrastructure
  • isolating private docker images from other parties is a requirement

Implementation Overview

Nexus would be listening at a non-https connector such as the default 8081.

Docker repositories are added into Nexus as normal but would NOT be configured with any connector port values.

In the simple case there would be the following docker repository hierarchy inside Nexus per project team:

  • docker-group-project
    • docker-hosted-project
    • docker-hub

Based on the host name or port of the request to a reverse proxy, the reverse proxy decides where to reverse proxy the request into Nexus.

Docker Push Port Mapping Example

docker login project.example.com:8086
docker push project.example.com:8086

The reverse proxy would direct docker push commands received at

https://project.example.com:8086

to

http://localhost:8081/repository/docker-hosted-project

Docker Push Host Mapping Example

docker login project-push.example.com
docker push project-push.example.com

The reverse proxy would direct docker push commands received at

https://project-push.example.com

to

http://localhost:8081/repository/docker-hosted-project

Docker Pull Port Mapping Example:

docker login project.example.com:8087
docker pull project.example.com:8087

The reverse proxy would direct docker pull commands received at

https://project.example.com:8087

to

http://localhost:8081/repository/docker-group-project

Docker Pull Host Mapping Example:

docker login project.example.com
docker pull project.example.com

The reverse proxy would direct docker pull commands received at

https://project.example.com

to

http://localhost:8081/repository/docker-group-project

Example Reverse Proxy Configuration

Port Mapping Example:

Here is an example Apache httpd configuration for port mapping:

https://project.example.com:8087

to:

http://localhost:8081/repository/docker-repo

Listen 8087 https

<VirtualHost *:8087>
  ServerName project.example.com
  ServerAdmin admin@example.com

  AllowEncodedSlashes NoDecode
  ProxyRequests Off
  ProxyPreserveHost On

  SSLEngine ON
  SSLCertificateFile "/path/to/ssl/server.crt"
  SSLCertificateKeyFile "/path/to/ssl/server.key"

  ProxyPass / http://localhost:8081/repository/docker-repo/ nocanon
  ProxyPassReverse / http://localhost:8081/repository/docker-repo/
  RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>

Host Mapping Example:

Here is an example Nginx configuration for host mapping:

https://project.example.com

to:

http://localhost:8081/repository/docker-repo

 server {
   listen 443 ssl;
   server_name project.example.com

   ssl on; 
   ssl_certificate /path/to/ssl/server.crt;
   ssl_certificate_key /path/to/ssl/server.key;

   # Docker /v2 and /v1 (for search) requests
   location /v2 {
     proxy_set_header Host $host:$server_port;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto "https";
     proxy_pass http://localhost:8081/repository/docker-repo/v2;
   }
   location /v1 {
     proxy_set_header Host $host:$server_port;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto "https";
     proxy_pass http://localhost:8081/repository/docker-repo/v1;
  }

   # Regular Nexus requests
   location / {
     proxy_set_header Host $host:$server_port;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto "https";
     proxy_pass http://localhost:8081;
   }
 }

In this Nginx host mapping, the same server is used for both Docker and regular Nexus requests, and location directives are used to proxy /v2 or /v1 requests to the Docker repository. These v1/v2 paths are automatically added by Docker to the requests and does not require users to add them directly to the Docker commands.

Limitations

A wildcard TLS certificate is needed for the host name mapping scenario, if you intend to have more than one project team specific host name.

Related articles