1
0
docker-letsencrypt-nginx-pr.../docs/Persistent-data.md

121 lines
6.1 KiB
Markdown
Raw Normal View History

2019-01-11 18:58:49 +01:00
## Persistent data
### Named volumes (recommended)
2019-01-11 18:58:49 +01:00
When you follow instructions from Basic usage or Advanced usage, Docker will automatically create **named volumes** for every `--volume` / `-v` argument passed. Named volume will make it easy for you to mount the same persisted data even if you delete then re-create the container:
2019-01-11 18:58:49 +01:00
```shell
$ 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 \
2019-01-11 18:58:49 +01:00
-v /var/run/docker.sock:/tmp/docker.sock:ro \
nginxproxy/nginx-proxy
2019-01-11 18:58:49 +01:00
$ docker volume ls
DRIVER VOLUME NAME
local certs
local vhost
local html
2019-01-11 18:58:49 +01:00
```
### Anonymous volumes (not recommended)
2019-01-11 18:58:49 +01:00
If you don't prefix your volumes with a name, Docker will instead create **anonymous volumes** (volumes with a random name). Those volume persist after the container is deleted but aren't automatically re-mounted when you re-create the container. Their usage is **not recommended** as they don't provide any advantages over named volumes and make keeping tracks of what volume store which data way harder.
2019-01-11 18:58:49 +01:00
```shell
$ 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 \
2019-01-11 18:58:49 +01:00
-v /var/run/docker.sock:/tmp/docker.sock:ro \
nginxproxy/nginx-proxy
2019-01-11 18:58:49 +01:00
$ docker volume ls
DRIVER VOLUME NAME
local 287be3abd610e5566500d719ceb8b952952f12c9324ef02d05785d4ee9737ae9
local 6530b1b40cf89efb71aa7fd19bddec927fa2bcae59b04b9c1c850af72ffe0123
local f260f71fefadcdfc311d285d69151f2312915174d3fb1fab89949ec5ec871a54
2019-01-11 18:58:49 +01:00
```
### 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).
2021-04-04 22:58:22 +02:00
`-v certs:/etc/nginx/certs:rw` on the **acme-companion** container.
2019-01-11 18:58:49 +01:00
## Ownership & permissions of private and ACME account keys
2021-04-04 22:58:22 +02:00
By default, the **acme-companion** container will enforce the following ownership and permissions scheme on the files it creates and manage:
2019-01-11 18:58:49 +01:00
```
[drwxr-xr-x] /etc/nginx/certs
├── [drwxr-xr-x root root] accounts
│ └── [drwxr-xr-x root root] acme-v02.api.letsencrypt.org
2019-01-11 18:58:49 +01:00
│ └── [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-v02.api.letsencrypt.org/directory/default.json
2019-01-11 18:58:49 +01:00
│ ├── [-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
```
2021-04-04 22:58:22 +02:00
This behavior can be customized using the following environment variable on the **acme-companion** container:
2019-01-11 18:58:49 +01:00
* `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-v02.api.letsencrypt.org
2019-01-11 18:58:49 +01:00
│ └── [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-v02.api.letsencrypt.org/directory/default.json
2019-01-11 18:58:49 +01:00
│ ├── [-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
```
2021-04-04 22:58:22 +02:00
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 **acme-companion** container.