balanceboard/DEPLOYMENT.md

Deployment and Issue Management Instructions

Making Changes and Committing

1. Make Code Changes

Edit the necessary files to implement your feature or fix.

2. Commit Your Changes

Always use descriptive commit messages with the Claude Code format:

git add <files>
git commit -m "$(cat <<'EOF'
Brief title of the change

Detailed description of what was changed and why.
- Bullet points for key features
- More details as needed
- Reference issue numbers (e.g., Issue #1)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

3. Push to Remote

git push origin main

Commenting on Issues

After implementing a fix or feature that addresses a GitHub/Gitea issue, comment on the issue to document the work:

Comment on Issue #1 Example

curl -X POST -u "the_bot:4152aOP!" \
  -H "Content-Type: application/json" \
  -d "{\"body\":\"Implemented [feature description] in commit [commit-hash].\\n\\nFeatures include:\\n- Feature 1\\n- Feature 2\\n- Feature 3\"}" \
  https://git.scorpi.us/api/v1/repos/chelsea/balanceboard/issues/1/comments

General Template

curl -X POST -u "the_bot:4152aOP!" \
  -H "Content-Type: application/json" \
  -d "{\"body\":\"Your comment here with \\n for newlines\"}" \
  https://git.scorpi.us/api/v1/repos/chelsea/balanceboard/issues/ISSUE_NUMBER/comments

Important Notes:

• Use the_bot as the username with password 4152aOP!
• Escape quotes in JSON with \"
• Use \\n for newlines in the body
• Remove apostrophes or escape them carefully to avoid shell parsing issues
• Replace ISSUE_NUMBER with the actual issue number

Database Migrations

When you add new database fields:

1. Update the Model (in models.py)
2. Create a Migration Script (e.g., migrate_password_reset.py)
3. Run the Migration before deploying:

   python3 migrate_password_reset.py
   

4. Test Locally to ensure the migration works
5. Deploy to production and run the migration there too

Docker Deployment

Build and Push

# Build the image
docker build -t git.scorpi.us/chelsea/balanceboard:latest .

# Push to registry
docker push git.scorpi.us/chelsea/balanceboard:latest

Deploy on Server

# SSH to server
ssh user@reddit.scorpi.us

# Pull latest image
cd /path/to/balanceboard
docker-compose pull

# Restart services
docker-compose down
docker-compose up -d

# Check logs
docker-compose logs -f balanceboard

Common Issues

Container Won't Start

• Check logs: docker-compose logs balanceboard
• Verify file permissions in data/ directory
• Ensure all required files are in git (filtersets.json, themes/, static/, etc.)

Database Migration Errors

• Back up database first
• Run migration manually: python3 migrate_*.py
• Check if columns already exist before re-running

404 Errors for Static Files

• Ensure files are committed to git
• Rebuild Docker image after adding files
• Check volume mounts in docker-compose.yml

Checklist for Each Commit

• Make code changes
• Test locally
• Run database migrations if needed
• Commit with descriptive message
• Push to git remote
• Comment on related issues
• Build and push Docker image (if needed)
• Deploy to server (if needed)
• Verify deployment works
• Update this README if process changes