Deploy Docassemble on Oracle Cloud's Free and Powerful Ampere VM

Sci-fi depiction of a supercomputer generated by DALL·E 2

Background

I have been using Amazon Lightsail to run docassemble instances since 2020. I would recommend this approach for those starting out with cloud hosting and who can afford a minimum spend of $20 a month. Lightsail abstracts a lot of the complexity and configuration options that are typically present with offerings from AWS, Azure and GCP (with the same compute capacity typically also being about half the price). For a quick-start guide to getting going with a Lightsail deployment, see the guide provided by Suffolk's Legal Innovation & Technology Lab. 

I have been meaning to explore alternative cloud hosting platforms like Digital Ocean and Hetzner, which I suspect might be more cost effective, but am yet to get round to it. Then, a couple of months ago, I came across a reference to 'Oracle's free 4vCPU, 24GB RAM machine' in a comments thread discussing Windmill (a really interesting sounding open source platform). 

Those specs and the word 'free' piqued my interest. After some investigation, I discovered that Oracle Cloud has a very generous free tier with Always Free resources. Since my discovery, I have been happily running my development environment on the aforementioned rather beastly machine. Server restarts (necessitated when a python module is updated) are significantly faster and things in general are perceptibly more snappy. Given that I spend most of my day developing on docassemble, this constitutes a major quality of life improvement. The fact that my bank balance is not impacted is just the icing on top. 

Oracle Cloud

Each tenancy gets the first 3,000 OCPU hours and 18,000 GB hours per month for free to create Ampere A1 Compute instances using the VM.Standard.A1.Flex shape (equivalent to 4 OCPUs and 24 GB of memory).  An OCPU provides CPU capacity equivalent of one physical core of an Intel Xeon processor with hyper threading enabled. Each tenancy also gets two VM.Standard.E2.1.Micro instances for free.

What this means practically is that you can deploy an Ampere VM.Standard.A1.Flex Virtual machine, with a 4 core OCPU, 24 GB memory for free. One need not be as greedy as me, and could rather choose to deploy 4 instances of 1 OCPU, 6 GB machines, or say two 2 OCPU, 12 GB machines. There is then the added bonus of the two VM.Standard.E2.1.Micro instances, which while not suitable for running docassemble, can be used for other things like hosting a blog. 

However, there are a few things to keep in mind. The Oracle Cloud service isn't as beginner-friendly as others like Lightsail and even for a seasoned cloud user, learning a new layout can be annoying. Additionally, because the server's underlying architecture is Arm, you will need to use docker build to build the jhpyle/docassemble-os and jhpyle/docassemble images. Furthermore, running docassemble on Arm architecture is considered experimental. Although I haven't encountered any unexpected behavior beyond the two documented known issues, it's something to be aware of.

Setting everything up can be a bit finicky, so I'll outline the steps I followed for anyone interested in trying this out. If you are new to cloud hosting or docassemble, I would highly recommend first immersing yourself in the excellent documentation on Installing on Docker. 

Create your always free account

The first thing to do is to sign up for Oracle's alway free account. Note that you will be required to input valid credit card details, but I can confirm that you will need to explicitly upgrade before you will be charged for any services that fall outside of the alway free tier. 

Spin up your VM

Once you have logged into your console, select the OS image and the VM shape. For my setup, I chose Ubuntu 22.04 (the commands below are thus specific to this OS) and used the maxed out Ampere ARM instance type (4 OCPUs with 24GB of RAM).

Download the private and public SSH keys that you will use later for connecting to the VM. 

You can also adjust the default storage (I believe you get up to 200gb on the always free tier). Create your instance. 

After a couple of minutes, your VM will be good to go. 

Configure your network

To allow incoming http and https traffic, you will need to open ports 80 and 443 on the firewall. 

Repeat for port 443

The VM that you created above by default comes with an ephemeral public IP address. This means that the public IP address is tied to the life of the instance. This somewhat defeats one of the most powerful aspects of docassemble when deployed with cloud backup, namely the ability to destroy not only a container but the instance itself. This feature allows you to seamlessly upgrade docassemble and also upgrade or downgrade your VM. 

But I digress. All that just to say that you will want to add a static IP address to your instance.  

Then navigate to your instance, then click on 'Attached VNICs'. 

Change the Public IP type to no public IP and then go back and change it to Reserved public IP (selecting the static IP you created above). 

