This describes the configuration of the main nginx container for the charlesreid1.com pod.
The nginx container is critical to routing operations on charlesreid1.com, so we cover how the configuration files are split up and organized on this page, and include a summary of each file below.
Where are the nginx config files?¶
Nginx configuration files are located in the
submodule of this repository, which points to the
Within that repository is the
folder, which contains several
What Files Are There?¶
We have three sets of files present:
HTTP config files that redirect HTTP traffic on port 80 to be HTTPS traffic on port 443, one for each top-level domain (charlesreid1.com, charlesreid1.blue, and charlesreid1.red):
HTTPS rules for charlesreid1.com endpoints (the wiki,
phpMyAdmin, and ignoring
HTTPS rules for subdomains (pages.charlesreid1.com, hooks.charlesreid1.com, bots.charlesreid1.com):
HTTP Config Files¶
The HTTP config files are listed below:
The HTTP config files do the following:
- Requests for port 80 (for a domain or subdomain) are always redirected to port 443 for the same domain/subdomain
HTTPS Config Files¶
The HTTPS config files are listed below:
The HTTPS config files (without "subdomain" in their name) do the following:
/are redirected to the htdocs folders mentioned above
/wiki/are reverse-proxied to the local Apache+PHP container on port 8989
(Optional) requests for
/phpMyAdmin/are reverse-proxied to the local phpMyAdmin container on port 80
git.charlesreid1.comare reverse-proxied to the local Gitea container on port 3000
files.charlesreid1.comare reverse-proxied to the local Python files on port 8081
HTTPS Subdomain Config Files¶
The HTTPS subdomain config files are listed below:
The subdomains config files redirect requests for a set of subdomains on charlesreid1.com, namely:
This charlesreid1.com docker pod will redirect requests for these subdomains to another server running another docker pod, called the webhook docker pod, available at docker/pod-webhooks).
The webhook docker pod runs an nginx server, both to serve up static sites that live under the https://pages.charlesreid1.com domain, and to handle webhook traffic - the container also runs a Python webhook server that receives webhooks from git.charlesreid1.com, which enables push-to-deploy functionality similar to Github Pages.
Why All The Config Files?¶
If everything is stuffed into a smaller number of nginx config files, they become long and unwieldy, and more prone to mistakes.
- HTTP config files only contain redirects
- HTTPS (no subdomain) config files handle
Getting Configuration Files Into Container¶
The configuration files are mounted into the container
by bind-mounting the
conf.d folder of the
/et/nginx/conf.d in the container.
This is done in the charlesreid1 pod docker-compose file.
The nginx container hosts static content, in addition to serving as a reverse-proxy for several other services. This section covers how static content is treated by the charlesreid1.com nginx container
Outside the Container:
Static content hosted by the container is stored on the host
Each site (e.g., charlesreid1.com) has its own folder, containing the source for the static site and an htdocs folder containing the static content actually being hosted.
Additionally, because the static content for the site is actually
contained on the
gh-pages branch of charlesreid1/charlesreid1.com,
htodcs folder is actually a git repository. When it is
cloned, it is cloned such that the git repo's contents go into
/www/charlesreid1.com/htdocs/ and the contents of the
folder go into
This allows the site static content to be updated to reflect the
contents of the
gh-pages branch by pulling the latest upstream
changes into htdocs.
The directory structure used is as follows:
/www /charlesreid1.com /charlesreid1-src ...source for pelican site... /htdocs ...static content... /git ...dot git folder... /charlesreid1.blue /charlesreid1-blue-src ...source for pelican site... /htodcs ...static content... /git ...dot git folder... /charlesreid1.red /charlesreid1-red-src ...source for pelican site... /htodcs ...static content... /git ...dot git folder...
This directory structure can be achieved using the following bash command:
REPOURL="https://git.charlesreid1.com/charlesreid1/charlesreid1.com.git" git -C /www/example.com \ clone \ --separate-git-dir=git \ -b gh-pages \ $REPOURL htdocs
The dotfiles/debian repository contains scripts for krash, which runs the charlesreid1.com pod, to set up the directory structure as above, as well as scripts to pull the latest changes from upstream for each of the live web directories above.
Inside the Container:
Once the contents of the
/www/ directory have been set up,
the content can be made avialable inside the container by
bind-mounting the htdocs directories into the
inside the container. This is done with the following
volume directives in the
volumes: - "/www/charlesreid1.blue/htdocs:/www/charlesreid1.blue/htdocs:ro" - "/www/charlesreid1.red/htdocs:/www/charlesreid1.red/htdocs:ro" - "/www/charlesreid1.com/htdocs:/www/charlesreid1.com/htdocs:ro" ...
Utility Scripts: Updating Site Contents¶
of the debian/dotfiles](https://git.charlesreid1.com/dotfiles/debian)
repository, there are several utility scripts to help with
setting up and updating this directory structure.
To set up the directory structure, use the
1 2 3 4 5 6 7 8 9
#!/bin/bash REPOURL="https://git.charlesreid1.com/charlesreid1/charlesreid1.com.git" git -C /www/example.com \ clone \ --separate-git-dir=git \ -b gh-pages \ $REPOURL htdocs
To update the contents of the
htdocs/ folder using the latest changes
gh-pages branch, use the
1 2 3 4 5
#!/bin/bash git -C /www/example.com \ --git-dir=git --work-tree=htdocs \ pull origin gh-pages
We utilize Let's Encrypt to issue SSL certificates for our domain. This is a pain because of the need to automatically renew certificates every 90 days, and because of missing information in their documentation.
Where To Put Certificates¶
We leave the certificates where Let's Encrypt puts them, namely, in
The certificates are bind-mounted into the container at the same location,
then contains the following:
volumes: - "/etc/letsencrypt:/etc/letsencrypt" ...
Which Server Needs Certificates¶
Because the d-nginx-charlesreid1 docker container is serving as the front-end nginx server handling all incoming charlesreid1.com web requests, it is also the one negotiating HTTPS sessions with clients, so it is the container that needs the Let's Encrypt certificates.
This means that, for example, the SSL certificate for
pages.charlesreid1.com is on krash, even though the
content served up by the site is on blackbeard.
Getting and Renewing Certificates¶
Once you have worked everything out and gotten auto-renew cron scripts running smoothly, everything is unicorns and rainbows. But when you hit the Let's Encrypt rate limit because they did not explain it properly in the documentation, you may want everyone to die.
Let's Encrypt provides a command line utility called certbot that can be used to automate the process of creating and renewing certificates.
See the charlesreid1/certbot repository for scripts. The basic setup is as follows:
Certificates must be renewed every 90 days. I run the certificate renewal script in the root acount's crontab every 15 days so the certs never expire.
There are three top-level domains controlled by pod-charlesreid1:
There are several subdomains available on charlesreid1.com.
Hosted on krash:
Hosted on blackbeard: