docassemble on Ubuntu 24.04 on Azure User Guide

Overview

docassemble is an open source expert system for guided interviews and automated document assembly. It leads a user through a branching question and answer interview, validates the answers, and assembles the results into finished PDF and Word documents from templates. Interviews are authored in a readable YAML format with Python logic, so complex conditional workflows, calculations and document generation run without bespoke application code. Originally built for the legal aid community, docassemble is used by legal services organisations, courts, government agencies and businesses.

The cloudimg image installs docassemble 1.10.5 the official non-Docker way as a self-contained appliance: a Python 3.12 virtualenv, pip install of the docassemble.base, docassemble.demo and docassemble.webapp distributions, with local PostgreSQL 16, Redis and RabbitMQ on loopback, four systemd services (uWSGI, two Celery workers and the websockets server) running as the unprivileged www-data user, and nginx in front. It generates the application secretkey, the PostgreSQL password and the administrator account uniquely on the first boot of each VM. Backed by 24/7 cloudimg support.

What is included:

• docassemble 1.10.5 installed the official non-Docker way (MIT licensed), on Python 3.12
• Four systemd services running as the unprivileged www-data user: docassemble-uwsgi (uWSGI on a loopback socket), docassemble-celery and docassemble-celerysingle (Celery background workers), and docassemble-websockets (the live interview server)
• PostgreSQL 16, Redis and RabbitMQ bound to loopback; nginx fronting the app on port 80 with an unauthenticated /healthz
• The full document assembly stack (pandoc, LibreOffice, a TeX Live subset, poppler-utils, pdftk-java, tesseract-ocr, ghostscript) so PDF and DOCX assembly works out of the box
• A per VM secretkey, a per VM PostgreSQL password and a per VM administrator account, all generated on first boot and recorded in a root only credentials file; none are baked into the image
• The external hostname and url root set automatically from the VM public IP on first boot, so the web interface works immediately
• A dedicated 20 GiB Azure data disk at /var/lib/docassemble-data holding the PostgreSQL cluster and the docassemble file store, captured into the image and re-provisioned with every VM
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_D2s_v3 (2 vCPU / 8 GiB RAM) is the recommended size; docassemble runs uWSGI and two Celery workers alongside PostgreSQL, Redis and RabbitMQ, so 8 GiB of RAM is comfortable for evaluation and small deployments. NSG inbound: allow 22/tcp from your management network, and 80/tcp (plus 443/tcp once you add your own TLS certificate) for the web interface.

Step 1 - Deploy from the Azure Marketplace

Launch the image from the Azure portal (search the Marketplace for "docassemble on Ubuntu 24.04 LTS by cloudimg", choose your size and networking, and create), or from the Azure CLI:

az vm create \
  --resource-group my-docassemble-rg \
  --name my-docassemble \
  --image <cloudimg-docassemble-image-urn> \
  --size Standard_D2s_v3 \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group my-docassemble-rg --name my-docassemble --port 80 --priority 900

On first boot the appliance generates its per VM secrets and administrator account and sets external hostname / url root to the VM public IP. docassemble is slow to warm on the very first request (it compiles templates and loads the interview engine), so allow a minute or two before signing in.

Step 2 - Retrieve the per VM administrator password

docassemble ships with no default login: the upstream default admin@admin.com / password account is never created. The first boot service creates a unique administrator account and writes it to a root only file. SSH in and read it:

ssh azureuser@<vm-ip>
sudo cat /root/docassemble-credentials.txt

You will see the administrator email, the per VM password, and the URL to use. The database lives on the dedicated data disk and the secretkey and PostgreSQL password are unique to this VM.

Step 3 - Sign in to the web interface

Browse to http://<vm-public-ip>/ and sign in with the email and password from the credentials file.

curl -s -o /dev/null -w 'sign-in page: HTTP %{http_code}\n' http://127.0.0.1/user/sign-in

Step 4 - Run a guided interview

docassemble's core feature is the guided interview: a branching question and answer flow that collects and validates answers and can assemble a document at the end. The appliance boots with a runnable demonstration interview so you can see the engine working immediately. Browse to http://<vm-public-ip>/ to start it, or open the full demonstration interview from the "Demo" menu.

Step 5 - Author your own interviews in the Playground

Sign in as the administrator and open the Playground (the pencil / development menu). The Playground is a live editor: write interview YAML on the left, press Run and see it render on the right, and use the Variables panel and example blocks to build up branching logic and document templates. When an interview is ready you publish it as a package and set it as your default interview.

The administrator Utilities page provides the document tooling: scan a PDF or DOCX template to extract its fillable fields, and generate translation files for the interview system phrases.

Step 6 - Set your own domain, TLS and email before production

docassemble builds absolute URLs from url root. The appliance boots with external hostname and url root set to the VM public IP over plain HTTP as a working evaluation default. Before you publish real interviews you should:

1. Point a DNS name at the VM and set external hostname and url root: https://your.domain in /usr/share/docassemble/config/config.yml.
2. Add a TLS certificate and an nginx :443 server block (Let's Encrypt with certbot --nginx is a good option), and set use https: True.
3. Configure a real SMTP server in the mail block of config.yml so docassemble can send registration and notification email.
4. For a production deployment set allow demo: False so the sample interviews are not publicly runnable, and set your own default interview.

After editing the config, restart the services with sudo systemctl restart docassemble-uwsgi docassemble-celery docassemble-celerysingle docassemble-websockets nginx (see the maintenance section below).

Verifying the deployment

All services run locally: PostgreSQL, Redis, RabbitMQ, uWSGI, the Celery workers and the websockets server on loopback, fronted by nginx on port 80.

systemctl is-active postgresql redis-server rabbitmq-server nginx docassemble-uwsgi docassemble-celery docassemble-websockets

The unauthenticated health endpoint returns 200:

curl -s -o /dev/null -w 'GET /healthz -> HTTP %{http_code}\n' http://127.0.0.1/healthz

docassemble has no default login, and only the per VM administrator password authenticates to the admin area:

sudo bash /usr/local/sbin/docassemble-cred-roundtrip.sh

The PostgreSQL cluster and the docassemble file store live on the dedicated data disk:

Data, storage and maintenance

The PostgreSQL cluster and the docassemble file store (uploaded and generated documents) live on the dedicated 20 GiB Azure data disk mounted at /var/lib/docassemble-data, which is captured into the image and re-provisioned with every VM. For a production instance, grow the data disk to suit your document volume and take regular backups of both the database and the file store. Keep the OS patched with unattended-upgrades (enabled by default).

Useful paths and commands:

• Configuration: /usr/share/docassemble/config/config.yml
• Credentials (root only): /root/docassemble-credentials.txt
• Logs: sudo journalctl -u docassemble-uwsgi -u docassemble-celery
• Restart: sudo systemctl restart docassemble-uwsgi docassemble-celery docassemble-celerysingle docassemble-websockets nginx

Support

This image is provided by cloudimg with 24/7 support. docassemble is open source software released under the MIT License. cloudimg is not affiliated with or endorsed by the docassemble project; "docassemble" is used only to identify the software packaged in this image.