CheckInApp/deployment/DEPLOYMENT.md

CheckIn App V2 - Deployment Guide

This guide explains how to deploy CheckIn App V2 to a production server using Nginx and systemd.

Table of Contents

1. Prerequisites
2. Server Setup
3. Application Setup
4. Nginx Configuration
5. Systemd Service Setup
6. SSL/TLS Certificate
7. Monitoring and Logs
8. Troubleshooting

---

Prerequisites

• Operating System: Ubuntu 20.04+ or similar Linux distribution
• Python: 3.9 or higher
• Node.js: 16+ (for building frontend)
• Nginx: 1.18 or higher
• Domain name (optional but recommended for SSL)

Install Required Packages

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python and tools
sudo apt install -y python3 python3-pip python3-venv

# Install Node.js (using NodeSource)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Install Nginx
sudo apt install -y nginx

# Install other dependencies
sudo apt install -y git curl wget

---

Server Setup

1. Create Application User

# Create a dedicated user for the application
sudo useradd -r -m -s /bin/bash checkin
sudo usermod -aG www-data checkin

2. Create Application Directory

# Create directory structure
sudo mkdir -p /opt/checkin-app
sudo chown -R checkin:www-data /opt/checkin-app

# Create required subdirectories
sudo -u checkin mkdir -p /opt/checkin-app/{data,logs,sessions}

---

Application Setup

1. Clone Repository

# Switch to application user
sudo su - checkin

# Clone the repository
cd /opt/checkin-app
git clone https://github.com/your-repo/checkin-app.git .

# Or upload your files using scp/rsync

2. Setup Backend

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install Python dependencies
pip install -r backend/requirements.txt

# Create .env file
cp .env.example .env

# Edit .env and configure your settings
nano .env

Important Environment Variables:

# Database
DATABASE_URL=sqlite:///./data/checkin.db

# Security
SECRET_KEY=your-secret-key-here-change-this
ALLOWED_ORIGINS=https://your-domain.com

# QQ Login (if applicable)
QQ_APPID=your-qq-appid
QQ_APPSECRET=your-qq-appsecret

# Email notifications (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
ADMIN_EMAIL=admin@your-domain.com

3. Initialize Database

# Run database migrations if needed
# Example:
# alembic upgrade head

# Or run initialization script
python backend/scripts/create_admin.py

4. Build Frontend

# Install frontend dependencies
cd frontend
npm install

# Build for production
npm run build

# Verify build output
ls -lh dist/

5. Set Permissions

# Exit from checkin user
exit

# Set proper permissions
sudo chown -R checkin:www-data /opt/checkin-app
sudo chmod -R 755 /opt/checkin-app
sudo chmod -R 775 /opt/checkin-app/{data,logs,sessions}

---

Nginx Configuration

1. Copy Configuration

# Copy example configuration
sudo cp /opt/checkin-app/deployment/nginx.conf.example /etc/nginx/sites-available/checkin-app

# Edit configuration
sudo nano /etc/nginx/sites-available/checkin-app

2. Update Configuration

Replace the following placeholders:

• your-domain.com → Your actual domain name
• /opt/checkin-app → Your installation path (if different)

3. Enable Site

# Create symbolic link
sudo ln -s /etc/nginx/sites-available/checkin-app /etc/nginx/sites-enabled/

# Remove default site (optional)
sudo rm /etc/nginx/sites-enabled/default

# Test Nginx configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

---

Systemd Service Setup

1. Copy Service File

# Copy example service file
sudo cp /opt/checkin-app/deployment/checkin-app.service.example /etc/systemd/system/checkin-app.service

# Edit service file
sudo nano /etc/systemd/system/checkin-app.service

2. Update Service File

Replace placeholders:

• User=www-data → User=checkin (if using dedicated user)
• WorkingDirectory=/opt/checkin-app → Your installation path
• Adjust paths in ExecStart if needed

3. Enable and Start Service

# Reload systemd
sudo systemctl daemon-reload

# Enable service (start on boot)
sudo systemctl enable checkin-app.service

