Church-Music/legacy-site/documentation/md-files/UBUNTU_DEPLOYMENT_GUIDE.md

# Ubuntu Server Deployment Guide

## Overview

This guide walks you through deploying the House of Prayer Song Lyrics System on an Ubuntu server (20.04/22.04/24.04).

## Prerequisites

- Ubuntu Server 20.04+ with sudo access
- Domain name (optional, but recommended for HTTPS)
- MongoDB Atlas account (or local MongoDB installation)
- Minimum 2GB RAM, 2 CPU cores, 20GB disk space

## Architecture

- **Backend**: Flask (Python) API on port 5000
- **Frontend**: React app served via Nginx on port 80/443
- **Database**: MongoDB Atlas (cloud) or local MongoDB
- **Reverse Proxy**: Nginx for SSL/TLS and routing
- **Process Manager**: systemd services for automatic startup

---

## Step 1: Initial Server Setup

### 1.1 Update System

```bash
sudo apt update && sudo apt upgrade -y
```

### 1.2 Install Required System Packages

```bash
sudo apt install -y \
    python3 python3-pip python3-venv \
    nodejs npm \
    nginx \
    git \
    curl \
    ufw \
    tesseract-ocr \
    poppler-utils \
    libtesseract-dev \
    libleptonica-dev
```

### 1.3 Configure Firewall

```bash
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
```

---

## Step 2: Transfer Project Files

### 2.1 Copy Project to Server

From your Windows machine, use one of these methods:

**Option A: Using Git (Recommended)**

```bash
# On Ubuntu server
cd /var/www
sudo mkdir -p church-songlyric
sudo chown $USER:$USER church-songlyric
cd church-songlyric

# Clone your repository (if you have one)
git clone <your-repo-url> .

# OR upload via SCP from Windows PowerShell:
# scp -r "E:\Documents\Website Projects\Church_SongLyric\*" username@your-server-ip:/var/www/church-songlyric/
```

**Option B: Using SFTP/WinSCP**

1. Use WinSCP or FileZilla to transfer the entire project folder
2. Place it in `/var/www/church-songlyric/`

### 2.2 Set Proper Permissions

```bash
cd /var/www/church-songlyric
sudo chown -R $USER:www-data .
sudo chmod -R 755 .
```

---

## Step 3: Backend Setup

### 3.1 Create Python Virtual Environment

```bash
cd /var/www/church-songlyric/backend
python3 -m venv venv
source venv/bin/activate
```

### 3.2 Install Python Dependencies

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

### 3.3 Configure Environment Variables

```bash
nano .env
```

Add the following (replace with your actual values):

```env
# MongoDB Connection (use your Atlas connection string)
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/songlyric?retryWrites=true&w=majority

# Flask Configuration
FLASK_PORT=5000
FLASK_ENV=production
SECRET_KEY=your-super-secret-key-here-change-this

# API Tokens (optional)
GENIUS_TOKEN=your_genius_token_if_needed

# Server Configuration
ALLOWED_ORIGINS=http://your-domain.com,https://your-domain.com,http://your-server-ip
```

### 3.4 Test Backend

```bash
source venv/bin/activate
python app.py
# Should start on port 5000
# Press Ctrl+C to stop
```

---

## Step 4: Frontend Setup

### 4.1 Install Node Dependencies

```bash
cd /var/www/church-songlyric/frontend
npm install
```

### 4.2 Update API Configuration

Edit `src/api.js` to use your server's domain or IP:

```bash
nano src/api.js
```

Update the base URL:

```javascript
const API_BASE_URL = process.env.REACT_APP_API_URL || 'http://your-domain.com/api';
```

### 4.3 Create Production Environment File

```bash
nano .env.production
```

Add:

```env
REACT_APP_API_URL=http://your-domain.com/api
# Or for HTTPS:
# REACT_APP_API_URL=https://your-domain.com/api
```

### 4.4 Build Frontend

```bash
npm run build
# Creates optimized production build in ./build/
```

---

## Step 5: Configure Nginx

### 5.1 Create Nginx Configuration

```bash
sudo nano /etc/nginx/sites-available/church-songlyric
```

Paste the following configuration:

```nginx
server {
    listen 80;
    server_name your-domain.com www.your-domain.com;  # Replace with your domain or server IP

    # Serve React frontend
    root /var/www/church-songlyric/frontend/build;
    index index.html;

    # Frontend routing - serve index.html for all routes
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Proxy API requests to Flask backend
    location /api {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Static file caching
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

### 5.2 Enable Site and Test Configuration

```bash
sudo ln -s /etc/nginx/sites-available/church-songlyric /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

---

## Step 6: Create Systemd Services

### 6.1 Backend Service

```bash
sudo nano /etc/systemd/system/church-songlyric-backend.service
```

Paste:

