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

MongoDB Atlas Setup Guide

Quick Setup (5 minutes)

1. Create Free MongoDB Atlas Account

1. Go to: https://www.mongodb.com/cloud/atlas/register
2. Sign up with email or Google account
3. Choose FREE M0 cluster (512MB storage, perfect for this app)

2. Create Database Cluster

1. After login, click "Build a Database"
2. Choose M0 FREE tier
3. Select AWS provider and closest region (e.g., US East)
4. Click "Create Cluster" (takes 1-3 minutes)

3. Configure Database Access

1. Click "Database Access" in left sidebar
2. Click "Add New Database User"
   • Username: church_admin (or your choice)
   • Password: Click "Autogenerate Secure Password" and COPY IT
   • Database User Privileges: Atlas admin
3. Click "Add User"

4. Configure Network Access

1. Click "Network Access" in left sidebar
2. Click "Add IP Address"
3. Click "Allow Access from Anywhere" (0.0.0.0/0)
   • This allows your PC, mobile, and tablet to connect
4. Click "Confirm"

5. Get Connection String

1. Click "Database" in left sidebar

2. Click "Connect" button on your cluster

3. Choose "Connect your application"

4. Copy the connection string (looks like):

   mongodb+srv://church_admin:<password>@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
   

5. Replace <password> with the password you copied in step 3

6. Update Backend Configuration

Edit backend/.env file:

MONGODB_URI=mongodb+srv://church_admin:YOUR_PASSWORD_HERE@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
MONGODB_DATABASE=church_songlyric

7. Run Migration

cd backend
.\venv\Scripts\python.exe migrate_to_mongodb.py

Verify Setup

After migration, you can view your data:

1. Go to MongoDB Atlas dashboard
2. Click "Browse Collections"
3. You should see:
   • songs collection (39 documents)
   • profiles collection (5 documents)
   • profile_songs collection (5 documents)

Connection Benefits

✅ Cross-Device Access: PC, mobile, tablet all connect to same cloud database ✅ Always Online: No need to keep PC running ✅ Automatic Backups: Atlas handles backups ✅ Free Forever: M0 tier is permanently free (512MB) ✅ Secure: Encrypted connections, user authentication

Troubleshooting

Connection timeout?

• Check Network Access allows 0.0.0.0/0
• Verify connection string has correct password
• Check internet connection

Authentication failed?

• Double-check password (no < > brackets)
• Verify username matches database user

Need help?

• MongoDB Atlas docs: https://docs.atlas.mongodb.com/
• Contact support through Atlas dashboard