PTS/Church-Music
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Church-Music/legacy-site/documentation/md-files/UBUNTU_DEPLOYMENT_GUIDE.md

10 KiB
Raw Permalink Blame History

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

sudo apt update && sudo apt upgrade -y

1.2 Install Required System Packages

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

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)

# 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

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

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

3.2 Install Python Dependencies

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

3.3 Configure Environment Variables

nano .env

Add the following (replace with your actual values):

# 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

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

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:

nano src/api.js

Update the base URL:

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

4.3 Create Production Environment File

nano .env.production

Add:

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

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

Step 5: Configure Nginx

5.1 Create Nginx Configuration

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

Paste the following configuration:

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

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

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

Paste:

[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

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
  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)

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

sudo apt install certbot python3-certbot-nginx -y

8.2 Obtain SSL Certificate

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

sudo systemctl status certbot.timer
# Should show active

Step 9: Verify Deployment

9.1 Check Services

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

9.2 Test API

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

# 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

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

10.3 Update Application

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

# 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

# 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

# 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

# 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

# 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! 🎉

Reference in New Issue View Git Blame Copy Permalink