Deployment of Arches (archesproject.org) via Docker. We initially developed this repo to simplify and streamline deployment of Arches for use in archaeology and related instruction.
This main goal of this repo is to offer a simple, turnkey approach to deploying HTTPS secured Arches on the Web. You can also use this to deploy the current stable version of Arches for use on a localhost
by leaving Arches with the Django DEBUG
setting as True
. See below for instructions on creating and editing an .env
file.
If you're interested in deploying Arches to a localhost
(not the public Web), switch to the local
code branch. That will deploy a limited subset of Docker containers needed to run Arches on a localhost
in DEBUG
mode. To switch to the local branch:
git checkout origin/local
If you're interested in testing a localhost
(only) deployment of Arches for Science (AfS), switch to the local-dev-1-1-x
code branch. That will deploy a limited subset of Docker containers needed to run AfS on a localhost
in DEBUG
mode:
git checkout origin/local-afs-dev-1-1-x
This approach automatically obtains and renews Let's Encrypt TLS certificates and set up HTTPS in Nginx for your domain name using Docker Compose.
You can set up HTTPS in Nginx with Let's Encrypt TLS certificates for your domain name and get A+ rating at SSL Labs SSL Server Test by changing a few configuration parameters of this example.
Let's Encrypt is a certificate authority that provides free X.509 certificates for TLS encryption. The certificates are valid for 90 days and can be renewed. Both initial creation and renewal can be automated using Certbot.
The approach currently only supports one domain name, as discussed in this example:
- teach-with-arches.org
The idea is simple. There are 3 containers:
- Nginx
- Certbot - for obtaining and renewing certificates
- Cron - for triggering certificates renewal once a day
The sequence of actions:
- Nginx generates self-signed "dummy" certificates to pass ACME challenge for obtaining Let's Encrypt certificates
- Certbot waits for Nginx to become ready and obtains certificates
- Cron triggers Certbot to try to renew certificates and Nginx to reload configuration on a daily basis
- The Nginx container uses updates symbolic links that point to either "dummy" certificates or Let's Encrypt certificates.
The following lists some information about the contents of this repo and how they fit together:
docker-compose.yml
.env
- specifiesCOMPOSE_PROJECT_NAME
to make container names independent from the base directory name. specifies project configuration, e.g. domain names, emails, database connection details, etc. This file contains sensitive information.arches/
Dockerfile
arches_data
- A directory on your host machine that gets attached to the Arches container. This makes it convenient to pass data (like packages or exports) in and out of your Arches container.conf.d/
- A directory of Supervisord configurations for the celery worker and celery beat processes. This gets copied into the Arches container.celery.py
- Editable file if you want to modify your Arches project use of celeryarches_proj-supervisor.conf
- Supervisord configurations for the celery worker and celery beat processesentrypoint.sh
- entrypoint script. This has some handy utility functions for some routine administration of the Arches container.settings_local.py
- Editable python file to define project specific settings for your Arches instance. Many of the environment variables that you assign in your.env
filesettings_local.py
- Editable python file configuring URLs in your Arches instance
certbot/
Dockerfile
certbot.sh
- entrypoint script
cron/
Dockerfile
renew_certs.sh
- script executed on a daily basis to try to renew certificates
html/
- directory mounted asroot
for Nginxindex.html
nginx/
Dockerfile
nginx.sh
- entrypoint script. This script will update where symbolic links will resolve (either to the dummy self-assigned certificates or to the Let's Encrypt obtained certificates)hsts.conf
- HTTP Strict Transport Security (HSTS) policyoptions-ssl-nginx.conf
- SSL related configurationsdefault.conf
- Nginx configuration for your domain. Contains a configuration to get A+ rating at SSL Server Test. This configuration also asks Nginx to gzip compress certain text-based static files (especially CSS and Javascript) which should help with performance. This config uses symbolic links to specify the path to SSL certificates.default.conf
- Nginx server configuration. It loads the Perl language module to simplify passing environment variables to your Nginx domain configuration.
webpack/
Dockerfile
webpack_entrypoint.sh
- Thewebpack
container is a minimalist container that invokes a docker command on thearches
container. This command prepares static assets for the Arches frontend by running webpack and collectstatic.
To adapt the example to your domain names you need to change only .env
:
DOMAINS=teach-with-arches.org
CERTBOT_EMAILS[email protected] [email protected]
CERTBOT_TEST_CERT=0
CERTBOT_RSA_KEY_SIZE=4096
Configuration parameters:
DOMAINS
- a space separated list of domains to manage certificates forCERTBOT_EMAILS
- a space separated list of email for corresponding domains. If not specified, certificates will be obtained with--register-unsafely-without-email
CERTBOT_TEST_CERT
- use Let's Encrypt staging server (--test-cert
)
Let's Encrypt has rate limits. So, while testing it's better to use staging server by setting CERTBOT_TEST_CERT=1
(default value).
When you are ready to use production Let's Encrypt server, set CERTBOT_TEST_CERT=0
.
- Docker and Docker Compose are installed.
- You have a domain name
- You have a server with a publicly routable IP address
- You have cloned this repository
git clone https://github.com/opencontext/arches-via-docker.git
This approach will setup the most current stable version of Arches (now v7.5.0). If you want to deploy Arches version 6 (specifically stable version 6.2.6), please switch to the v6
branch of this repo, with:
git checkout origin/v6
For all domain names configure DNS A records to point to a server where Docker containers will be running.
Specify you domain names and contact emails for these domains in the edit_dot_env
file and then save this file as .env
:
First make an .env
file
cp edit_dot_env .env
Now edit .env
file to change your settings.
nano .env
Here are properties to change based on your specific Web domain. Please note, for now this only supports one domain specified by the DOMAINS
variable (the plural is asperational..).
DOMAINS=teach-with-arches.org
CERTBOT_EMAILS[email protected]
Below are properties to edit to change how Arches deploy. If you want to deploy this on your own machine (localhost), setting DJANGO_DEBUG=True
is useful to see and diagnose useful error messages in the Arches Django application, but be sure to set DJANGO_DEBUG=False
for deployments on the public Web. NOTE if you run this on your localhost, this Docker build will currently make your Arches application available to your browser via https://127.0.0.1:8004/ on port 8004, not the usual 8000. This nonstandard port was chosen in case your local host has other applications already running on port 8000.
If you set BUILD_PRODUCTION=True
, be sure you have well over 8GB of system RAM. BUILD_PRODUCTION=True
will invoke the Arches manage.py build_production
command, and this command is very resource intensive and time consuming. You will likely get errors that will cause your build to fail if you do a production build on a server with only 8GB of RAM.
DJANGO_MODE=DEV
DJANGO_DEBUG=False
...
BUILD_PRODUCTION=False
docker volume create --name=logs_nginx
docker volume create --name=nginx_ssl
docker volume create --name=certbot_certs
docker volume create --name=arches_certbot
Configure to use production Let's Encrypt server in .env
:
CERTBOT_TEST_CERT=0
docker compose up --build
Stop the containers:
docker compose down
Re-create the volume for Let's Encrypt certificates:
docker volume rm certbot_certs
docker volume rm arches_certbot
docker volume create --name=certbot_certs
docker volume create --name=arches_certbot
Start the containers:
docker compose up
Besides setting up HTTPS and Nginx, this repo deploys an instance of Arches. Currently this will setup an "empty" Arches instance. You'll need to load it with your own data by loading a package or some other approach. Once you deploy Arches, you can use normal Arches management commands as so:
docker exec -it arches python3 manage.py [Arches management commands and arguments here]
You may run into weirdness permissions issues restarting the docker container. I solved it with:
sudo chmod 666 /var/run/docker.sock
This repo will hopefully streamline deployment of Arches for use on the Web. Eventually, we hope to use this as the basis for deploying instances of Arches for use in archaeological teaching and learning applications.
None of this code is very original. This repo started by forking: https://github.com/evgeniy-khist/letsencrypt-docker-compose
Some elements of this repo are also derived from: https://github.com/opencontext/oc-docker
and
https://github.com/archesproject/arches-for-science-prj
and
https://github.com/archesproject/arches-dependency-containers
and finally