Add VPS deployment artifacts and documentation

Include systemd service file, Apache reverse proxy config,
and comprehensive deployment guide for Linux VPS setup.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

1 files changed, 177 insertions, 0 deletions

diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..89d2bc6
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,177 @@
+# Deployment Guide
+
+Deploy Task Dashboard to a VPS using Apache2 as reverse proxy and Systemd for process management.
+
+## Prerequisites
+
+- Linux VPS (Ubuntu/Debian recommended)
+- Apache2 with `mod_proxy`, `mod_proxy_http`, `mod_ssl`, `mod_headers`, `mod_rewrite`
+- Go 1.21+ (for building)
+- SSL certificate (Let's Encrypt recommended)
+
+## Directory Structure
+
+```
+/site/{fqdn}/
+├── app                 # Compiled binary
+├── data/
+│   └── dashboard.db    # SQLite database
+├── public/             # Static assets (served by Apache)
+│   ├── css/
+│   └── js/
+├── templates/          # HTML templates
+└── .env                # Environment configuration
+```
+
+## Build
+
+On your development machine or CI:
+
+```bash
+# Build for Linux
+GOOS=linux GOARCH=amd64 go build -o app cmd/dashboard/main.go
+```
+
+## Setup
+
+### 1. Create Directory Structure
+
+```bash
+export FQDN="your-domain.com"
+sudo mkdir -p /site/${FQDN}/{data,public,templates}
+sudo chown -R www-data:www-data /site/${FQDN}
+```
+
+### 2. Deploy Files
+
+```bash
+# Copy binary
+sudo cp app /site/${FQDN}/
+
+# Copy static assets
+sudo cp -r web/static/* /site/${FQDN}/public/
+
+# Copy templates
+sudo cp -r web/templates/* /site/${FQDN}/templates/
+
+# Set permissions
+sudo chmod +x /site/${FQDN}/app
+```
+
+### 3. Configure Environment
+
+Create `/site/${FQDN}/.env`:
+
+```bash
+# Required API Keys
+TODOIST_API_KEY=your_todoist_api_key
+TRELLO_API_KEY=your_trello_api_key
+TRELLO_TOKEN=your_trello_token
+
+# Optional
+PLANTOEAT_API_KEY=your_plantoeat_api_key
+
+# Paths (adjust for deployment structure)
+DATABASE_PATH=/site/${FQDN}/data/dashboard.db
+TEMPLATE_DIR=/site/${FQDN}/templates
+STATIC_DIR=/site/${FQDN}/public
+
+# Server
+PORT=8080
+DEBUG=false
+CACHE_TTL_MINUTES=5
+
+# Default user credentials (change after first login!)
+DEFAULT_USER=admin
+DEFAULT_PASS=your_secure_password
+```
+
+Secure the file:
+
+```bash
+sudo chmod 600 /site/${FQDN}/.env
+sudo chown www-data:www-data /site/${FQDN}/.env
+```
+
+### 4. Install Systemd Service
+
+```bash
+# Copy and customize service file
+sudo cp deployment/task-dashboard.service /etc/systemd/system/task-dashboard@.service
+
+# Enable and start service
+sudo systemctl daemon-reload
+sudo systemctl enable task-dashboard@${FQDN}
+sudo systemctl start task-dashboard@${FQDN}
+
+# Check status
+sudo systemctl status task-dashboard@${FQDN}
+```
+
+### 5. Configure Apache
+
+```bash
+# Enable required modules
+sudo a2enmod proxy proxy_http ssl headers rewrite
+
+# Copy and customize Apache config
+# Replace ${FQDN} with your actual domain in the config file
+sudo cp deployment/apache.conf /etc/apache2/sites-available/${FQDN}.conf
+
+# Edit the file to replace ${FQDN} placeholders
+sudo sed -i "s/\${FQDN}/${FQDN}/g" /etc/apache2/sites-available/${FQDN}.conf
+
+# Enable site
+sudo a2ensite ${FQDN}
+
+# Test and reload
+sudo apache2ctl configtest
+sudo systemctl reload apache2
+```
+
+### 6. SSL Certificate (Let's Encrypt)
+
+```bash
+sudo apt install certbot python3-certbot-apache
+sudo certbot --apache -d ${FQDN}
+```
+
+## Verification
+
+1. Check service is running: `sudo systemctl status task-dashboard@${FQDN}`
+2. Check logs: `sudo journalctl -u task-dashboard@${FQDN} -f`
+3. Visit `https://${FQDN}` and login with configured credentials
+
+## Updating
+
+```bash
+# Stop service
+sudo systemctl stop task-dashboard@${FQDN}
+
+# Deploy new binary
+sudo cp app /site/${FQDN}/
+
+# Update static assets if changed
+sudo cp -r web/static/* /site/${FQDN}/public/
+
+# Update templates if changed
+sudo cp -r web/templates/* /site/${FQDN}/templates/
+
+# Start service
+sudo systemctl start task-dashboard@${FQDN}
+```
+
+## Troubleshooting
+
+### Service won't start
+- Check logs: `sudo journalctl -u task-dashboard@${FQDN} -e`
+- Verify .env file exists and has correct permissions
+- Ensure database directory is writable
+
+### 502 Bad Gateway
+- Check if Go app is running: `sudo systemctl status task-dashboard@${FQDN}`
+- Verify PORT in .env matches Apache ProxyPass
+
+### Static files not loading
+- Ensure `/site/${FQDN}/public/` contains CSS/JS files
+- Check Apache logs: `sudo tail -f /var/log/apache2/${FQDN}-error.log`