selfsigned-companion is a lightweight certificate companion container for nginx-proxy heavily inspired by acme-companion.
Warning
The certificates generated using this container should only be used for locally hosted projects.
- Automated creation of self-signed certificates using openssl.
- Startup creation of a certificate authority (CA) to trust your self-signed certificates.
- Automated update and reload of nginx config on certificate creation.
- Configurable certificate validaity period.
A writable volume must be declared on the nginx-proxy container so that it can be shared with the selfsigned-companion container:
/etc/nginx/certs
to store certificates and private keys (readonly for the nginx-proxy container).
Example of use:
Start nginx-proxy with the two additional volumes declared:
$ docker run --detach \
--name nginx-proxy \
--publish 80:80 \
--publish 443:443 \
--volume certs:/etc/nginx/certs \
--volume /var/run/docker.sock:/tmp/docker.sock:ro \
nginxproxy/nginx-proxy
Binding the host docker socket (/var/run/docker.sock
) inside the container to /tmp/docker.sock
is a requirement of nginx-proxy.
Start selfsigned-companion, getting the volumes from nginx-proxy with --volumes-from
:
$ docker run --detach \
--name nginx-proxy-selfsigned \
--volumes-from nginx-proxy \
--volume /var/run/docker.sock:/var/run/docker.sock:ro \
jamesblanksby/nginx-proxy-selfsigned-companion
The host docker socket has to be bound inside this container too, this time to /var/run/docker.sock
.
Once both nginx-proxy and selfsigned-companion containers are up and running, start any container you want proxied with environment variables VIRTUAL_HOST
and SELFSIGNED_HOST
both set to the domain(s) your proxied container is going to use.
Certificates will only be issued for containers that have both VIRTUAL_HOST
and SELFSIGNED_HOST
variables set to domain(s) that correctly resolve to the host.
$ docker run --detach \
--name proxied-app \
--env "VIRTUAL_HOST=local.example.com" \
--env "SELFSIGNED_HOST=local.example.com" \
nginx
Note
In this example SELFSIGNED_HOST
covers all subdomains (*.local.example.com
) so including all your FQDNs is not required.
The containers being proxied must expose the port to be proxied, either by using the EXPOSE
directive in their Dockerfile or by using the --expose
flag to docker run
or docker create
.
If the proxied container listens on and exposes another port other than the default 80
, you can force nginx-proxy to use this port with the VIRTUAL_PORT
environment variable.
Repeat Step 3 for any other container you want to proxy.
For selfsigned-companion to work properly, it needs to know the ID of the nginx-proxy container.
There are two methods to inform the selfsigned-companion container of the nginx-proxy container ID:
environment variable
: assign a fixed name to the nginx-proxy container with--name
and set the environment variableNGINX_PROXY_CONTAINER
to this name on the selfsigned-companion container.volumes-from
: Using this method, the selfsigned-companion container will get the nginx-proxy container ID from the volumes it got using thevolumes-from
option.
$ docker run --detach \
--name nginx-proxy-selfsigned \
[...]
--env "NGINX_PROXY_CONTAINER=unique-nginx-proxy" \
jamesblanksby/nginx-proxy-selfsigned-companion
Note
The environment variable NGINX_PROXY_CONTAINER
defaults to nginx-proxy
so only include if your nginx-proxy container is named differently.
$ docker run --detach \
--name nginx-proxy-selfsigned \
[...]
--volumes-from nginx-proxy \
jamesblanksby/nginx-proxy-selfsigned-companion
By default, when you use a self-signed certificate, web browsers will not consider it trustworthy and will notify you about a possible security risk. To address this, you need to import your certificate authority (CA) certificate, which is located in the certs
directory. The process of importing the certificate can vary depending on your operating system and web browser.
- In the Keychain Access app, select the login keychain.
- Drag the
ca.crt
file onto the Keychain Access app. - Double-click a certificate.
- Next to "Trust", click the arrow to display the trust policies for the certificate.
- Choose "Always Trust" when using this certificate.
$ sudo apt-get install -y ca-certificates
$ sudo cp certs/ca.crt /usr/local/share/ca-certificates
$ sudo update-ca-certificates
- Go to Preferences → Privacy & Security → Certificates or
about:preferences#privacy
. - Click "View Certificates".
- Select the "Authorities" tab and click "Import…".
- Choose your
ca.crt
certificate file. - Check "Trust the CA to identify websites" and click "OK".
- Go to Security → Manage Certificates or
chrome://settings/certificates
. - Select the "Authorities" tab and click "Import…".
- Click "Browse…" choose your
ca.crt
certificate file. - Check "Trust this certificate for identifying websites" and click "OK".
You may wish to alter the default 365
day self-signed certificate validity period, use the docker environment variable SELFSIGNED_EXPIRY
on startup.
An example of a 10 year (3650
day) validity period:
$ docker run --detach \
--name proxied-app \
[...]
--env "SELFSIGNED_EXPIRY=3650"
nginx