SecureAnyCloud
Deployment guide

docassemble

Overview

This image runs docassemble 1.10.5, 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.

SecureAnyCloud installs docassemble the official non-Docker way as a self-contained appliance: a Python 3.12 virtualenv with pip-installed docassemble.base, docassemble.demo and docassemble.webapp distributions, 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. The image generates the application secretkey, the PostgreSQL password and the administrator account uniquely on the first boot of each VM, and is backed by 24/7 SecureAnyCloud support.

What you get:

  • 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, with nginx fronting the app on port 80 and 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 SecureAnyCloud support.

Prerequisites

You need 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. For NSG inbound rules, 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 by searching the Marketplace for "docassemble on Ubuntu 24.04 LTS by SecureAnyCloud", choosing your size and networking, and creating the VM. Or deploy from the Azure CLI:

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:docassemble-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-docassemble-rg \
  --name my-docassemble \
  --image sac1647283583153:docassemble-ubuntu-24-04:default:latest \
  --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, because 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

The file shows 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. To confirm that the sign-in page responds, run:

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 to 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, publish it as a package and set it as your default interview.

The administrator Utilities page provides the document tooling. You can 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

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, do the following:

  • Point a DNS name at the VM and set external hostname and url root: https://your.domain in /usr/share/docassemble/config/config.yml.
  • 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.
  • Configure a real SMTP server in the mail block of config.yml so docassemble can send registration and notification email.
  • 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. The maintenance section below repeats this command.

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. Check that they are active:

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. Run the check:

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

The PostgreSQL cluster and the docassemble file store live on the dedicated data disk, as described in the next section.

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, which is 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 SecureAnyCloud with 24/7 support. docassemble is open source software released under the MIT License. SecureAnyCloud is not affiliated with or endorsed by the docassemble project. The name "docassemble" is used only to identify the software packaged in this image.

Deploy on Azure

Launch docassemble on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure