Add local development environment support and automated deployment

[josephradford]

Summary

Adds comprehensive local development support for testing the home-server-stack on macOS/Docker Desktop before deploying to production servers, plus automated deployment tooling.

Key Features

🖥️ Local Development Environment

• docker-compose.local.yml - Override file that simplifies services for Mac:

  • Exposes all services on localhost ports
  • Disables AdGuard Home, WireGuard, and Fail2ban (macOS incompatible)
  • Removes SSL/TLS complexity (uses HTTP)
  • Removes security middlewares for easy local testing

• New Makefile targets:

  • make local-setup - One-command setup (creates .env.local, validates, starts services)
  • make local-start - Start services
  • make local-stop - Stop services
  • make local-restart - Restart services
  • make local-logs - View logs
  • make local-status - Check status
  • make local-clean - Remove containers

• Services accessible locally via direct ports:

  • Homepage Dashboard: http://localhost:3000
  • Traefik Dashboard: http://localhost:8080
  • n8n: http://localhost:5678
  • Home Assistant: http://localhost:8123
  • Actual Budget: http://localhost:5006
  • Grafana: http://localhost:3001
  • Prometheus: http://localhost:9090
  • Alertmanager: http://localhost:9093

🚀 Automated Deployment

• scripts/deploy-to-server.sh - One-command deployment to production:

  1. Checks local git status
  2. Pushes changes to repository
  3. SSHs to server and pulls changes
  4. Validates configuration
  5. Pulls updated Docker images
  6. Restarts services
  7. Shows service status

• Makefile deploy target:

  make deploy [email protected]
  make deploy [email protected] BRANCH=feature/new-service

📁 Environment File Management

• .env.local (for Mac development) - now separate from .env (production)
• .env.local.example - Template with safe defaults for local testing
• ENV_FILE variable support - Scripts now accept ENV_FILE parameter:
  • configure-homepage.sh - Updated to support both environments
  • setup-homeassistant.sh - Updated to support both environments
  • setup-traefik-password.sh - Updated to support both environments
• Added .env.local to .gitignore

📚 Documentation

• QUICKSTART_LOCAL.md - Quick start guide for local development
• docs/LOCAL_DEVELOPMENT.md - Comprehensive guide covering:
  • Local vs production differences
  • Development workflow
  • Testing checklist
  • Deployment options
  • Troubleshooting
• .env-files-reference.md - Complete reference for environment file usage

Development Workflow

# 1. Test locally
make local-setup

# 2. Make changes, test locally
make local-restart && make local-logs

# 3. Commit and push
git add .
git commit -m "Description"
git push

# 4. Deploy to server
make deploy [email protected]

Files Changed

New Files:

• docker-compose.local.yml - Local development overrides
• .env.local.example - Local environment template
• scripts/deploy-to-server.sh - Automated deployment script
• QUICKSTART_LOCAL.md - Quick start guide
• docs/LOCAL_DEVELOPMENT.md - Comprehensive local dev guide
• .env-files-reference.md - Environment file reference

Modified Files:

• .gitignore - Added .env.local
• Makefile - Added local-* and deploy targets
• scripts/configure-homepage.sh - Support ENV_FILE variable
• scripts/setup-homeassistant.sh - Support ENV_FILE variable
• scripts/setup-traefik-password.sh - Support ENV_FILE variable

Testing

• Local setup works: make local-setup
• All services start locally
• Environment variable separation works
• Scripts support both .env and .env.local
• Deploy script tested on actual server (requires server access)

Benefits

1. Faster Development - Test changes locally before deploying
2. Safer Deployments - Validate changes work before touching production
3. Better Documentation - Clear separation between local and production
4. Easier Onboarding - New contributors can run stack locally in 3 commands
5. One-Command Deploy - No more manual SSH and git pull steps

🤖 Generated with Claude Code