initial commit
This commit is contained in:
227
DEPLOYMENT.md
Normal file
227
DEPLOYMENT.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# 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"]
|
||||
```
|
||||
Reference in New Issue
Block a user