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:

1. Set the hostname's A record to the new server's public IPv4 address.
2. 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:

1. The interface loads.
2. A PDF can be uploaded.
3. Page previews work.
4. An export downloads successfully.
5. 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.

References

• Docker Compose: build and start containers
• Apache reverse-proxy guide
• Certbot documentation