To install the Docassemble Docker image on Windows 11 Pro, you need to install Docker Desktop, configure it to use the WSL 2 backend, and execute the standard Docker run command.

Docassemble will run in Docker Desktop without you needing to install a separate Ubuntu or Debian Linux distribution in your Windows environment.

Here is the exact step-by-step procedure to get it up and running.

System Requirements:

Before starting, ensure your system fulfills the necessary resource limits:

Storage: At least 40GB of free hard drive space (Docassemble takes up about 20GB and requires an additional 20GB of free space to run smoothly).

Memory: Minimum 4GB of RAM.

Step 1: Install and Configure Docker Desktop Download https://docs.docker.com/desktop/setup/install/windows-install/ the Docker Desktop for Windows Installer.

Run the downloaded.exe file.

Ensure the option to “Use WSL 2 instead of Hyper-V” is checked when prompted during installation.

Follow the on-screen instructions, finish the setup, and restart your computer.

Launch Docker Desktop, accept the subscription service agreement, and leave it running in the background.

Step 2: Run the Docassemble Container

Once Docker is active, open Windows PowerShell or the Command Prompt as an Administrator and execute the appropriate command based on your port availability:

Option A: Run on default ports (Recommended). If your machine is not using ports 80 (HTTP) or 443 (HTTPS) for other web servers, run:

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

Note: –stop-timeout 600 is critical for Docassemble because it needs time to safely shut down its internal databases and SQL services when you stop the container.

Option B: Run on a custom port (If Port 80 is busy). If you already have a local development environment blocking port 80, map the traffic to an alternative port like 8080:

BASH

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

Step 3: Access Docassemble

After running the command, Docker will download the image layers from Docker Hub. This can take a few minutes. Open your web browser. Navigate to http://localhost (or http://localhost:8080 if you chose Option B). It may take 2 to 5 minutes for the system to complete its internal startup tasks on the first launch. If you see a server error initially, refresh the page after a short wait.

Q. If you plan to use this for serious development work, would you like to know how to map a persistent local directory so you don't lose your interviews and data when the container restarts?

Ans. We can check on that later.

Can we setup Docassemble with a fixed local network IP address and target that IP from a Linux Ubuntu server running Apache and use Reverse Proxy to publish the Docassemble to the internet with a fully qualified domain name?

Yes, we can absolutely route traffic through an external Ubuntu server running Apache. To achieve this, you need to ensure the Ubuntu box can physically talk to your Windows host IP address over a chosen port, configure Apache's reverse proxy modules, and inform the Docassemble container of its external identity.

Here is how to set up the configuration.

Step 1: Bind Docassemble to your Windows LAN IP instead of binding to localhost (which isolates traffic to your Windows PC), map Docker Desktop to your local network interface.

1. Find your Windows machine's local IP address (e.g., 192.168.1.50) by opening Command Prompt and typing ipconfig. You can configure Windows to use a fixed static IP address, or you can configure your router to assign a “reserved IP” from the DHCP pool of IP addresses that is tied to the MAC address of your network hardware interface.

2. Start the Docassemble container by binding it strictly to that IP and a chosen port (e.g., port 8080 so it doesn't conflict with any other Windows web servers). Note, you can use TCP port 80 on the Docassemble container if there are no other potentially conflicting web services running on port 80 of the Windows 11 Pro PC, and you are using the Apache2 reverse proxy configuration from your Linux Ubuntu server box (which defaults the proxy target to port 80 unless otherwise configured).

BASH

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

Step 2: Configure Apache on your Ubuntu Server.

A. On your Ubuntu server, Apache needs the proxy extensions enabled to capture incoming requests and pass them to the Windows machine.Log into your Ubuntu machine and enable the proxy modules:

bash

sudo a2enmod proxy proxy_http proxy_wstunnel rewrite headers

B. Create or modify an Apache Virtual Host configuration file (e.g., /etc/apache2/sites-available/docassemble-proxy.conf):

Apache:

<VirtualHost *:80>
    ServerName docassemble.yourdomain.local

    ProxyRequests Off
    ProxyPreserveHost On

    # Forward standard HTTP traffic to Windows 11
    ProxyPass / http://192.168.1.50
    ProxyPassReverse / http://192.168.1.50

    # Handle WebSocket connections (Critical for Docassemble's live interviews)
    ProxyPass /wsws http://192.168.1wsws
    ProxyPassReverse /wsws http://192.168.1wsws

    # Security headers to ensure Docassemble maps links correctly
    RequestHeader set X-Forwarded-Proto "http"
    RequestHeader set X-Forwarded-Port "80"

    ErrorLog ${APACHE_LOG_DIR}/docassemble_error.log
    CustomLog ${APACHE_LOG_DIR}/docassemble_access.log combined
</VirtualHost>

C. Enable the configuration and restart Apache:

bash

sudo a2ensite docassemble-proxy.conf
sudo systemctl restart apache2

Step 3: Update Docassemble's Configuration

Docassemble needs to know it is being accessed via a proxy domain so that it constructs external links, emails, and package management endpoints with the Ubuntu server's address instead of localhost.

A. Go to your web browser and open the configuration menu (once you can see it via the Ubuntu domain or the direct Windows IP).

B. Navigate to Configuration (System-wide configuration).

C. Add or update the following parameters:

yaml

external hostname: docassemble.yourdomain.local
behind https load balancer: false

(Note: If you eventually secure your Ubuntu Apache proxy using SSL/TLS Let's Encrypt certificates, change X-Forwarded-Proto to “https”, change port to 443 in Step 2, and switch behind https load balancer to true).

D. Click Save and let the container restart its background services.

Troubleshooting Windows Firewall Blockages

By default, Windows 11 Firewall blocks unsolicited inbound traffic to ports even if Docker maps them. If your Ubuntu server gets a 502 Bad Gateway or Connection Timed Out when trying to contact the Windows IP:

A. Open Windows Defender Firewall with Advanced Security on your Windows 11 machine.

B. Click Inbound Rules → New Rule.

C. Choose Port → Select TCP → Type 8080 into specific local ports.

D. Choose Allow the connection and apply it to your current network profile (Private domain recommended).

Are you planning to configure SSL/HTTPS on the Ubuntu Apache box right away, or do you want to test the routing over plain HTTP first?