DocAssemble Development

Docassemble Docker Upgrade and Deployment Problems: Containers, Data Storage, HTTPS and Memory

Short answer: Most docassemble Docker problems come from five things: a system upgrade done without persistent data storage, a container stopped too quickly, a stale cached image, configuration that lives in storage and silently overrides your new environment variables, or a server with too little memory or disk. Set up data storage before you upgrade anything.

docassemble ships as one Docker image (jhpyle/docassemble) that bundles NGINX, uWSGI, PostgreSQL, Redis, Celery and supervisord. That makes installs simple, but it also means one mistake during an upgrade can take the whole service down. This guide uses a symptom → cause → fix format, based on the official Installing on Docker docs and real GitHub issues.

Note: the code and commands below are examples based on the official docassemble documentation. Test them on a staging server before using them in production.

Quick diagnostic table

Symptom Likely cause Fix
Interviews, users or Playground files gone after upgrade No Docker volume, S3 or Azure storage, so docker rm deleted the data Always use data storage before a system upgrade
“Upgrade” done but nothing seems newer Docker reused an old cached image docker pull jhpyle/docassemble (or remove the old image) before docker run
New container restores an empty or broken database Old container was killed before it finished backing up docker stop -t 600, then check docker logs
Changed DAHOSTNAME, USELETSENCRYPT etc. but nothing changed Config file in storage takes precedence over env vars Edit the configuration file, or see ENVIRONMENT_TAKES_PRECEDENCE
HTTP 500 / uWSGI won’t load the app after installing a package Python dependency conflict (#932) Remove or pin the conflicting package; test in staging first
Celery and websockets crash-loop after an upgrade with No module named 'pkg_resources' Dependency pin in that release (#987, now closed) Upgrade to a release that includes the fix
Server slow, crashes, or upgrade fails part-way Under 4GB RAM, or disk full of old images 4GB RAM / 40GB disk minimum; prune old images and containers

What is the difference between upgrading docassemble packages and a system upgrade?

Answer: A package upgrade updates only docassemble’s Python code, using the “Upgrade” button under Package Management, and keeps the same container. A system upgrade replaces the container with a new image, which updates the operating system, Python and system libraries. You need a system upgrade every so often, and it is only safe when you use data storage.

The docs explain that most releases only change the Python code, but a system upgrade becomes necessary when the underlying operating system files change, when new Python packages stop working with old system files, or when docassemble needs a newer Python version (Installing on Docker).

Rule of thumb: use the Package Management button for routine updates, and plan a system upgrade (with a maintenance window) every few months or when the release notes call for one.

How do I safely do a docassemble system upgrade?

Answer: Stop the container with a long timeout so it can save the SQL database, Redis and files to data storage. Then remove the old container and image, pull the latest image, and run the same docker run command you used originally. On start-up, the new container restores your data and reinstalls your Python packages.

The steps from the official docs:

docker ps -a                      # find the container ID
docker stop -t 600 <containerid>  # give it up to 10 minutes to shut down safely
docker logs <containerid>         # confirm a clean shutdown
docker rm <containerid>
docker rmi jhpyle/docassemble
docker pull jhpyle/docassemble
docker run --env-file=env.list -v dabackup:/usr/share/docassemble/backup \
  -d -p 80:80 -p 443:443 --restart always --stop-timeout 600 jhpyle/docassemble

Use the same docker run flags as before, especially the -v volume and --env-file. If you leave out the volume, the new container starts empty.

Why did I lose my data after upgrading docassemble?

Answer: If you ran docassemble without a Docker volume, S3 or Azure blob storage, your database and files lived only inside the container. When you remove that container with docker rm, they are deleted. The docs warn that without one of these forms of data storage, your data will be lost if you attempt a system upgrade.

Before your next upgrade, choose one of these:

  • Docker volume (-v dabackup:/usr/share/docassemble/backup): the simplest choice. But moving to a new host means copying the volume, which can be slow. The docs suggest using docker volume create to put the volume on a separate drive, so you can rebuild the virtual machine without touching your data.
  • S3 or S3-compatible storage (S3ENABLE=true and the other S3 variables): lets you terminate a host, build a new one, point DNS at it and docker run, with no data copy. It suits AWS deployments in the USA or Australia, and it lets you pick a bucket region that meets data-residency needs.
  • Azure blob storage (AZUREENABLE=true and the other AZURE variables): the same benefits on Azure. Popular with UK organisations already using Microsoft 365, with UK South or UK West regions available.

Use docker volume ls to check which volumes exist. If dabackup isn’t there, you aren’t using a volume.

Why won’t my docassemble container start after an upgrade?

Answer: Usually the new container is trying to restore data that wasn’t saved cleanly, or a Python package you installed no longer works with the new environment. Check docker logs first, then the logs inside the container. Dependency conflicts after installing extra packages are a known cause of HTTP 500 errors on start-up.

Common patterns in public issues:

  • Package conflicts. In #932, installing the openai package through Package Management on 1.9.7 led to HTTP 500 errors and uWSGI failing to load the app after a restart (reported as a pydantic-core mismatch). Because Python packages you installed are reinstalled on every start-up, a bad package can break each new container too.
  • Release-specific dependency bugs. In #987, after an upgrade to 1.10.8 the celery, celerysingle and websockets processes crash-looped with ModuleNotFoundError: No module named 'pkg_resources'. The issue is closed. Read the open and recent issues before you upgrade a production server.
  • Database restore errors. In #658, a new container logged ERROR: database "docassemble" does not exist during the restore step, and then couldn’t start or install packages.

To get more detail in docker logs, set SUPERVISORLOGLEVEL=debug so supervisord prints log messages to the container output (Installing on Docker).

Why doesn’t docassemble pick up my new Docker environment variables?

Answer: Once the configuration file is stored in the persistent volume, S3 or Azure, its values take precedence over Docker environment variables. Environment variables mainly tell the server where to find the configuration and fill in a first configuration. To change settings later, edit the configuration (Configuration in the menu), or use ENVIRONMENT_TAKES_PRECEDENCE.

This catches out many teams who change DAHOSTNAME or TIMEZONE in env.list, rerun the container and see no change. Note that TIMEZONE defaults to America/New_York. UK servers should set Europe/London, and Australian servers a zone such as Australia/Sydney, or dates in documents can be off by a day.

How do I fix Let’s Encrypt and HTTPS problems in docassemble?

Answer: Set DAHOSTNAME to the public hostname, USEHTTPS=true, USELETSENCRYPT=true and LETSENCRYPTEMAIL, and publish ports 80 and 443. The DNS record must point at the server before the container starts, because certbot runs at start-up. If a load balancer handles HTTPS for you, use BEHINDHTTPSLOADBALANCER instead of USEHTTPS.

A minimal env.list from the docs:

DAHOSTNAME=docassemble.example.com
USEHTTPS=true
USELETSENCRYPT=true
LETSENCRYPTEMAIL=admin@example.com

Checklist:

  1. The DNS A record resolves to this server’s IP before you run the container.
  2. Ports 80 and 443 are open in your firewall or cloud security group. On AWS EC2 this is a common gap (see the request for SSL help on EC2 in #346).
  3. The docs warn: don’t set USEHTTPS=true behind a proxy that forwards unencrypted HTTP to your server. Use BEHINDHTTPSLOADBALANCER instead.
  4. If you change these values after first start, remember that the stored configuration wins (see the previous section).

On start-up, certbot either renews the existing certificate or creates a new one, and the Let’s Encrypt configuration is copied to data storage, so certificates survive system upgrades.

How much memory and disk does a docassemble server need?

Answer: The official docs say to run Docker on a machine with at least 4GB of memory and 40GB of disk. The install uses about 20GB, and you should always keep at least 20GB free. Smaller cloud instances often fail during start-up, package installs or upgrades, and each old image left on disk uses more space.

Practical steps for small servers:

  • Size up to at least 4GB RAM before blaming code.
  • Remove unused containers and images after each upgrade. The docs note that downloading too many copies of jhpyle/docassemble without deleting old ones is one of the easiest ways to run out of disk space. Old containers also block you from deleting their images.
  • Check free disk space before a system upgrade, not after it fails.

Should I pin a docassemble image version instead of using latest?

Answer: For production, yes, it’s wise. Versioned image tags exist (for example jhpyle/docassemble:1.9.7 is cited in #932), and #568 asked for tags because latest is unpredictable. Pin the tag, test the next version in staging, then move production.

A simple routine: run a staging container from the new tag with a copy of your data, test your key interviews and document outputs, then do the production system upgrade during a quiet period in your users’ time zone.

Frequently asked questions

Will a docassemble system upgrade delete my interviews? Not if you use a Docker volume, S3 or Azure blob storage, and stop the container with docker stop -t 600. Without data storage, removing the container deletes your data.

How often should I do a system upgrade? Use the Package Management “Upgrade” button for routine releases. Do a system upgrade when the release notes say one is needed, or periodically to get operating system security updates.

Can I move docassemble to a new server? Yes. With S3 or Azure storage: stop the container, build the new host, point DNS at it and docker run. With a Docker volume, you must copy the volume across first.

Why is my docassemble server so slow? Check that it has at least 4GB RAM and enough free disk. Old images and containers often fill the disk.


Need a hand with your docassemble server?

Upgrades and deployments are where small mistakes cause real downtime for clients and court users. If you’d like a second pair of eyes, our free docassemble audit reviews your hosting, data storage, HTTPS and upgrade setup and gives you a prioritised fix list.

Related reading: – Docassemble support and maintenance checklist – Fix a broken docassemble interview: common YAML and logic issues – Docassemble DOCX template errors (draft — link once published) – Docassemble PDF fill problems (draft — link once published)

Sources: docassemble.org — Installing on Docker (system upgrade, data storage, environment variables, Let’s Encrypt, hardware requirements); GitHub jhpyle/docassemble issues #932, #987, #658, #346, #568. Checked 1 Nov 2026.

More in this Docassemble troubleshooting series – Complete Docassemble troubleshooting guide – Docassemble DOCX template errors: causes and fixes – Docassemble PDF fill problems: fields, checkboxes and signatures – Docassemble support and maintenance

en_USEnglish
Scroll to Top