If you intend to use HTTPS, you will need to point a sub-domain of your domain to the public IP address. Log onto your domain provider's DNS console and create a sub-domain A record that points to the static IP address. 

Take steps to get cloud storage ready

Oracle provides S3 compatible bucket object storage (with up to 10gb on the free tier). You will need to create a policy that allows your user to interact with Buckets. You will then need to create a bucket that you will use with your VM.

Lastly, you will need credentials to access your bucket. 

Navigate to Identity -> Domains -> Default domain -> Users -> <your_username>.

Generate a secret key. The key, together with the secret key, will be be used below in the env.list file. 

Install docker and build the docassemble images 

SSH into your instance. Oracle provides comprehensive instructions for different operating systems if this is new to you. I like to use Visual Studio Code's built in terminal with two extensions - Remote Explorer and Remote - SSH. 

Once you are in, run the following commands:

(
sudo apt update && sudo apt upgrade -y
sudo reboot
)

And then:

(
# Install packages to allow apt to use a repository over HTTPS
sudo apt -y install apt-transport-https ca-certificates curl software-properties-common
# Add Docker’s official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# Set up the stable repository with the correct architecture
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Update the apt package index again
sudo apt -y update
# Verify that Docker CE will be installed from the Docker repository
apt-cache policy docker-ce
# Install the latest version of Docker CE
sudo apt -y install docker-ce
# Add your user to the docker group to run docker commands without sudo
sudo usermod -aG docker ${USER}
# Reboot the system to apply the changes
sudo reboot
)

This should not take too long, probably about 5min. You are then ready to build the docassemble images. This is the part that is different from a usual deployment. As mentioned above, given that the underlying architecture is ARM, the images have to be built from scratch. Run the following commands:

(
# Clone the 'docassemble' repository from GitHub
git clone https://github.com/jhpyle/docassemble
git clone https://github.com/jhpyle/docassemble-os
# Change the current working directory to 'docassemble-os'
cd docassemble-os
# Build the OS image 'jhpyle/docassemble-os' from the Dockerfile in the current directory
docker build -t jhpyle/docassemble-os .
# Change the current working directory to 'docassemble' which is in the parent directory
cd ../docassemble
# Build the docassemble image 'jhpyle/docassemble' from the Dockerfile in the current directory
docker build -t jhpyle/docassemble .
# Reboot the system to apply the changes
sudo reboot
)

Note that building the OS image will take a good amount of time, probably somewhere in the region of an hour.

Launch

If you are not intending on using HTTPS or cloud backup, then you can immediately kick things off with: 

docker run -d -p 80:80 -p 443:443 --restart always --stop-timeout 600 jhpyle/docassemble

If you have configured a sub-domain to point to your static IP and taken the steps to allow for cloud backup, then you will want to create an env.list file to use with your docker run command. 

DAHOSTNAME=demo.lawtechno.com # swap with the subdomain that you configured
S3ENABLE=true
S3BUCKET=demo-lawtechno-com # swap with the name of the bucket you assigned
S3ACCESSKEY=8335b78cc56012345575605c0d8a685e7207358 # swap with your access key
S3SECRETACCESSKEY=TBzHyqbCFSDwn45H8SLKnR7ZjWERW1yvOXqX16G0= # swap with your secret key
S3ENDPOINTURL=https://prdx1cvs2amt.compat.objectstorage.af-johannesburg-1.oraclecloud.com #swap the prdx1cvs2amt and the af-johannesburg-1 with your bucket's namespace and region code 
S3REGION=af-johannesburg-1 # swap with your region code
TIMEZONE=Africa/Johannesburg # swap with your timezone
USEHTTPS=true
USELETSENCRYPT=true
LETSENCRYPTEMAIL=ryan@lawtechno.com # swap with your email 

Once you have saved your env.list file, you are ready to make the final incantation:

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

After a few minutes, you should be able to visit the sub-domain that you configured and get started with your deployment of docassemble. You will also want to confirm that you correctly wired everything up with your bucket by checking that objects are now present in your bucket.  

The above turned out to be rather image dense. If anybody is struggling with following along, please let me know and I will post an video run through. 

There are other resources in the always free tier like databases that could be used with your docassemble development, but I am yet to explore these. 

If this was useful or if anything is not clear, happy to receive feedback in the comments. Also curious to hear of other hosting tips or tricks that you might have.