Docker Deploy App
Deploy PDF Extractor to a New Server
This guide deploys PDF Extractor using Docker Compose, with Apache providing HTTPS access.
Requirements
- An Ubuntu server with Apache and Docker already installed.
- SSH access with root or sudo privileges.
- A domain or subdomain pointing to the new server.
- The complete application deployment ZIP, including:
- Dockerfile
- compose.yaml
- requirements.txt
- app.py
- static/ directory
Use the complete deployment ZIP for a new installation. An update-only ZIP may not contain everything required.
Example Settings
Replace these example values where necessary:
| Setting | Example |
|---|---|
| Application directory | /opt/pdfextractorwebapp |
| Website address | pdf.example.com |
| Deployment archive | pdf-extractor-web-full-deploy-2026-11-10.zip |
| Local application port | 8000 |
The project files reside in /opt/pdfextractorwebapp on the server. The application runs inside its Docker container.
1. Upload the Application
Upload the complete deployment ZIP to the new server's /tmp/ directory using SCP, SFTP, or your preferred file-transfer application.
2. Check Docker Compose
Connect to the server using SSH, then run:
sudo docker --version sudo docker compose version
Both commands should display version information.
If the second command fails, install the Docker Compose plugin for your Docker installation before continuing.
3. Extract the Application
Install unzip and curl if needed:
sudo apt update sudo apt install -y unzip curl
Create the application directory and extract the archive:
sudo mkdir -p /opt/pdfextractorwebapp cd /opt/pdfextractorwebapp sudo unzip -o /tmp/pdf-extractor-web-full-deploy-2026-11-10.zip
Confirm the project files are directly inside this directory:
ls -la
Dockerfile and compose.yaml should be visible.
4. Build and Start the Container
From the application directory, run:
sudo docker compose up -d --build
The first build downloads dependencies and may take several minutes.
- --build builds the application image.
- -d runs the container in the background.
Check the container:
sudo docker compose ps
Its status should show Up.
The supplied compose.yaml includes a restart policy so the application restarts after a server reboot, provided Docker starts automatically.
Enable Docker at startup:
sudo systemctl enable --now docker
5. Test the Application Directly
Before configuring Apache, test the application locally:
curl -fsS http://127.0.0.1:8000/health curl -I http://127.0.0.1:8000/
Expected results:
- The health endpoint returns {"status": "ok"}.
- The application page returns HTTP 200.
Do not continue until these checks pass.
To investigate a failure:
cd /opt/pdfextractorwebapp sudo docker compose logs --tail=100 pdf-extractor
The supplied configuration binds port 8000 to 127.0.0.1. Keep this setting so Apache handles public access.
6. Configure Apache
Enable the reverse-proxy modules:
sudo a2enmod proxy proxy_http
Create an Apache site configuration:
sudo nano /etc/apache2/sites-available/pdfextractor.conf
Paste the following, replacing pdf.example.com with your actual hostname:
<VirtualHost *:80>
ServerName pdf.example.com
ProxyRequests Off
ProxyPreserveHost On
ProxyTimeout 600
LimitRequestBody 53477376
ProxyPass "/" "http://127.0.0.1:8000/" connectiontimeout=5 timeout=600
ProxyPassReverse "/" "http://127.0.0.1:8000/"
ErrorLog ${APACHE_LOG_DIR}/pdfextractor-error.log
CustomLog ${APACHE_LOG_DIR}/pdfextractor-access.log combined
</VirtualHost>
The timeout accommodates longer PDF exports. The request-body limit accommodates the application's default 50 MB upload limit plus metadata.
If this hostname already has an Apache configuration, update that configuration instead of creating a competing virtual host.
Enable the site and validate the configuration:
sudo a2ensite pdfextractor.conf sudo apache2ctl configtest
If the result is Syntax OK, reload Apache:
sudo systemctl reload apache2
Test Apache's connection to the application:
curl -i -H "Host: pdf.example.com" http://127.0.0.1/health
Expected result: HTTP 200 and {"status": "ok"}.
7. Configure DNS and Firewall Access
At your DNS provider:
- Set the hostname's A record to the new server's public IPv4 address.
- If an AAAA record exists, update it to the new server's IPv6 address, or remove it if IPv6 is unused.
Allow inbound TCP ports 80 and 443 through the server firewall and any hosting-provider firewall.
If UFW is already active, allow Apache traffic:
sudo ufw allow 'Apache Full'
Do not enable UFW without first ensuring SSH access is allowed.
Port 8000 does not need public access.
If migrating an existing hostname, keep the old server running while DNS changes propagate.
8. Enable HTTPS
Setup_SSL
Ensure the HTTPS virtual host retains the ProxyPass and ProxyPassReverse settings, including timeout=600.
9. Verify the Deployment
Test the public HTTPS endpoint:
curl -fsS https://pdf.example.com/health
Open the website in a browser and verify:
- The interface loads.
- A PDF can be uploaded.
- Page previews work.
- An export downloads successfully.
- Multiple PDFs can be processed together.
Updating the Application Later
Upload the update ZIP to /tmp/, then run:
cd /opt/pdfextractorwebapp sudo unzip -o /tmp/UPDATE-FILENAME.zip sudo docker compose up -d --build curl -fsS http://127.0.0.1:8000/health curl -I http://127.0.0.1:8000/
Replace UPDATE-FILENAME.zip with the actual archive name.
Refresh the website after rebuilding.
Useful Commands
Run these commands from /opt/pdfextractorwebapp.
View Container Status
sudo docker compose ps
View Recent Application Logs
sudo docker compose logs --tail=100 pdf-extractor
Follow Application Logs
sudo docker compose logs -f pdf-extractor
Press Ctrl+C to stop following logs. This does not stop the container.
Restart the Application
sudo docker compose restart
Restarting does not apply source-code changes copied into the Docker image. Use a rebuild after updating application files.
Rebuild After Changes
sudo docker compose up -d --build
Stop the Application
sudo docker compose stop
View Apache Errors
sudo tail -n 100 /var/log/apache2/pdfextractor-error.log
Troubleshooting
Apache Displays a Proxy Error
Check the application directly:
curl -i --max-time 10 http://127.0.0.1:8000/health curl -I --max-time 10 http://127.0.0.1:8000/ sudo docker compose logs --tail=100 pdf-extractor
If the local application works, inspect the Apache configuration and error log.
Permission Denied for Static Files
If the container logs report PermissionError for /app/static/index.html, correct the source-file permissions and rebuild:
cd /opt/pdfextractorwebapp sudo chmod 755 static sudo chmod 644 app.py static/index.html static/app.js static/style.css sudo docker compose up -d --build
The corrected Dockerfile also normalizes these permissions during the build.
Exports Time Out
Confirm the active HTTPS virtual host includes timeout=600 on its ProxyPass directive.
Validate and reload Apache after changing its configuration:
sudo apache2ctl configtest sudo systemctl reload apache2
For unusually large exports, try fewer pages or smaller batches.