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

```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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](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

```bash
# 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`):

```bash
# 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

```bash
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

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

### MongoDB connection issues

```bash
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

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

### Permission errors

```bash
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**