# Start service
sudo systemctl start checkin-app.service

# Check status
sudo systemctl status checkin-app.service

# View logs
sudo journalctl -u checkin-app -f

---

SSL/TLS Certificate

Using Let's Encrypt (Recommended)

# Install Certbot
sudo apt install -y certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# Follow the prompts to configure SSL

# Test auto-renewal
sudo certbot renew --dry-run

The Certbot will automatically update your Nginx configuration with SSL settings.

Manual Certificate Setup

If you have your own SSL certificate:

# Copy certificate files
sudo mkdir -p /etc/nginx/ssl
sudo cp your-cert.crt /etc/nginx/ssl/
sudo cp your-key.key /etc/nginx/ssl/

# Set permissions
sudo chmod 600 /etc/nginx/ssl/your-key.key

# Update Nginx configuration with certificate paths

---

Monitoring and Logs

Service Logs

# View service logs
sudo journalctl -u checkin-app -f

# View last 100 lines
sudo journalctl -u checkin-app -n 100

# View logs since yesterday
sudo journalctl -u checkin-app --since yesterday

Application Logs

# Backend logs
tail -f /opt/checkin-app/logs/backend.log

# Nginx access logs
sudo tail -f /var/log/nginx/checkin-app-access.log

# Nginx error logs
sudo tail -f /var/log/nginx/checkin-app-error.log

Service Status

# Check service status
sudo systemctl status checkin-app

# Check if port is listening
sudo netstat -tlnp | grep :8000

# Check process
ps aux | grep python

---

Troubleshooting

Service Won't Start

# Check service logs
sudo journalctl -u checkin-app -xe

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

# Verify permissions
ls -la /opt/checkin-app/

# Test manual start
sudo -u checkin /opt/checkin-app/venv/bin/python /opt/checkin-app/run_daemon.py

Nginx Errors

# Test Nginx configuration
sudo nginx -t

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

# Verify backend is running
curl http://localhost:8000/health

Database Issues

# Check database file permissions
ls -la /opt/checkin-app/data/

# Check if database is locked
fuser /opt/checkin-app/data/checkin.db

# Backup database
cp /opt/checkin-app/data/checkin.db /opt/checkin-app/data/checkin.db.backup

Frontend Not Loading

# Verify build exists
ls -la /opt/checkin-app/frontend/dist/

# Check Nginx configuration for root path
grep -n "root" /etc/nginx/sites-available/checkin-app

# Clear browser cache or test with curl
curl -I https://your-domain.com/

---

Updating the Application

Update Backend

# Switch to application user
sudo su - checkin
cd /opt/checkin-app

# Pull latest changes
git pull

# Activate virtual environment
source venv/bin/activate

# Update dependencies
pip install -r backend/requirements.txt

# Run migrations if needed
# alembic upgrade head

# Exit and restart service
exit
sudo systemctl restart checkin-app

Update Frontend

sudo su - checkin
cd /opt/checkin-app/frontend

# Pull latest changes
git pull

# Install dependencies
npm install

# Build
npm run build

# Exit
exit

# No need to restart - Nginx serves static files

---

Security Recommendations

1. Firewall: Use ufw to restrict access

   sudo ufw allow 22/tcp   # SSH
   sudo ufw allow 80/tcp   # HTTP
   sudo ufw allow 443/tcp  # HTTPS
   sudo ufw enable
   

2. Regular Updates: Keep system and packages updated

   sudo apt update && sudo apt upgrade
   

3. Backup: Regular backups of database and configuration

   # Create backup script
   sudo nano /opt/checkin-app/backup.sh
   

4. Monitoring: Consider using monitoring tools like Prometheus, Grafana, or Uptime Kuma

5. Rate Limiting: Configure Nginx rate limiting for API endpoints

---

Additional Resources

• Nginx Documentation
• Systemd Documentation
• Let's Encrypt
• FastAPI Deployment

---

Support

For issues or questions, please:

• Check the logs first
• Review this guide carefully
• Open an issue on GitHub
• Contact system administrator