Standard Docker-Compose Deploys
I've been deploying a bunch of web apps recently, and it turns out there's one pattern that's so common it might even be called classic. Basically:
- Each subdomain should get routed to its own docker container.
blog.example.com
should hit a blogging container,app.example.com
should hit a React app, etc. - Caching, compression, and SSL (issuance and renewal) should be automatically handled.
This tutorial explains how to do all of that with a single docker-compose
file.
This cornerstone of this setup is a docker image called nginx-proxy
. Each time a request hits your server, this container checks the subdomain and chooses which docker container will handle it. It also handles caching, compression, and SSL (if the certificates are available).
To set it up, add the following to a docker-compose.yml
file.
version: '2'
services:
nginx-proxy:
image: nginxproxy/nginx-proxy
ports:
- '80:80'
- '443:443'
volumes:
- /etc/nginx/certs:/etc/nginx/certs
- /etc/nginx/vhost.d:/etc/nginx/vhost.d
- /usr/share/nginx/html:/usr/share/nginx/html
- /var/run/docker.sock:/tmp/docker.sock:ro
This file says that the service 'nginx-proxy' will be based on the image nginxproxy/nginx-proxy
, will communicate with the outside world on ports 80 and 443, and will be able to access the locations listed under volumes
on your host system.
To run it, install docker and docker-compose, then run docker-compose up
. If you navigate to localhost
, you should see a black-on-white nginx error. That's because there are no other containers for nginx-proxy
to forward your request to.
Let's add one. It will be an instance of Ghost, the popular blogging platform. Add this to the end of your docker-compose.yml
, under the services
heading.
ghost:
image: ghost
environment:
VIRTUAL_HOST: robertcunningham.xyz
VIRTUAL_PORT: 2368
url: https://robertcunningham.xyz
expose:
- 2368
volumes:
- ./ghost:/var/lib/ghost/content
The VIRTUAL_HOST
and VIRTUAL_PORT
variables tell nginx-proxy to forward requests for the root domain (robertcunningham.xyz
) to port 2368 of the ghost container. The url
variable tells Ghost where it'll live, and the volumes
heading provides a place on the host system where Ghost can save its files.
Re-run docker-compose up
, and navigate to your website (robertcunningham.xyz
, in our case). Behind the scenes, nginx-proxy
will delegate this request to the newly-created ghost container, and you should see a brand new installation of Ghost.
You can continue to do this for your other services. For example, to host your React app at app.robertcunningham.xyz
, you could add something like this:
robertsapp:
image: 43459873.dkr.ecr.us-east-1.amazonaws.com/robertsapp
expose:
- 8080
environment:
VIRTUAL_HOST: app.robertcunningham.xyz
VIRTUAL_PORT: 8080
This will download the docker image robertsapp
from Amazon ECR, and forward any requests for app.robertcunningham.xyz
to it.
Now we'll configure SSL. SSL is handled by a container called nginxproxy/acme-companion
. Its job is to check whether the SSL certificates on your disk exist and are up to date. If they're not, it issues or renews them. Then nginx-proxy
can use those certificates when it accepts incoming connections.
For this to work, add the following to the bottom of your docker-compose file.
nginx-proxy-ssl:
image: nginxproxy/acme-companion
volumes:
- /etc/acme.sh:/etc/acme.sh
- /var/run/docker.sock:/var/run/docker.sock:ro
volumes_from:
- nginx-proxy
environment:
#ACME_CA_URI: 'https://acme-staging-v02.api.letsencrypt.org/directory'
NGINX_PROXY_CONTAINER: 'nginx-proxy'
The volumes_from
statement allows the nginx-proxy-ssl
container to put the certificates in a place where nginx-proxy
can find them. If you uncomment the ACME_CA_URI
environment variable, you'll get your certificates from the LetsEncrypt staging environment. The staging environment is more forgiving with rate limits, and once everything works, you can comment out this line to get real certificates.
You'll also need to add the following to your ghost
container.
environment:
LETSENCRYPT_HOST: robertcunningham.xyz
LETSENCRYPT_EMAIL: [email protected]
And that's it! You're done. You can run docker-compose up -d
, which will run the process in the background, so it doesn't get terminated when you exit your SSH session. If you want to stop it in the future, you can run docker-compose down
.
That's it! Happy deploying.
If you're still unsure of anything, you can find the full docker-compose behind this website here for reference.
Notes
[1] This tutorial relies heavily upon docker. I'll make a quick plug for it here. Of all the developer tools I know, docker shares the title with git for most useful. If you don't know it, spend two hours today to learn it. It'll save you time for the rest of your life.