Installing a docassemble server

What this guide is#

There are a lot of ways you can install Docassemble. This is one quick path that will help you get started quickly without having to make your own choices.

  1. Provision a full virtual machine in AWS Lightsail.
  2. Wire up the file storage and backups to AWS S3.
  3. Use an env.list file that contains all of the startup configuration that I keep a local copy of.

Why? This gets you:

  1. A cheap, easy to use, always on server. Provisioning the same server for full-time usage on EC2 or Azure would be at least 2 times the price.
  2. The safety of all configuration and databases, files and backups being stored and served from S3.
  3. The ability to easily destroy and restore a new copy of your server.

What you miss out on:

  1. Automated load balancing and auto scaling that comes with EC-2.
  2. Clustering and managed docker that you get with docker swarm or Lightsail containers.

Things that I don't do but should consider:

  1. Using docker compose instead of just an env.list

Setting up Docassemble, start to finish#

Create your AWS account#

Follow Amazon's instructions

Choose a DNS name#

If you want to be able to reach your server over the Internet, you must add a DNS entry for it. You can use a subdomain of an existing domain name you control.

I recommend using something short, like apps.example.com (where example.com is a domain name you already own.) If you don't own a domain name yet, it may be simplest to purchase and manage it through AWS Route 53.

I still recommend using a subdomain of the new domain you purchase, rather than pointing docassemble directly to a top level domain.

Create your Lightsail server#

Create a Lightsail instance

Choose Ubuntu Server (the newest edition) as the operating system type.

Choose the 4 GB instance as the size, unless you have a very good reason to choose otherwise. Docassemble can run with fewer than 4 GB of RAM if you set up a swap file. You will probably not need more than 4 GB of RAM until you reach a very high traffic level or have a lot of developers working on your server at the same time.

Choose an AWS region that matches your needs. E.g., one that is geographically close to your users or that is not subject to US jurisdiction if required by data privacy laws in your country.

Label the new Lighsail instance with the DNS name you chose earlier. For example: apps.example.com.

Optionally: take note of the IPv6 address that AWS automatically assigns to your new Lightsail instance.

Create a static IPv4 address#

Follow the AWS Lightsail instructions to create a static IP. Use the DNS name you chose earlier to label the IP. Like: apps.example.com-IP.

Enable HTTPS traffic on your Lightsail server#

  1. Click on your Lightsail instance, and then the Networking tab. (Note: make sure you click on the instance name first).
  2. Scroll down to IPv4 Firewall. Click + Add rule to add a new rule.
  3. Select "HTTPS" as the application, and then the green "create" button.

This should also create the matching IPv6 rule automatically for you.

Create a DNS entry with the new DNS name you chose#

Create a new A record that points to your new IP address and matches the DNS name you chose earlier. The instructions for this vary depending on where your DNS is hosted. The AWS documentation is pretty confusing. Here are some good instructions on the Pantheon website.

Optionally: create an AAAA record that points to the IPv6 IP address that matches your new Lightsail instance. This will allow people to access your new server over IPv6 and is a good future-proofing step with no cost.

Create an S3 Bucket to match your new DNS name#

Follow the instructions to create an AWS S3 bucket using the AWS console.

You will make a new S3 bucket with these configuration options:

  1. Named the same as your DNS name. E.g., apps.example.com
  2. Matches the AWS region of your Lightsail instance.
  3. Use the default security policy, including Block Public Access.

Create an IAM user that has appropriate access to your S3 bucket#

I tend to create an S3 user with "Full Access" permissions, because the AWS account only includes S3 buckets that Docassemble is intended to access.

Visit the Identity Access and Management (IAM) console in AWS. Create a new user with the same name as your DNS name. E.g., apps.example.com.

For AWS Access type, select "Programmatic access" and then click Next.

Under Set permissions, choose "Attach existing policies directly".

Under "filter policies", type S3. Check the box next to AmazonS3FullAccess.

Click next and don't modify anything on the Tags page. Click Next: Review, and then Create user.

Copy the Access key ID and Secret access key to a safe place, such as an open text editor window. This is your only chance to view the secret access key.

Finish installation on your Lightsail instance over SSH#

Connect with SSH#

Follow the AWS instructions to connect to your new server with SSH. I recommend using either Putty or another 3rd-party SSH client, but the browser-based SSH console will work in a pinch.

Either way, I suggest downloading the default lightsail SSH keypair and keeping a copy somewhere safe.

Update the server#

From the SSH console, type the following commands, hitting enter after one:

sudo apt update
sudo apt upgrade -u -y

Install docker#

Type the command below to install docker

sudo apt install docker.io

Add your user account to the Docker group#

Type the following commands in the SSH console:

sudo usermod -aG docker $USER
newgrp docker

Create an env.list file#

In an editor of your choice, copy the following text:

DAHOSTNAME=apps.example.com
S3ENABLE=true
S3BUCKET=apps.example.com
S3ACCESSKEY=
S3SECRETACCESSKEY=
S3REGION=us-east-2
TIMEZONE=America/New_York
USEHTTPS=true
USELETSENCRYPT=true
LETSENCRYPTEMAIL=apps@example.com

Update the values as follows:

  • Under DAHOSTNAME, set it to your DNS name.
  • Under S3 bucket, set it to your DNS name.
  • Set the S3ACCESSKEY to your Access key ID.
  • Set the S3SECRETACCESSKEY to your secret access key that you wrote down earlier.
  • Set the S3 region to the appropriate region you selected.
  • Set the Timezone to the matching "tz database time zone" name that you want to be the default on your server. This will be used in log files and to set the time that daily scheduled cron scripts run.
  • Set LETSENCRYPTEMAIL to an email of your choice. You will receive messages at this address if your certificate is about to expire, but otherwise will not.

Notice that in the Docker environment file, we use a lowercase true, not True.

Create a new file on the server named env.list and copy the settings from your text editor into the file on the server. Here is one way you can do that:

nano env.list
[shift-insert or right mouse click to paste]
[CTRL+O, CTRL+X to save and exit the Nano editor]

Here is where using a 3rd party SSH console and not the Amazon SSH console is helpful. Amazon's web-based SSH console is very bad at handling copy and paste.

Save this env.list file locally somewhere secure. It is the one important file that will not be backed up to S3 if something goes wrong on your server.

Start Docker#

Start up your new docassemble server like this:

docker run -d -p 443:443 -p 80:80 --restart always --env-file env.list jhpyle/docassemble

If you are running Docker on a server you own instead of AWS#

Make sure that you set up persistent volumes. Both your startup command and your env.list file will look different.

Sit back and wait#

In a few minutes, your Docassemble server will be up and running. Visit the website at the DNS name you chose, https://apps.example.com. Log in with the default username and password, admin@admin.com/password. Change it to something more secure.

How many servers do I need?#

I recommend at least 2 servers: a production server and a development server. You may also want a test server, for a total of 3.

Production should have the most stable version of Docassemble. Development can test bleeding edge code. Test should mirror Production as much as possible.

If you want to configure load balancing, that is something I have not experimented with in Docassemble. Cost will be much higher but it may be worthwhile. You still will want at least a test/dev and production environment.

Further reading#

For a lot more detail, review Installation and also the configuration pages.