Installing a Production/Staging Server¶
If you are deploying Islandora on a server that is publicly accessible, there's extra precautions you should take for
performance and security reasons. If you follow these steps, you'll see how we can use our
codebase folder to build
a custom Drupal container, and bake code into the container instead of bind-mounting it in. We'll also cover how to
store passwords as secrets and set up TLS.
If you haven't already made a local environment, you'll want to do that first. These instructions build off of having a codebase folder.
Using your Domain¶
At this point, we're assuming that you've purchased a domain to use for your repository. By default,
islandora.traefik.me is used, which
is fine for
make demo and
make local. But for your production site, you'll need to set the domain you own in your .env file.
Sensitive information, such as passwords, should never be built into a container. It also shouldn't ever be bind-mounted in like we do with our codebase folder. If you use secrets, it's like bind-mounting in a file, except that file is provided from the host machine to the container using an encrypted channel.
To use secrets, set the following in your .env file
The secrets themselves are stored in the
secrets/live folder of
isle-dc. If you navigate to that directory, you'll see several small
files, where each file represents a different password. They are each randomly generated when you run
All public facing sites need to use HTTPS, and it's definitely a stumbling block for the uninitiated. Fortunately,
set up to use HTTPS by default. Even when running
make demo, your site runs over HTTPS at
Using your own certificates¶
The default certificates are stored in the
certs folder of
isle-dc, and you can simply overwrite them with certificates from your
certificate authority. As long as the certificates match the
DOMAIN variable in your
.env file, that is. Changing the files in the
certs folder requires restarting the Traefik container, which you can do by running
docker-compose restart traefik.
|cert.pem||A PEM encoded certificate that also contains the issuer's certificate as well. Most certificate authorities offer "Full Chain" or "With Issuer" certificates that contain everything you need. Occassionally, you may find yourself needing to manually concatenate your certificate with the issuer certificate by hand. In that case, the certificate for your site goes first, and the issuer's certificate is appended afterwards.|
|privkey.pem||A PEM encoded private key used to sign your certificate|
Requesting Certificates through Let's Encrypt¶
To use Let's Encrypt to acquire your SSL Certificate, set the following in your .env file and run
make -B docker-compose.yml && make up.
Be sure to replace
email@example.com with the email address you've associated with Let's Encrypt.
The way this is setup, is it performs an HTTP Challenge to verify you are in control of the domain. So your system will need to be accessible at
??? warning "Let's Encrypt Rate Limit" If you aren't careful, you can hit Let's Encrypt's rate limit, and you'll be locked out for up to a week! If you want to use their staging server instead while testing things out, add the following to your .env file
``` ACME_SERVER=https://acme-staging-v02.api.letsencrypt.org/directory ```
You'll still get security exceptions when it's working, but you should be able to check the certificate from the browser and confirm you are getting it from the staging server.
Troubleshooting Certificate Issues¶
If you are still getting security exceptions, check what certificate is being used through your browser. Setting
TRAEFIK_LOG_LEVEL=DEBUG in your
.env file will help out greatly when debugging Traefik. You can tail the logs with
docker-compose logs -tf traefik.
traefik.me SSL certificate expired or revoked¶
The *.traefik.me certificate that covers
islandora.traefik.me will need to be redownloaded ocassionally, due to the certificate expiring or possibly being revoked. You can download the updated certificates by performing the following commands:
rm certs/cert.pem rm certs/privkey.pem make download-default-certs docker-compose restart traefik
traefik.me Certificate Note
Please note that sometimes the upstream provider of the traefik.me certificate takes a couple of days to update the certificiate after it expires or is accidently revoked.
Requesting Certifcates through ACME and External Account Binding¶
To request certificates through another Certificate Authority (CA) that supports External Accounting Binding through ACME such as InCommon or ZeroSSL you will need to add the following to your
USE_ACME=true ACME_EMAILfirstname.lastname@example.org ACME_SERVER= ACME_EAB_KID= ACME_EAB_HMAC=
ACME_SERVER is the CA server to use,
ACME_EAB_KID is the key identifer from the External CA, and
ACME_EAB_HMAC is the HMAC key from the External CA.
Once you have added these commands you will need to run the following commands:
make -B docker-compose.yml make up
Building and Deploying Your Custom Container¶
First, set your
ENVIRONMENT variable to
custom in your .env file in addition to the changes outlined above
ENVIRONMENT=custom USE_SECRETS=true DOMAIN=your-domain.org
Then rebuild your dockerfile to have your changes take effect
make -B docker-compose.yml
After this, you can build your custom container with
You then deploy the container with
docker-compose up -d