whats-the-point/SETUP_CHECKLIST.md

Setup Checklist

Before You Start

• Docker and Docker Compose installed
• TMDB API key obtained (see TMDB_SETUP.md)
• Git/Gitea repository initialized

Local Development Setup

1. Configure Environment:

   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:

   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:

   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:

   # 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

# 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

# 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