nginx/README.md

# Nginx Docker Compose files

Docker Compose files to spin up an instance of Nginx.

# How to run

Add a `COMPOSE_ENV` file and save its location as a shell variable along with the location where this repo lives, here for example `/opt/containers/nginx` plus all other variables. At [env/fqdn_context.env.example](env/fqdn_context.env.example) you'll find an example environment file.

When everything's ready start Nginx with Docker Compose, otherwise head down to [Initial setup](#initial-setup) first.

## Environment

```
export COMPOSE_DIR='/opt/containers/nginx'
export COMPOSE_CTX='ux_vilnius'
export COMPOSE_PROJECT='nginx-'"${COMPOSE_CTX}"
export COMPOSE_FILE="${COMPOSE_DIR}"'/compose.yaml'
export COMPOSE_ENV=<add accordingly>
```

## Context

On your deployment machine create the necessary Docker context to connect to and control the Docker daemon on whatever target host you'll be using, for example:
```
docker context create fully.qualified.domain.name --docker 'host=ssh://root@fully.qualified.domain.name'
```

## Pull

Pull images from Docker Hub verbatim.

```
docker compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" pull
```

## Copy to target

Copy images to target Docker host, that is assuming you deploy to a machine that itself has no network route to reach Docker Hub or your private registry of choice. Copying in its simplest form involves a local `docker save` and a remote `docker load`. Consider the helper mini-project [quico.space/Quico/copy-docker](https://quico.space/Quico/copy-docker) where [copy-docker.sh](https://quico.space/Quico/copy-docker/src/branch/main/copy-docker.sh) allows the following workflow:

```
copy-docker 'nginx:latest' fully.qualified.domain.name
```

## Start

```
docker --context 'containers-1.ops.loft.seneve.de' compose --project-name "${COMPOSE_PROJECT}" --file "${COMPOSE_FILE}" --env-file "${COMPOSE_ENV}" up --detach
```

## Clean up

Get rid of unnecessary images on both the deployment and the target machine:
```
docker --context 'fully.qualified.domain.name' system prune -af
docker system prune -af
```

# Initial setup

We're assuming you run Docker Compose workloads with ZFS-based bind mounts. ZFS management, creating a zpool and setting adequate properties for its datasets is out of scope of this document.

## Datasets

Create ZFS datasets and set permissions as needed.

* Parent dateset
    ```
    export "$(grep -Pi -- '^CONTEXT=' "${COMPOSE_ENV}")"
    zfs create -o canmount=off zpool/data/opt
    zfs create -o mountpoint=/opt/docker-data zpool/data/opt/docker-data
    ```

* Container-specific datasets
    ```
    zfs create -p 'zpool/data/opt/docker-data/nginx-'"${CONTEXT}"'/nginx/conf'
    zfs create -p 'zpool/data/opt/docker-data/nginx-'"${CONTEXT}"'/nginx/data'
    ```
    This results in a directory structure like so:
    ```
    /opt/docker-data/nginx-loft/nginx
    ├── conf
    └── data
    ```
  
* Create subdirs
    ```
    mkdir -p '/opt/docker-data/nginx-'"${CONTEXT}"'/nginx/'{'conf/'{'certs','nginx/'{'conf.d','sites-enabled'}},'data/logs'}
    ```
    This creates the following dir structure:
    ```
    /opt/docker-data/nginx-loft/nginx
    ├── conf
    │   ├── certs
    │   └── nginx
    │       ├── conf.d
    │       └── sites-enabled
    └── data
        └── logs
    ```

* Change ownership
    ```
    chown -R 101:101 '/opt/docker-data/nginx-'"${CONTEXT}"'/nginx/'*
    ```

## Additional files

* Place an `ssl.conf` and an `nginx.conf` file on target server:
    ```
    /opt/docker-data/nginx-loft/nginx
    └── conf
        └── nginx
            ├── conf.d
            │   └── ssl.conf
            └── nginx.conf
    ```

* The `nginx.conf` file may look like so:
    ```
    user  nginx;
    worker_processes  auto;
    
    error_log  /var/log/nginx/error.log notice;
    pid        /var/run/nginx.pid;
    
    
    events {
        worker_connections  1024;
    }
    
    
    http {
        include       /etc/nginx/mime.types;
        default_type  application/octet-stream;
    
        log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                          '$status $body_bytes_sent "$http_referer" '
                          '"$http_user_agent" "$http_x_forwarded_for"';
    
        access_log  /var/log/nginx/access.log  main;
    
        sendfile        on;
        #tcp_nopush     on;
    
        keepalive_timeout  65;
    
        #gzip  on;
    
        include /etc/nginx/conf.d/*.conf;
        include /etc/nginx/sites-enabled/*.conf;
    }
    ```

* An `ssl.conf` file may look like so:
    ```
    server_tokens off;
    
    # For a 100% SSL rating at ssllabs.com
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_protocols TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers AES256+EECDH:AES256+EDH:!aNULL;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam sslcerts/dhparam.pem;
    ssl_ecdh_curve secp384r1;
    
    add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
    # In a Nextcloud instance these two are done internally by PHP nowadays.
    # Nextcloud's admin interface will complain if you do these via the reverse
    # proxy.
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    
    # End 100% SSL rating block
    ```

* Store SSL certificates as needed in `/opt/docker-data/nginx-${CONTEXT}/nginx/conf/certs`

*  Add per-site config files to `/opt/docker-data/nginx-${CONTEXT}/nginx/conf/nginx/sites-enabled` like so:
    ```
    /opt/docker-data/nginx-loft/
    └── nginx
        └── conf
            └── nginx
                └── sites-enabled
                    ├── name.domain.qualified.fully.conf
                    └── name.domain.a.also.conf
    ```
    Where an individual file may look like so. This largely depends on each application.
    ```
    server {
        listen                      80;
        server_name                 fully.qualified.domain.name;
    
        access_log /var/log/nginx/name.domain.qualified.fully_plain_access.log main;
        error_log /var/log/nginx/name.domain.qualified.fully_plain_error.log error;
    
        return 308 https://$server_name$request_uri;
    }
    
    server {
        listen                      443 ssl;
        listen                      [::]:443 ssl;
        http2                       on;
        server_name                 fully.qualified.domain.name;
        ssl_certificate             /etc/nginx/sslcerts/name.domain.qualified.fully_fullchain.cer;
        ssl_certificate_key         /etc/nginx/sslcerts/name.domain.qualified.fully.key;
        ssl_trusted_certificate     /etc/nginx/sslcerts/name.domain.qualified.fully_ca.cer;
    
        access_log /var/log/nginx/name.domain.qualified.fully_ssl_access.log main;
        error_log /var/log/nginx/name.domain.qualified.fully_ssl_error.log error;
    
        location / {
            proxy_pass http://fully.qualified.domain.name:63961;
            proxy_set_header Host $http_host;
            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 $scheme;
        }
    }
    ```

When done head back up to [How to run](#how-to-run).

# Development

## Conventional commits

This project uses [Conventional Commits](https://www.conventionalcommits.org/) for its commit messages.

### Commit types

Commit _types_ besides `fix` and `feat` are:

- `refactor`: Keeping functionality while streamlining or otherwise improving function flow
- `docs`: Documentation for project or components

### Commit scopes

The following _scopes_ are known for this project. A Conventional Commits commit message may optionally use one of the following scopes or none:

- `nginx`: A change to how the `nginx` service component works
- `build`: Build-related changes such as `Dockerfile` fixes and features.
- `mount`: Volume or bind mount-related changes.
- `net`: Networking, IP addressing, routing changes
- `meta`: Affects the project's repo layout, file names etc.