stiftung-management-system/docs/production-server-setup.md

Production Server Setup Guide

This guide will help you set up your production server for automated deployment from GitHub Actions.

Prerequisites

• A Linux server (Ubuntu 20.04+ recommended)
• SSH access to the server
• Domain name pointing to your server (optional)

Step 1: Connect to Your Server

ssh your-username@your-server-ip

Step 2: Update System

sudo apt update && sudo apt upgrade -y

Step 3: Install Docker and Docker Compose

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Logout and login again to apply group changes
exit
# Then reconnect via SSH

Step 4: Install Git

sudo apt install git -y

Step 5: Set Up Project Directory

# Create project directory
sudo mkdir -p /opt/stiftung
sudo chown deployment:deployment /opt/stiftung
cd /opt/stiftung

# Clone your repository (the deployment user with SSH key will handle this)
# If you have SSH key configured for the deployment user:
git clone git@github.com:remmerinio/stiftung-management-system.git .

# Alternative: If you need to use HTTPS with Personal Access Token:
# git clone https://github.com/remmerinio/stiftung-management-system.git .

# Copy environment template
cp env-template.txt app/.env

Step 6: Configure Environment Variables

Edit the production environment file:

nano app/.env

Add these settings (replace with your actual values):

# Django Settings
DJANGO_DEBUG=0
DJANGO_SECRET_KEY=your-very-long-secret-key-here
DJANGO_ALLOWED_HOSTS=your-domain.com,your-server-ip
LANGUAGE_CODE=de
TIME_ZONE=Europe/Berlin

# Database Settings
POSTGRES_DB=stiftung_prod
POSTGRES_USER=stiftung_user
POSTGRES_PASSWORD=your-secure-database-password
DB_HOST=db
DB_PORT=5432

# Redis Settings  
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

# Email Settings (optional)
EMAIL_HOST=smtp.your-provider.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@example.com
EMAIL_HOST_PASSWORD=your-email-password
EMAIL_USE_TLS=1

# Paperless-ngx Integration (if you're using Paperless)
# PAPERLESS_API_URL=http://your-paperless-server:port
# PAPERLESS_API_TOKEN=your-paperless-api-token
# PAPERLESS_REQUIRED_TAG=Your_Required_Tag
# PAPERLESS_LAND_TAG=Your_Land_Tag
# PAPERLESS_ADMIN_TAG=Your_Admin_Tag
# PAPERLESS_DESTINATAERE_TAG_ID=123
# PAPERLESS_LAND_TAG_ID=456
# PAPERLESS_ADMIN_TAG_ID=789

# Gramps Integration (if you're using GrampsWeb)
# GRAMPS_URL=http://your-gramps-server:port
# GRAMPS_USERNAME=your-gramps-username
# GRAMPS_PASSWORD=your-gramps-password

Step 7: Set Up Production Docker Compose

Copy the production Docker Compose file to the project root:

cp deploy-production/docker-compose.prod.yml .

Step 8: Generate Strong Secret Key

python3 -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Use this output as your DJANGO_SECRET_KEY in the .env file.

Step 9: Set Up SSL/HTTPS (Recommended)

If you have a domain name, set up SSL certificates:

# Install Certbot
sudo apt install snapd
sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot

# Create certificate
sudo certbot certonly --standalone -d your-domain.com

# The certificates will be in /etc/letsencrypt/live/your-domain.com/

Step 10: Configure Firewall

# Enable firewall
sudo ufw enable

# Allow SSH
sudo ufw allow ssh

# Allow HTTP and HTTPS
sudo ufw allow 80
sudo ufw allow 443

# Check status
sudo ufw status

Step 11: Initial Deployment

Run the first deployment manually:

cd /opt/stiftung

# Build and start containers
docker-compose -f docker-compose.prod.yml up -d --build

# Run initial migrations
docker-compose -f docker-compose.prod.yml exec web python manage.py migrate

# Create superuser
docker-compose -f docker-compose.prod.yml exec web python manage.py createsuperuser

# Collect static files
docker-compose -f docker-compose.prod.yml exec web python manage.py collectstatic --noinput

Step 12: Test the Deployment

Visit your server IP or domain name to verify the application is running.

Step 13: Enable Automatic Deployment

Once your server is properly set up, you can enable automatic deployment by editing .github/workflows/ci-cd.yml:

Change this line:

if: github.ref == 'refs/heads/main' && false  # Disabled until production server is set up

To:

if: github.ref == 'refs/heads/main'

Troubleshooting

If deployment fails:

1. Check Docker status:

   sudo systemctl status docker
   

2. Check container logs:

   docker-compose -f docker-compose.prod.yml logs
   

3. Restart services:

   docker-compose -f docker-compose.prod.yml restart
   

Common Issues:

• Permission denied: Make sure your user is in the docker group
• Port conflicts: Check if ports 80/443 are already in use
• Database connection: Verify your database settings in .env
• Static files: Ensure the web server can access static files

Monitoring and Maintenance

Check application status:

docker-compose -f docker-compose.prod.yml ps

View logs:

docker-compose -f docker-compose.prod.yml logs -f web

Update the application:

cd /opt/stiftung
git pull origin main
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d

Backup database:

docker-compose -f docker-compose.prod.yml exec db pg_dump -U stiftung_user stiftung_prod > backup_$(date +%Y%m%d_%H%M%S).sql

Security Recommendations

1. Keep system updated:

   sudo apt update && sudo apt upgrade -y
   

2. Use strong passwords for database and admin accounts

3. Enable fail2ban to prevent brute force attacks:

   sudo apt install fail2ban
   

4. Regular backups of your database and media files

5. Monitor logs for suspicious activity

Next Steps

After completing this setup:

1. Test the deployment pipeline by making a commit to the main branch
2. Set up monitoring and alerting for your application
3. Configure regular automated backups
4. Set up a staging environment for testing

Your production server is now ready for automated deployment from GitHub Actions!