docassemble Guided Interview and Document Assembly on AWS 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 AMI 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 instance. 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-instance secretkey, a per-instance PostgreSQL password and a per-instance 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 instance public IPv4 on first boot, so the web interface works immediately
• A dedicated 20 GiB EBS data volume at /var/lib/docassemble-data holding the PostgreSQL cluster and the docassemble file store, captured into the AMI and re-provisioned with every instance
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC with a subnet. m5.large (2 vCPU / 8 GiB RAM) is the recommended instance type; docassemble runs uWSGI and two Celery workers alongside PostgreSQL, Redis and RabbitMQ, so 8 GiB of RAM is comfortable for evaluation and small deployments. Security-group 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 - Launch from AWS Marketplace

Subscribe to the listing in AWS Marketplace, choose the docassemble on Ubuntu 24.04 delivery option, and launch it into your VPC and subnet with your key pair and a security group as above. On first boot the appliance generates its per-instance secrets and administrator account and sets external hostname / url root to the instance public IPv4. 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.

Connecting to your instance

SSH in as the default login user for the OS variant you launched:

ssh ubuntu@<public-ip>

Step 2 - Retrieve the per-instance 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:

sudo cat /root/docassemble-credentials.txt

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

Step 3 - Sign in to the web interface

Browse to http://<instance-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://<instance-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.

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 instance public IPv4 over plain HTTP as a working evaluation default. Before you publish real interviews you should:

1. Point a DNS name at the instance 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.

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-instance 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 volume:

findmnt /var/lib/docassemble-data

Data, storage and maintenance

The PostgreSQL cluster and the docassemble file store (uploaded and generated documents) live on the dedicated 20 GiB EBS data volume mounted at /var/lib/docassemble-data, which is captured into the AMI and re-provisioned with every instance. For a production instance, grow the data volume 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.