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 folder of
isle-dc. If you navigate to that directory, you'll see several small
files, where each file represents a different password. By default, they are all set to
password and you can change them to set your
passwords for the system.
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
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.
||A PEM encoded private key used to sign your certificate|
||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.|
Using Let's Encrypt instead of Certificate Files¶
Full support for Let's Encrypt is not available yet with ISLE, but will be soon. It can be done by hand though. Just understand that it takes editing your
docker-compose.yml file, and those changes will be destroyed if you regenerate your
docker-compose.yml file for any reason. Be sure to back up your
docker-compose.yml file once you have things in place.
The acme.json file¶
Create an empty
acme folder in
isle-dc and bind mount it into Traefik. When Traefik start up, it will write
acme.json to this folder. Your
volumes section for
traefik in your
docker-compose.yml file should look like
volumes: - ./certs:/etc/ssl/traefik:rw - ./tls.yml:/etc/traefik/tls.yml:rw - ./acme:/acme:rw
Creating the certificate resolver¶
Add the following to the
commands section for
traefik to tell it to use Let's Encrypt.
--certificatesresolvers.myresolver.acme.httpchallenge=true --certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=http --firstname.lastname@example.org --certificatesresolvers.myresolver.acme.storage=/acme/acme.json --certificatesResolvers.myresolver.acme.caServer=https://acme-v02.api.letsencrypt.org/directory
Be sure to replace
email@example.com with the email address you've associated with Let's Encrypt.
Adding the certificate resolver to routes¶
For the Drupal, Matomo, and Cantaloupe services, you'll need to add labels to instruct Traefik to use the
myresolver certificate resolver you just created.
For example, for Drupal
If you are still getting security exceptions, check what certificate is being used through your browser. Setting
--log.level=DEBUG in the
traefik will help out greatly when debugging. You can tail the logs with
docker-compose logs -tf traefik
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, use
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.
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_SECREST=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