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