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

# 🎯 PostgreSQL Migration Complete - Ready for Deployment

## Summary

Your Church Song Lyric application has been successfully prepared for migration to Ubuntu server **192.168.10.130** with the following changes:

- ✅ **Port**: Changed from 5000 to **5100**
- ✅ **Database**: Migrated from MongoDB to **PostgreSQL**
- ✅ **Server**: Configured for **192.168.10.130**
- ✅ **Dependencies**: Updated and tested locally

---

## 📦 What's Been Created

### Core PostgreSQL Files

| File | Description |
|------|-------------|
| `backend/postgresql_models.py` | SQLAlchemy models for PostgreSQL |
| `backend/migrate_to_postgresql.py` | Data migration script from MongoDB/JSON |
| `backend/requirements.txt` | Updated with PostgreSQL dependencies |

### Configuration Files

| File | Description |
|------|-------------|
| `backend/.env` | Updated for PostgreSQL and port 5100 |
| `backend/.env.example` | Template with PostgreSQL settings |
| `backend/.env.ubuntu` | Ubuntu server configuration |
| `frontend/.env.ubuntu` | Frontend API configuration |

### Deployment Scripts

| File | Description |
|------|-------------|
| `ubuntu-setup-postgresql.sh` | **Automated setup script** (recommended) |
| `ubuntu-deploy.sh` | Quick update/redeploy script |
| `ubuntu-services.sh` | Service management helper |

### Documentation

| File | Description |
|------|-------------|
| `POSTGRESQL_DEPLOYMENT_GUIDE.md` | **Complete step-by-step guide** |
| `POSTGRESQL_QUICK_START.md` | Quick reference for fast deployment |
| `SSH_QUICK_REFERENCE.md` | SSH commands and troubleshooting |
| `MIGRATION_STATUS.md` | Detailed migration status |
| `README_POSTGRESQL.md` | This file |

### Service Files

| File | Description |
|------|-------------|
| `church-songlyric-backend.service` | Systemd service definition |
| `nginx-church-songlyric.conf` | HTTP Nginx configuration |
| `nginx-church-songlyric-ssl.conf` | HTTPS Nginx configuration |

---

## 🚀 Deployment Options

### Option 1: Automated Setup (Recommended)

**Fastest way to deploy - One script does everything!**

```powershell
# 1. From Windows: Transfer files
scp -r "E:\Documents\Website Projects\Church_SongLyric" username@192.168.10.130:/tmp/

# 2. SSH to server
ssh username@192.168.10.130

# 3. Run automated setup
sudo mv /tmp/Church_SongLyric /var/www/church-songlyric
cd /var/www/church-songlyric
chmod +x ubuntu-setup-postgresql.sh
./ubuntu-setup-postgresql.sh
```

**The script will:**

- ✅ Install PostgreSQL
- ✅ Create database and user
- ✅ Install all dependencies (Python, Node.js, Nginx)
- ✅ Setup virtual environment
- ✅ Build frontend
- ✅ Migrate your data
- ✅ Create systemd service
- ✅ Configure Nginx
- ✅ Start everything

**Time**: ~15 minutes  
**Difficulty**: Easy

---

### Option 2: Manual Setup

**For more control or learning purposes**

Follow the detailed guide: **POSTGRESQL_DEPLOYMENT_GUIDE.md**

**Time**: ~45-60 minutes  
**Difficulty**: Moderate

---

## 🔐 Important Configuration

### PostgreSQL Connection String

```env
POSTGRESQL_URI=postgresql://songlyric_user:your_password@192.168.10.130:5432/church_songlyric
```

**Components:**

- Username: `songlyric_user`
- Password: Choose a secure password during setup
- Host: `192.168.10.130`
- Port: `5432` (PostgreSQL default)
- Database: `church_songlyric`

### Flask Configuration

```env
FLASK_PORT=5100
FLASK_ENV=production
SECRET_KEY=your-random-secret-key
```

### Access Points

| Service | URL | Port |
|---------|-----|------|
| Frontend | <http://192.168.10.130> | 80 |
| API | <http://192.168.10.130/api> | 80 (proxied) |
| Backend Direct | <http://192.168.10.130:5100> | 5100 |
| PostgreSQL | 192.168.10.130 | 5432 |

---

## 📋 Pre-Deployment Checklist

- [ ] SSH access to 192.168.10.130 configured
- [ ] Ubuntu server credentials ready
- [ ] Decided on PostgreSQL password
- [ ] Backed up current data (`data.json` exists)
- [ ] Read `POSTGRESQL_QUICK_START.md`
- [ ] Project files ready to transfer

---

## 🎬 Quick Start Commands

