docker-letsencrypt-nginx-proxy-companion/docs/Persistent-data.md

Persistent data

Anonymous volumes

When you follow instructions from Basic usage or Advanced usage, Docker will automatically create anonymous volumes (volumes with a random name) for every --volume / -v argument passed:

$ docker run -d \
    --name nginx-proxy \
    -p 80:80 \
    -p 443:443 \
    -v /etc/nginx/certs \
    -v /etc/nginx/vhost.d \
    -v /usr/share/nginx/html \
    -v /var/run/docker.sock:/tmp/docker.sock:ro \
    jwilder/nginx-proxy

$ docker volume ls
DRIVER              VOLUME NAME
local               287be3abd610e5566500d719ceb8b952952f12c9324ef02d05785d4ee9737ae9
local               6530b1b40cf89efb71aa7fd19bddec927fa2bcae59b04b9c1c850af72ffe0123
local               f260f71fefadcdfc311d285d69151f2312915174d3fb1fab89949ec5ec871a54
local               f2cd94ca48904dc9cfc840ce4b265a04831c580d525253d7a0e5aac4d1dca340

Named volumes (recommended)

Using named volumes instead make managing volumes easier:

$ docker run -d \
    --name nginx-proxy \
    -p 80:80 \
    -p 443:443 \
    -v certs:/etc/nginx/certs \
    -v vhost:/etc/nginx/vhost.d \
    -v html:/usr/share/nginx/html \
    -v /var/run/docker.sock:/tmp/docker.sock:ro \
    jwilder/nginx-proxy

$ docker volume ls
DRIVER              VOLUME NAME
local               certs
local               vhost
local               html

Host volumes

Alternatively, you might want to store the certificates on a local folder rather than letting Docker create and manage a volume for them. This is easily achieved by using a host volume (binding an absolute path on your host to the /ect/nginx/certs folder on your containers):

-v /path/to/certificates:/etc/nginx/certs

No matter the type of volume you choose, if you set them on the nginx-proxy or nginx container and use --volumes_from on the others containers, they will automatically be mounted inside the container to the path your first defined.

Restraining other containers write permission

If you want to restrain the nginx and docker-gen processes to read only access on the certificates, you'll have to use different volume flags depending on the container.

Example with named volumes:

-v certs:/etc/nginx/certs:ro on the nginx-proxy or nginx + docker-gen container(s).

-v certs:/etc/nginx/certs:rw on the letsencrypt-nginx-proxy-companion container.

Ownership & permissions of private and ACME account keys

By default, the letsencrypt-nginx-proxy-companion container will enforce the following ownership and permissions scheme on the files it creates and manage:

[drwxr-xr-x]  /etc/nginx/certs
├── [drwxr-xr-x root root]  accounts
│   └── [drwxr-xr-x root root]  acme-v01.api.letsencrypt.org
│       └── [drwxr-xr-x root root]  directory
│           └── [-rw-r--r-- root root]  default.json
├── [-rw-r--r-- root root]  dhparam.pem
├── [-rw-r--r-- root root]  default.crt
├── [-rw-r--r-- root root]  default.key
├── [drwxr-xr-x root root]  domain.tld
│   ├── [lrwxrwxrwx root root]  account_key.json -> ../accounts/acme-v01.api.letsencrypt.org/directory/default.json
│   ├── [-rw-r--r-- root root]  cert.pem
│   ├── [-rw-r--r-- root root]  chain.pem
│   ├── [-rw-r--r-- root root]  fullchain.pem
│   └── [-rw-r--r-- root root]  key.pem
├── [lrwxrwxrwx root root]  domain.tld.chain.pem -> ./domain.tld/chain.pem
├── [lrwxrwxrwx root root]  domain.tld.crt -> ./domain.tld/fullchain.pem
├── [lrwxrwxrwx root root]  domain.tld.dhparam.pem -> ./dhparam.pem
└── [lrwxrwxrwx root root]  domain.tld.key -> ./domain.tld/key.pem

This behavior can be customized using the following environment variable on the letsencrypt-nginx-proxy-companion container:

• FILES_UID - Set the user owning the files and folders managed by the container. The variable can be either a user name if this user exists inside the container or a user numeric ID. Default to root (user ID 0).
• FILES_GID - Set the group owning the files and folders managed by the container. The variable can be either a group name if this group exists inside the container or a group numeric ID. Default to the same value as FILES_UID.
• FILES_PERMS - Set the permissions of the private keys and ACME account keys. The variable must be a valid octal permission setting and defaults to 644.
• FOLDERS_PERMS - Set the permissions of the folders managed by the container. The variable must be a valid octal permission setting and defaults to 755.

For example, FILES_UID=1000, FILES_PERMS=600 and FOLDERS_PERMS=700 will result in the following:

[drwxr-xr-x]  /etc/nginx/certs
├── [drwx------ 1000 1000]  accounts
│   └── [drwx------ 1000 1000]  acme-v01.api.letsencrypt.org
│       └── [drwx------ 1000 1000]  directory
│           └── [-rw------- 1000 1000]  default.json
├── [-rw-r--r-- 1000 1000]  dhparam.pem
├── [-rw-r--r-- 1000 1000]  default.crt
├── [-rw------- 1000 1000]  default.key
├── [drwx------ 1000 1000]  domain.tld
│   ├── [lrwxrwxrwx 1000 1000]  account_key.json -> ../accounts/acme-v01.api.letsencrypt.org/directory/default.json
│   ├── [-rw-r--r-- 1000 1000]  cert.pem
│   ├── [-rw-r--r-- 1000 1000]  chain.pem
│   ├── [-rw-r--r-- 1000 1000]  fullchain.pem
│   └── [-rw------- 1000 1000]  key.pem
├── [lrwxrwxrwx 1000 1000]  domain.tld.chain.pem -> ./domain.tld/chain.pem
├── [lrwxrwxrwx 1000 1000]  domain.tld.crt -> ./domain.tld/fullchain.pem
├── [lrwxrwxrwx 1000 1000]  domain.tld.dhparam.pem -> ./dhparam.pem
└── [lrwxrwxrwx 1000 1000]  domain.tld.key -> ./domain.tld/key.pem

If you just want to make the most sensitive files (private keys and ACME account keys) root readable only, set the environment variable FILES_PERMS to 600 on your letsencrypt-nginx-proxy-companion container.