INSTALL.txt

## Installation and basic operation of the Nginx load balancer
Setup TransIP API (needed for Let's Encrypt's DNS method)
Either copy `transip-rsa.key` and `transip.ini` from another server
(e.g., Oxygen) to the `docker` directory, or if there is no existing API
key, create a new one on the TransIP website copy it here in a file
called `docker/transip.key` and run:
   $ cd docker
   $ openssl rsa -in transip.key -out transip-rsa.key
   $ chmod 660 transip-rsa.key
   $ rm transip.key
   $ echo 'certbot_dns_transip:dns_transip_username = openstate' > transip.ini
   $ echo 'certbot_dns_transip:dns_transip_key_file = transip-rsa.key' >> transip.ini

Whitelist the IPv4 and IPv6 addresses of this server in the API configuration
settings on transip.nl

Copy the following file and view it to see how to configure new websites
- Copy docker/nginx/conf.d/default.conf.example to docker/nginx/conf.d/default.conf

Create the directory `html` which can be used to serve static files
   $ mkdir ../html

Before starting a new Nginx load balancer container make sure that:
   - no other container exists with the name `docker_c-nginx-load-balancer_1`
     or which binds port 80 and/or 443, otherwise creating a new container will
     fail
   - `docker/nginx/conf.d/default.conf` contains all relevant `server` blocks

Create and start the container:
   $ cd docker
   $ sudo docker-compose up -d

NOTE: When editing docker/nginx/nginx.conf with vim, make sure to add the
following line to your ~/.vimrc file otherwise the container will not receive
any changes you made to it (see
https://forums.docker.com/t/modify-a-file-which-mount-as-a-data-volume-but-it-didnt-change-in-container/2813/11):
   - set backupcopy=yes
NOTE2: If you edit docker/nginx/nginx.conf, push it to GitHub and pull it to the
servers, use `fab deploy-and-restart`, as `docker-compose restart` is required to
update the new inode (otherwise the new `nginx.conf` is not mounted in the
container)


Always test your configuration before going live with it!
   $ sudo docker exec docker_c-nginx-load-balancer_1 nginx -t

Reload the configuration:
   # Simple: From the host
   $ sudo docker exec docker_c-nginx-load-balancer_1 nginx -s reload

   # Alternative: From the container
   # Enter the container
   $ sudo docker exec -it docker_c-nginx-load-balancer_1 sh
   # In the container run the following commands
   $ nginx -t
   $ nginx -s reload
   # press ctrl + d to exit the container

Or combine both testing and reloading by using the reload.sh script
   $ cd docker
   $ ./reload.sh


## How to update Nginx (and Certbot)
- NOTE: never(!) run `docker-compose down` as this removes the docker network and all containers won't be able reconnect to the new network!
- Check the most recent version of Nginx Alpine on https://hub.docker.com/_/nginx
    - Also check the changelog (especially for 'Security' related fixes) on http://nginx.org/en/CHANGES
- Change the version of Nginx Alpine in `docker/docker-compose.yml`
    - (optional) change the version of Certbot in `docker/Dockerfile-cerbot` (see the most recent version https://hub.docker.com/r/certbot/certbot/tags and check the changelog https://github.com/certbot/certbot/blob/master/CHANGELOG.md)
    - (optional) change the version of certbot-dns-transip in `docker/Dockerfile-cerbot` (see the most recent version https://github.com/hsmade/certbot-dns-transip/releases)
- Rebuild and create the new container
   # Use Fabric to deploy the new Nginx version on multiple servers
   $ fab deploy-and-up
   # If you also updated Cerbot/certbot-dns-transip then run
   $ fab deploy-certbot

   # Alternative
   $ cd docker
   $ sudo docker-compose up -d
- You will see some `nginx: [warn] conflicting server name...` messages, these are expected during the build process and can be ignored


## Nginx load balancer container won't start
It has happened that after a server reboot the docker_nginx-load-balancer_1 container won't start/restart and just gives an error like this (NOTE: this error is different from a simply misconfigured nginx conf file error): Starting docker_c-nginx-load-balancer_1 ... error
If this is the case you can force a container recreation using `sudo docker-compose up -d --force-recreate`


## How to add basic access authentication (i.e. password protect) to a directory
# NOTE: we use `.htpasswd-<website>` below because you need to create a new
# file(name) for each different website you want to add a password to, so don't
# add multiple lines to the same `.htpasswd` file as this will allow all
# users/passwords to work for all websites that reference this `.htpasswd`
# file.
- Create a `.htpasswd-<website>` file containing the username. The
`.htpasswd-<website>` file should be stored in the `docker/nginx/conf.d`
directory:
   $ sudo sh -c "echo -n '<USERNAME>:' >> docker/nginx/conf.d/.htpasswd-<website>"
- Generate the password, after running this command you will be asked to input a
password and repeat it:
   $ sudo sh -c "openssl passwd -apr1 >> docker/nginx/conf.d/.htpasswd-<website>"
- Add the following two lines to a `server` or `location` block in
`docker/nginx/conf.d/default.conf`:
   auth_basic "Please login";
   auth_basic_user_file /etc/nginx/conf.d/.htpasswd-<website>;
- Reload Nginx