```ini
[Unit]
Description=Church Song Lyric Backend (Flask)
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/church-songlyric/backend
Environment="PATH=/var/www/church-songlyric/backend/venv/bin"
ExecStart=/var/www/church-songlyric/backend/venv/bin/python app.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### 6.2 Enable and Start Services

```bash
sudo systemctl daemon-reload
sudo systemctl enable church-songlyric-backend
sudo systemctl start church-songlyric-backend
sudo systemctl status church-songlyric-backend
```

---

## Step 7: MongoDB Setup

### 7.1 MongoDB Atlas (Recommended)

1. Sign up at [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register)
2. Create a free M0 cluster
3. Add your server's IP address to the IP whitelist (or use 0.0.0.0/0 for all IPs)
4. Create a database user with read/write permissions
5. Get your connection string and add it to `/var/www/church-songlyric/backend/.env`

### 7.2 Migrate Data (if you have existing SQLite data)

```bash
cd /var/www/church-songlyric/backend
source venv/bin/activate

# Copy your app.db to the backend folder, then:
python migrate_to_mongodb.py
```

---

## Step 8: SSL/TLS Setup (Optional but Recommended)

### 8.1 Install Certbot

```bash
sudo apt install certbot python3-certbot-nginx -y
```

### 8.2 Obtain SSL Certificate

```bash
sudo certbot --nginx -d your-domain.com -d www.your-domain.com
```

Follow the prompts. Certbot will automatically update your Nginx configuration.

### 8.3 Auto-Renewal

```bash
sudo systemctl status certbot.timer
# Should show active
```

---

## Step 9: Verify Deployment

### 9.1 Check Services

```bash
sudo systemctl status church-songlyric-backend
sudo systemctl status nginx
```

### 9.2 Test API

```bash
curl http://localhost:5000/api/health
# Should return: {"status":"healthy"}
```

### 9.3 Test Frontend

Open browser to: `http://your-domain.com` or `http://your-server-ip`

---

## Step 10: Monitoring and Maintenance

### 10.1 View Logs

```bash
# Backend logs
sudo journalctl -u church-songlyric-backend -f

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

### 10.2 Restart Services

```bash
sudo systemctl restart church-songlyric-backend
sudo systemctl restart nginx
```

### 10.3 Update Application

```bash
cd /var/www/church-songlyric

# Pull latest changes (if using git)
git pull

# Update backend
cd backend
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart church-songlyric-backend

# Update frontend
cd ../frontend
npm install
npm run build
sudo systemctl reload nginx
```

---

## Troubleshooting

### Backend Won't Start

```bash
# Check logs
sudo journalctl -u church-songlyric-backend -n 50

# Check if port 5000 is in use
sudo netstat -tulpn | grep 5000

# Test manually
cd /var/www/church-songlyric/backend
source venv/bin/activate
python app.py
```

### Frontend Shows Blank Page

```bash
# Check Nginx configuration
sudo nginx -t

# Verify build files exist
ls -la /var/www/church-songlyric/frontend/build/

# Check browser console for errors
```

### MongoDB Connection Issues

```bash
# Test connection from server
cd /var/www/church-songlyric/backend
source venv/bin/activate
python -c "from mongodb_models import get_db; db = get_db(); print('Connected:', db.name)"
```

### Permission Issues

```bash
# Fix ownership
sudo chown -R www-data:www-data /var/www/church-songlyric

# Fix permissions
sudo chmod -R 755 /var/www/church-songlyric
```

---

## Quick Reference Commands

```bash
# Start services
sudo systemctl start church-songlyric-backend
sudo systemctl start nginx

# Stop services
sudo systemctl stop church-songlyric-backend
sudo systemctl stop nginx

# Restart services
sudo systemctl restart church-songlyric-backend
sudo systemctl restart nginx

# View status
sudo systemctl status church-songlyric-backend
sudo systemctl status nginx

# View logs
sudo journalctl -u church-songlyric-backend -f
sudo tail -f /var/log/nginx/error.log

# Test configurations
sudo nginx -t
python -c "from mongodb_models import get_db; print('DB OK')"
```

---

## Security Best Practices

1. **Keep system updated**: `sudo apt update && sudo apt upgrade -y`
2. **Use strong passwords** for MongoDB and SSH
3. **Enable firewall**: Only allow necessary ports (22, 80, 443)
4. **Use SSH keys** instead of passwords
5. **Regular backups** of MongoDB data
6. **Monitor logs** for suspicious activity
7. **Keep dependencies updated**: `pip list --outdated`, `npm outdated`

---

## Support

- Check logs first: `sudo journalctl -u church-songlyric-backend -f`
- Verify MongoDB connection in `.env` file
- Ensure firewall allows traffic on ports 80/443
- Test API directly: `curl http://localhost:5000/api/health`

---

**Congratulations!** Your Church Song Lyric System is now running on Ubuntu Server! 🎉