Deploy Piecewise With Docker

Install & Deploy Piecewise Using Docker

Using Docker and Docker Compose is the preferred method for deploying an instance of Piecewise, since it makes the application very portable and consistent across server environments.

First Steps

To install and run Piecewise, you'll need a server or VM. There are no special requirements for the application-- it's a basic web application with a Postgresql database. Measurement tests are conducted between the end user's web browser and M-Lab's servers. Piecewise provides the survey and test, and collects a copy of the results.

We recommend first deciding the URL you wish to use for the Piecewise instance, and setting up a DNS A/AAAA record pointing the URL to the IP address of your server or VM.

We also recommend installing a web server such as Nginx before installing Piecewise.

Once the URL resolves to your server/VM, you are ready to proceed.

Deploying Piecewise

There is an included docker-compose.yml file that will allow you to run it in a production configuration. First, clone the repo and from this directory run docker-compose:

docker-compose up --build -d

This will build the docker container from the current repository, download the official Postgres docker image, and configure them both (the -d flag will detach from the current shell so that you can leave it running, but you can omit it in order to leave the log output attached).

If this is the first time you've run it on this system, you'll want to run the database migrations to initialize the database:

docker-compose exec piecewise npm run db:migrations

and then optionally seed the database with a default admin user:

docker-compose exec piecewise npm run db:seeds

By default, it runs on http://localhost:3000, but you can place it behind a proxy such as Nginx in order to provide TLS support and other features.

Once your instance is deployed, access the administrative pages to configure your instance at: http:/localhost:3000/login

Using Nginx to Secure Local Ports for Piecewise Web Service

Piecewise containers expose specific ports, but serving the application over standard secure port 443 requires an additional web server like Apache or Nginx. An example nginx configuration file is provided below:

server {
	listen 80 default_server;
	server_name	_;
        return 301 https://$host$request_uri;
}

server {
	listen 443 ssl default_server;
	listen [::]:443 ssl default_server;
	server_name	<YOUR DOMAIN NAME>;

	root /var/www/html;
	client_max_body_size 4G;

	location / {
	 	proxy_set_header X-Real-IP $remote_addr;
	 	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	 	proxy_set_header Host $http_host;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_pass http://localhost:8080;
		proxy_redirect off;
	}

	location /api/ {
		proxy_set_header Host $http_host;
		#proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_redirect off;
		proxy_buffering off;
		proxy_pass http://localhost:8081/api/;
	}

	location /docs/ {
		#proxy_set_header X-Real-IP $remote_addr;
		#proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		#proxy_set_header Host $http_host;
		proxy_pass http://localhost:8081/docs/;
		#proxy_redirect off;
	}

   	ssl_certificate /etc/letsencrypt/live/<YOUR DOMAIN NAME>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<YOUR DOMAIN NAME>/privkey.pem;
}

server {
	listen 8443 ssl default_server;
	listen [::]:8443 ssl default_server;
	server_name	<YOUR DOMAIN NAME>;

	client_max_body_size 4G;

	location / {
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_set_header Host $http_host;
		proxy_redirect off;
		proxy_buffering off;
		proxy_pass http://localhost:8081;
	}

    ssl_certificate /etc/letsencrypt/live/<YOUR DOMAIN NAME>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<YOUR DOMAIN NAME>/privkey.pem;

}

Backups

To backup an instance of Piecewise running in a Docker container, run the following command:

docker exec <name of postgres container> pg_dumpall -c -U <database user, default piecewise> dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql

To restore:

cat <backup file>.sql | docker exec -t <name of postgres container> pg_dumpall -c -U <database user, default piecewise > dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql