Docker Swarm Mode enables you to easily distribute apps and services across one or more servers. It is a great option for teams already comfortable working with the Docker container framework. 

On the Healthcare Blocks platform, Docker Swarm Mode includes the following features:

  • Git-based deployments
  • Automatic provisioning and renewal of LetsEncrypt SSL certificates
  • Shared, encrypted disk storage
  • Private Docker Registry for storing images
  • Traefik reverse proxy

How It Works

When you deploy (via git push) an application containing a Dockerfile definition, the Dockerfile is used to build an application image. The image is then launched as one or more "containers" using Docker Swarm Mode; each container represents an isolated set of processes. The services running in the containers are not directly accessible - instead, an HTTP reverse proxy listens to incoming requests (on port 80 and 443) and routes traffic accordingly using host names (e.g. app1.mydomain.com, app2.mydomain.com). 

Preparing Your First App

In your development machine, install Docker a create a Dockerfile appropriate for your application stack. Your Dockerfile should include a RUN statement that starts up your application's server. This same Dockerfile will be used in production to build and run your application. More information can be found here.

Ensure your app builds locally: 

docker build -t app .

...and runs successfully:

docker run -it app

You should see output that represents a running application. If you encounter an error and your container exits, you will need to debug and repeat the above steps until everything runs successfully. 

If you haven't done so already, create a local git repository for your application.

git init
git add .
git commit -m "Initial commit"

Now define a git remote to point to your Healthcare Blocks. This setting will enable you to deploy your application to your server via git. The values below will be provided to you by a support technician in your initial provisioning email.

git remote add hcb ssh://<username>@<server_id>.healthcareblocks.com/data/apps/<customer_name>/deploy.git

# example
git remote add hcb ssh://john@abc123.healthcareblocks.com/data/apps/mycompany/deploy.git

Configure App Settings on the Server

The following steps describe how to configure production-specific settings, including domain name, for your app.

First, establish an SSH connection to your server:

ssh <username>@<server_id>.healthcareblocks.com

Configuration variables will be injected into your application during build and run time. These variables can be retrieved from the application environment - most likely your Web framework has the ability to do this already. To view and modify existing variables, edit /data/apps/<app name>/.env.

The settings that affect how your application is deployed and accessed are stored in /data/apps/<app name>/docker-compose.yml. 

By default, your application is accessible at app.<server id>.healthcareblocks.com, as defined in the config file:

- "traefik.frontend.rule=Host:app.<server_id>.healthcareblocks.com"

You can append your own subdomain/domain like this:

- "traefik.frontend.rule=Host:app.<server_id>.healthcareblocks.com,www.mydomain.com"

The port setting refers to the port being used by your application, which depends on your application framework and any defaults you might have included in Dockerfile. Many modern Web frameworks use port 3000 or 5000. Note that this port is not exposed to the outside world.

- "traefik.port=3000

SSL Certificates

The reverse proxy automatically provisions LetsEncrypt.org certificates when a new app or service is deployed that has a "traefik.frontend.rule=Host:" rule listed in docker-compose.yml. Thus, your application will be available via HTTP and HTTPS.

If you'd like to use your own SSL certificates or like to configure HTTP to HTTPS redirects, please contact us.

Deploying Your App

After you've made any relevant configuration settings on the server, you are now ready to deploy back on your local machine:

git push hcb master

Viewing Your Application Log

docker service logs <app_name>

Tailing your log:

docker service logs --tail 10 -f <app_name>

Scaling Your Application

docker service scale <app_name>=<number_of_instances>

# example
docker service scale myapp=2

To check the progress of your scaling action, you can do:

docker service ps <app_name>

Proxy Web UI

Traefik includes an administrative Web UI that shows any apps and services it is tracking. However, this interface is not exposed publicly - you'll need to connect with an SSH tunnel by running the command on your local machine.

ssh -L 9000:localhost:8080 username@<server_id>.healthcareblocks.com

Note: if port 9000 is already taken on your machine (you'll see an error), you can use a different number. Now in your browser go to http://localhost:9000.