228 lines
4.6 KiB
Markdown
228 lines
4.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
cd /opt/markdown-app
|
|
docker-compose up -d
|
|
```
|
|
|
|
Verify the container is running:
|
|
|
|
```bash
|
|
docker-compose ps
|
|
docker-compose logs
|
|
```
|
|
|
|
### 3. Configure nginx
|
|
|
|
Copy the nginx configuration and enable it:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Check Docker logs
|
|
docker-compose logs
|
|
|
|
# Check if port 8080 is already in use
|
|
sudo lsof -i :8080
|
|
```
|
|
|
|
### nginx returns 502 Bad Gateway
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```dockerfile
|
|
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "--workers", "4", "--timeout", "120", "app:app"]
|
|
```
|