Install Config Wiki

All about installing, configuring and troubleshooting

User Tools

Site Tools

Trace: • installing_docassemble_docker_image_desktop_windows_11_pro
installing_docassemble_docker_image_desktop_windows_11_pro

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
installing_docassemble_docker_image_desktop_windows_11_pro [2026/07/27 22:03] – wikiadmininstalling_docassemble_docker_image_desktop_windows_11_pro [2026/07/27 22:42] (current) – wikiadmin
Line 2: Line 2:
  
 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. 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. Here is the exact step-by-step procedure to get it up and running.
Line 35: Line 37:
 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. 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
 +
 +<code>
 +docker run -d -p 8080:80 --restart always --stop-timeout 600 jhpyle/docassemble
 +</code>
 +
 +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
 +
 +<code>
 +docker run -d -p 192.168.1.50:8080:80 --restart always --stop-timeout 600 jhpyle/docassemble
 +</code>
 + 
 +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
 +
 +<code>
 +sudo a2enmod proxy proxy_http proxy_wstunnel rewrite headers
 +</code>
 +
 +B.  Create or modify an Apache Virtual Host configuration file (e.g., /etc/apache2/sites-available/docassemble-proxy.conf):
 +
 +Apache:
 +
 +<code>
 +<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>
 +
 +</code>
 +
 +C.  Enable the configuration and restart Apache:
 +
 +bash
 +
 +<code>
 +sudo a2ensite docassemble-proxy.conf
 +sudo systemctl restart apache2
 +</code>
 +
 +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
 +
 +<code>
 +external hostname: docassemble.yourdomain.local
 +behind https load balancer: false
 +</code>
 +
 +(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?
  
installing_docassemble_docker_image_desktop_windows_11_pro.1785189794.txt.gz · Last modified: 2026/07/27 22:03 by wikiadmin