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

Quick Migration to Ubuntu Server

Summary

Your Church Song Lyric application is now ready to migrate to Ubuntu server. All necessary files have been created.

What's Been Created

📄 Documentation

• UBUNTU_DEPLOYMENT_GUIDE.md - Complete step-by-step deployment guide

🔧 Scripts

• ubuntu-setup.sh - Automated installation script (run first)
• ubuntu-deploy.sh - Quick deployment script (for updates)
• ubuntu-services.sh - Service management script

⚙️ Configuration Files

• church-songlyric-backend.service - Systemd service for backend
• nginx-church-songlyric.conf - Nginx HTTP configuration
• nginx-church-songlyric-ssl.conf - Nginx HTTPS configuration
• backend/.env.ubuntu - Backend environment template
• frontend/.env.ubuntu - Frontend environment template

---

Quick Start (3 Steps)

1️⃣ Transfer Files to Ubuntu Server

From your Windows machine (PowerShell):

# Replace with your server details
scp -r "E:\Documents\Website Projects\Church_SongLyric" username@your-server-ip:/tmp/

Or use WinSCP/FileZilla to transfer the entire folder.

2️⃣ Run Setup Script on Ubuntu

SSH into your Ubuntu server, then:

# Move files to installation directory
sudo mv /tmp/Church_SongLyric /var/www/church-songlyric
cd /var/www/church-songlyric

# Make scripts executable
chmod +x ubuntu-setup.sh ubuntu-deploy.sh ubuntu-services.sh

# Run the setup script
./ubuntu-setup.sh

The script will:

• Install all dependencies (Python, Node.js, Nginx, etc.)
• Create virtual environment
• Build the frontend
• Configure Nginx
• Create systemd services
• Set up firewall

3️⃣ Configure and Start

# Copy and edit environment file
cd /var/www/church-songlyric/backend
cp .env.ubuntu .env
nano .env
# Add your MongoDB URI and other settings

# Start services
sudo systemctl daemon-reload
sudo systemctl enable church-songlyric-backend
sudo systemctl start church-songlyric-backend
sudo systemctl restart nginx

# Check status
./ubuntu-services.sh status

---

Access Your Application

• HTTP: http://your-server-ip or http://your-domain.com
• HTTPS (after SSL setup): https://your-domain.com

---

Optional: Enable HTTPS

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

# Get SSL certificate (replace with your domain)
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# Auto-renewal is configured automatically

---

Useful Commands

# Service management
./ubuntu-services.sh start    # Start all services
./ubuntu-services.sh stop     # Stop all services
./ubuntu-services.sh restart  # Restart all services
./ubuntu-services.sh status   # Check status
./ubuntu-services.sh logs     # View live logs

# Manual service commands
sudo systemctl status church-songlyric-backend
sudo systemctl restart church-songlyric-backend
sudo systemctl restart nginx

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

# Update application
cd /var/www/church-songlyric
git pull  # if using git
./ubuntu-deploy.sh

---

MongoDB Setup

You need MongoDB for the application to work. Two options:

Option A: MongoDB Atlas (Recommended)

1. Sign up at https://www.mongodb.com/cloud/atlas/register
2. Create a FREE M0 cluster
3. Add your server's IP to IP whitelist (or 0.0.0.0/0 for all IPs)
4. Create a database user
5. Get connection string and add to /var/www/church-songlyric/backend/.env

Example:

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/songlyric?retryWrites=true&w=majority

Option B: Local MongoDB

# Install MongoDB on Ubuntu
sudo apt install mongodb -y
sudo systemctl start mongodb
sudo systemctl enable mongodb

# Use local connection string
MONGODB_URI=mongodb://localhost:27017/songlyric

---

Migrate Existing Data

If you have an existing SQLite database (app.db):

# Copy app.db to server backend folder
cd /var/www/church-songlyric/backend
source venv/bin/activate
python migrate_to_mongodb.py

---

Troubleshooting

Backend won't start

sudo journalctl -u church-songlyric-backend -n 50
cd /var/www/church-songlyric/backend
source venv/bin/activate
python app.py  # Test manually

Nginx errors

sudo nginx -t  # Test configuration
sudo tail -f /var/log/nginx/error.log

MongoDB connection issues

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

Port already in use

sudo netstat -tulpn | grep 5000
sudo lsof -i :5000

Permission errors

sudo chown -R www-data:www-data /var/www/church-songlyric
sudo chmod -R 755 /var/www/church-songlyric

---

Security Checklist

• Change default passwords in .env
• Set strong SECRET_KEY in .env
• Configure firewall (only ports 22, 80, 443)
• Enable HTTPS with Let's Encrypt
• Restrict MongoDB IP whitelist
• Use SSH keys instead of passwords
• Keep system updated: sudo apt update && sudo apt upgrade -y
• Set up automatic backups for MongoDB

---

Support Files Location

All configuration files are in your project root:

• /var/www/church-songlyric/UBUNTU_DEPLOYMENT_GUIDE.md - Full guide
• /var/www/church-songlyric/ubuntu-setup.sh - Setup script
• /var/www/church-songlyric/ubuntu-services.sh - Service manager

---

Next Steps After Deployment

1. ✅ Test the application thoroughly
2. ✅ Set up HTTPS with Certbot
3. ✅ Configure automatic backups
4. ✅ Set up monitoring (optional)
5. ✅ Document your server credentials securely

---

You're all set! Your Church Song Lyric system is ready for Ubuntu deployment. 🎉

For detailed instructions, see UBUNTU_DEPLOYMENT_GUIDE.md