setup features

2026-01-29 00:24:10 -05:00
parent 787c97a52f
commit 4a6e2c307c
34 changed files with 2891 additions and 71 deletions
--- a/SETUP_CHECKLIST.md
+++ b/SETUP_CHECKLIST.md
@@ -0,0 +1,132 @@
+# Setup Checklist
+
+## Before You Start
+
+- [ ] Docker and Docker Compose installed
+- [ ] TMDB API key obtained (see [TMDB_SETUP.md](TMDB_SETUP.md))
+- [ ] Git/Gitea repository initialized
+
+## Local Development Setup
+
+1. **Configure Environment:**
+   ```bash
+   cp backend/.env.example backend/.env
+   ```
+   
+2. **Edit `backend/.env`:**
+   - [ ] Set `TMDB_API_KEY` to your actual TMDB API key
+   - [ ] Change `JWT_SECRET` if desired (optional for dev)
+   - [ ] Verify database settings match docker-compose.yml
+
+3. **Start Services:**
+   ```bash
+   docker compose up --build
+   ```
+
+4. **Verify:**
+   - [ ] App accessible at http://localhost:4000
+   - [ ] Can register a new account
+   - [ ] Can search for shows/movies
+   - [ ] Database initialized successfully (check logs)
+
+## Production Deployment
+
+1. **Prepare Environment Variables:**
+   
+   Create a production `.env` file with:
+   ```bash
+   PORT=80
+   JWT_SECRET=<strong-random-secret>
+   DB_HOST=db
+   DB_USER=root
+   DB_PASSWORD=<strong-database-password>
+   DB_NAME=whats_the_point
+   TMDB_API_KEY=<your-tmdb-key>
+   ```
+
+2. **Base64 encode your `.env` for Gitea:**
+   ```bash
+   # On Linux/Mac:
+   cat .env | base64 -w 0
+   
+   # On Windows PowerShell:
+   [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((Get-Content .env -Raw)))
+   ```
+
+3. **Configure Gitea Secrets:**
+   - [ ] `PROD_ENV` - Base64 encoded environment file
+   - [ ] `PORTAINER_TOKEN` - Your Portainer API token
+
+4. **Update `prod-compose.yml`:**
+   - [ ] Verify volume paths match your system
+   - [ ] Update image registry URL if needed
+   - [ ] Verify port mappings
+
+5. **Verify Gitea Workflow:**
+   - [ ] Check `.gitea/workflows/rebuild-prod.yaml`
+   - [ ] Update `IMAGE_TAG` with your registry URL
+   - [ ] Update `ENDPOINT_NAME` to match your Portainer endpoint
+   - [ ] Update `STACK_NAME` if desired
+
+6. **Deploy:**
+   - [ ] Push to main branch
+   - [ ] Monitor Gitea Actions
+   - [ ] Check Portainer for successful deployment
+   - [ ] Verify app is accessible on production domain/IP
+
+## Post-Deployment
+
+- [ ] Test registration and login
+- [ ] Create a test challenge
+- [ ] Invite a friend (test email/username search)
+- [ ] Make and validate predictions
+- [ ] Check leaderboards
+- [ ] Test on mobile devices
+
+## Troubleshooting
+
+### Database Connection Issues
+- Check if database container is running: `docker ps`
+- Check database logs: `docker logs <db-container-name>`
+- Verify DB credentials in environment variables
+
+### TMDB API Not Working
+- Verify API key is correct in `.env`
+- Check TMDB API status: https://www.themoviedb.org/
+- Review backend logs for API errors
+
+### Frontend Not Loading
+- Check if backend is serving static files
+- Verify frontend built successfully (check Docker logs)
+- Clear browser cache
+
+### Docker Build Failures
+- Ensure all dependencies are in package.json files
+- Check Dockerfile syntax
+- Verify node_modules are not in build context (.dockerignore)
+
+## Maintenance
+
+### Database Backups
+```bash
+# Backup
+docker exec <db-container> mysqldump -u root -p<password> whats_the_point > backup.sql
+
+# Restore
+docker exec -i <db-container> mysql -u root -p<password> whats_the_point < backup.sql
+```
+
+### Viewing Logs
+```bash
+# Docker Compose (dev)
+docker compose logs -f web
+docker compose logs -f db
+
+# Production (Portainer)
+# Use Portainer UI to view logs
+```
+
+### Updating
+1. Pull latest changes from repository
+2. Push to main branch (triggers Gitea workflow)
+3. Workflow automatically rebuilds and redeploys