markdown-renderer/DEPLOYMENT.md

Deployment Guide

This guide covers deploying the Markdown Renderer application to a server with nginx using Docker.

Prerequisites

• Docker and Docker Compose installed on your server
• nginx installed and running
• sudo/root access to the server

Deployment Steps

1. Transfer Files to Server

Copy the application files to your server:

# On your local machine
scp -r /Users/brent/markdown user@yourserver:/tmp/markdown-app

# On the server
sudo mkdir -p /opt/markdown-app
sudo mv /tmp/markdown-app/* /opt/markdown-app/
sudo chown -R $USER:$USER /opt/markdown-app

2. Build and Start the Docker Container

cd /opt/markdown-app
docker-compose up -d

Verify the container is running:

docker-compose ps
docker-compose logs

3. Configure nginx

Copy the nginx configuration and enable it:

# Copy the configuration file
sudo cp /opt/markdown-app/nginx-markdown.conf /etc/nginx/sites-available/markdown

# Edit the configuration to set your domain name
sudo nano /etc/nginx/sites-available/markdown
# Change 'markdown.yourdomain.com' to your actual domain or server IP

# Enable the site
sudo ln -s /etc/nginx/sites-available/markdown /etc/nginx/sites-enabled/

# Test nginx configuration
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx

4. Enable Auto-Start on Server Boot

Install the systemd service:

# Copy the service file
sudo cp /opt/markdown-app/markdown-app.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable markdown-app.service

# Start the service
sudo systemctl start markdown-app.service

# Check status
sudo systemctl status markdown-app.service

5. Optional: Configure SSL with Let's Encrypt

If you want HTTPS (recommended for production):

# Install certbot
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx

# Obtain certificate (replace with your domain)
sudo certbot --nginx -d markdown.yourdomain.com

# Certbot will automatically configure nginx for HTTPS

Management Commands

View Logs

# Docker container logs
docker-compose logs -f

# nginx logs
sudo tail -f /var/log/nginx/markdown-access.log
sudo tail -f /var/log/nginx/markdown-error.log

# Systemd service logs
sudo journalctl -u markdown-app.service -f

Restart Services

# Restart the Docker container
sudo systemctl restart markdown-app.service
# OR
cd /opt/markdown-app && docker-compose restart

# Restart nginx
sudo systemctl restart nginx

Update the Application

cd /opt/markdown-app

# Pull new changes (if using git)
git pull

# Rebuild and restart
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# OR if using systemd service
sudo systemctl restart markdown-app.service

Stop Services

# Stop the Docker container
sudo systemctl stop markdown-app.service
# OR
cd /opt/markdown-app && docker-compose down

Firewall Configuration

If you have a firewall enabled, allow nginx:

# For ufw
sudo ufw allow 'Nginx Full'

# For firewalld
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Troubleshooting

Container won't start

# Check Docker logs
docker-compose logs

# Check if port 8080 is already in use
sudo lsof -i :8080

nginx returns 502 Bad Gateway

# Verify container is running
docker-compose ps

# Check if the app is responding
curl http://127.0.0.1:8080

Service doesn't start on boot

# Check service status
sudo systemctl status markdown-app.service

# Check if service is enabled
sudo systemctl is-enabled markdown-app.service

# View service logs
sudo journalctl -u markdown-app.service --no-pager

Accessing the Application

• If configured with a domain: http://markdown.yourdomain.com
• If using server IP: http://your.server.ip.address
• With HTTPS: https://markdown.yourdomain.com

Security Recommendations

1. Configure a firewall to only allow ports 80 (HTTP) and 443 (HTTPS)
2. Use HTTPS with Let's Encrypt certificates
3. Keep Docker and nginx updated
4. Consider adding rate limiting in nginx
5. Regularly update the application dependencies
6. Monitor logs for suspicious activity

Performance Tuning

The docker-compose.yml is configured with:

• 4 gunicorn workers (adjust based on CPU cores)
• 120-second timeout for PDF generation
• Log rotation (max 3 files of 10MB each)

To adjust workers, edit the Dockerfile CMD line:

CMD ["gunicorn", "--bind", "0.0.0.0:8080", "--workers", "4", "--timeout", "120", "app:app"]