Initial commit - Church Music Database
This commit is contained in:
501
legacy-site/documentation/md-files/UBUNTU_DEPLOYMENT_GUIDE.md
Normal file
501
legacy-site/documentation/md-files/UBUNTU_DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,501 @@
|
||||
# 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! 🎉
|
||||
Reference in New Issue
Block a user