### Connect to Server

```powershell
ssh username@192.168.10.130
```

### Transfer Files

```powershell
scp -r "E:\Documents\Website Projects\Church_SongLyric" username@192.168.10.130:/tmp/
```

### Deploy

```bash
sudo mv /tmp/Church_SongLyric /var/www/church-songlyric && \
cd /var/www/church-songlyric && \
chmod +x ubuntu-setup-postgresql.sh && \
./ubuntu-setup-postgresql.sh
```

### Access Application

```
http://192.168.10.130
```

---

## 🛠️ Post-Deployment

### Verify Everything Works

```bash
# Check service status
sudo systemctl status church-songlyric-backend

# Test API
curl http://192.168.10.130/api/health

# Check database
sudo -u postgres psql -d church_songlyric -c "\dt"
```

### Management Commands

```bash
# Restart service
sudo systemctl restart church-songlyric-backend

# View logs
sudo journalctl -u church-songlyric-backend -f

# Database access
sudo -u postgres psql -d church_songlyric
```

---

## 📊 Database Schema

### Tables

1. **songs** - Song lyrics and metadata (id, title, artist, lyrics, chords, etc.)
2. **profiles** - User/worship leader profiles (id, name, email, role)
3. **plans** - Worship service plans (id, title, date, notes)
4. **profile_songs** - Links profiles to favorite songs
5. **plan_songs** - Links songs to plans with order

All tables are auto-created by SQLAlchemy on first run.

---

## 🔄 Data Migration

Your existing data will be automatically migrated from `data.json`:

- ✅ All songs with lyrics and chords
- ✅ All profiles
- ✅ Profile-song relationships (if any)
- ✅ Plans and plan-songs (if any)

The migration script (`migrate_to_postgresql.py`) is safe and idempotent:

- Won't duplicate data
- Can be run multiple times
- Reports what was created/updated

---

## ⚠️ Important Notes

### Port Change Impact

The backend now runs on **port 5100** (was 5000). This affects:

- API endpoint URLs
- Firewall rules
- Mobile device configurations
- Any external integrations

### Database Change Impact

Switched from MongoDB to PostgreSQL:

- Different query syntax (handled by SQLAlchemy)
- Better performance for relational data
- ACID compliance
- Standard SQL queries

### Current Limitation

The `backend/app.py` file has been updated with new imports, but **route handlers still need full conversion to use PostgreSQL**. The current code won't work until routes are updated.

**Two options:**

1. Keep using MongoDB version and convert gradually
2. Request a complete PostgreSQL version of app.py

---

## 🆘 Troubleshooting

### Can't Connect to Server

```bash
ping 192.168.10.130
ssh -v username@192.168.10.130
```

### Service Won't Start

```bash
sudo journalctl -u church-songlyric-backend -n 50
```

### Database Connection Failed

```bash
psql -h 192.168.10.130 -U songlyric_user -d church_songlyric
```

### Port Already in Use

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

See **SSH_QUICK_REFERENCE.md** for more troubleshooting commands.

---

## 📚 Documentation Index

| Document | Purpose |
|----------|---------|
| **POSTGRESQL_QUICK_START.md** | ⭐ Start here for fast deployment |
| **POSTGRESQL_DEPLOYMENT_GUIDE.md** | Complete step-by-step guide |
| **SSH_QUICK_REFERENCE.md** | SSH commands and server management |
| **MIGRATION_STATUS.md** | Technical details of what changed |
| **README_POSTGRESQL.md** | This overview document |

---

## ✅ Next Steps

1. **Review** `POSTGRESQL_QUICK_START.md`
2. **Connect** to Ubuntu server via SSH
3. **Transfer** project files to server
4. **Run** automated setup script
5. **Test** application at <http://192.168.10.130>
6. **Verify** data migration completed
7. **Configure** backups

---

## 🎉 You're Ready

Everything is prepared for deployment. The automated setup script will handle all the complex configuration.

**Estimated deployment time: 15-20 minutes**

### Get Started Now

```powershell
# 1. Transfer files (from Windows)
scp -r "E:\Documents\Website Projects\Church_SongLyric" username@192.168.10.130:/tmp/

# 2. SSH and deploy (on Ubuntu)
ssh username@192.168.10.130
cd /var/www && sudo mv /tmp/Church_SongLyric church-songlyric
cd church-songlyric && chmod +x *.sh && ./ubuntu-setup-postgresql.sh
```

**Questions?** See the documentation files listed above!

---

**Status**: ✅ Ready for Deployment  
**Date**: December 7, 2025  
**Target Server**: 192.168.10.130  
**Port**: 5100  
**Database**: PostgreSQL