wip

2026-01-13 02:42:03 +01:00
parent 19081ec682
commit e46b104127
21 changed files with 1622 additions and 2 deletions
--- a/ENV_SETUP.md
+++ b/ENV_SETUP.md
@@ -0,0 +1,210 @@
+# Environment Setup Guide
+
+This guide explains how to configure environment variables for your Hetzner deployment.
+
+## Quick Start
+
+1. **Copy the example file:**
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Edit the .env file:**
+   ```bash
+   nano .env
+   ```
+
+3. **Fill in your values** (see below)
+
+## Required Variables
+
+### `DOMAIN`
+Your website domain name.
+```
+DOMAIN=mintel.me
+```
+
+### `ADMIN_EMAIL`
+Email for SSL certificate notifications.
+```
+ADMIN_EMAIL=admin@mintel.me
+```
+
+## Optional Variables
+
+### `REDIS_URL`
+Connection string for Redis cache.
+- **Default**: `redis://redis:6379`
+- **Format**: `redis://host:port`
+- **Example**: `redis://redis:6379`
+
+### `PLAUSIBLE_DOMAIN`
+Domain for Plausible analytics tracking.
+- **Default**: Same as `DOMAIN`
+- **Example**: `mintel.me`
+
+### `PLAUSIBLE_SCRIPT_URL`
+URL to your Plausible analytics script.
+- **Default**: `https://plausible.yourdomain.com/js/script.js`
+- **Example**: `https://analytics.mintel.me/js/script.js`
+
+## Woodpecker CI/CD Variables
+
+These are only needed if using Woodpecker for automated deployment:
+
+### `DEPLOY_HOST`
+Hetzner server IP address or hostname.
+```
+DEPLOY_HOST=123.45.67.89
+```
+
+### `DEPLOY_USER`
+User for SSH access (usually root).
+```
+DEPLOY_USER=root
+```
+
+### `SSH_PRIVATE_KEY`
+Private key for SSH authentication.
+```
+SSH_PRIVATE_KEY=-----BEGIN OPENSSH PRIVATE KEY-----
+...
+-----END OPENSSH PRIVATE KEY-----
+```
+
+**Generate SSH key if needed:**
+```bash
+ssh-keygen -t ed25519 -C "woodpecker@mintel.me"
+ssh-copy-id root@YOUR_HETZNER_IP
+```
+
+### `SLACK_WEBHOOK` (Optional)
+Slack webhook for deployment notifications.
+```
+SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
+```
+
+## Usage Examples
+
+### Local Development
+```bash
+# Create .env file
+cp .env.example .env
+
+# Edit with your values
+nano .env
+
+# Start services
+docker-compose up
+```
+
+### Production Deployment
+```bash
+# On Hetzner server
+cd /opt/mintel
+
+# Create .env file
+cat > .env << EOF
+DOMAIN=mintel.me
+ADMIN_EMAIL=admin@mintel.me
+REDIS_URL=redis://redis:6379
+PLAUSIBLE_DOMAIN=mintel.me
+PLAUSIBLE_SCRIPT_URL=https://analytics.mintel.me/js/script.js
+EOF
+
+# Deploy
+./deploy.sh
+```
+
+### Woodpecker CI/CD
+1. Go to your Gitea repository
+2. Navigate to Settings → Secrets
+3. Add these secrets:
+   - `DEPLOY_HOST` - Your Hetzner IP
+   - `DEPLOY_USER` - Usually `root`
+   - `SSH_PRIVATE_KEY` - Private key content
+   - `DOMAIN` - Your domain
+   - `ADMIN_EMAIL` - Your email
+   - (Optional) `SLACK_WEBHOOK`
+
+## Security Notes
+
+- **Never commit `.env` file** to git (it's in `.gitignore`)
+- **Keep SSH keys secure** and never share
+- **Use strong passwords** for all services
+- **Enable firewall** on Hetzner server
+
+## Troubleshooting
+
+### Variables not loading
+```bash
+# Check if .env file exists
+ls -la .env
+
+# Check file permissions
+chmod 600 .env
+
+# Verify variables
+cat .env
+```
+
+### Docker Compose not using .env
+```bash
+# Explicitly specify env file
+docker-compose --env-file .env up
+
+# Or check if it's being loaded
+docker-compose config
+```
+
+### Woodpecker secrets not working
+1. Verify secret names match exactly
+2. Check repository settings
+3. Restart Woodpecker agent
+4. Check Woodpecker logs
+
+## Environment-Specific Configurations
+
+### Development
+```bash
+# .env
+DOMAIN=localhost:3000
+ADMIN_EMAIL=dev@localhost
+REDIS_URL=redis://localhost:6379
+```
+
+### Staging
+```bash
+# .env
+DOMAIN=staging.mintel.me
+ADMIN_EMAIL=staging@mintel.me
+REDIS_URL=redis://redis:6379
+```
+
+### Production
+```bash
+# .env
+DOMAIN=mintel.me
+ADMIN_EMAIL=admin@mintel.me
+REDIS_URL=redis://redis:6379
+PLAUSIBLE_DOMAIN=mintel.me
+PLAUSIBLE_SCRIPT_URL=https://analytics.mintel.me/js/script.js
+```
+
+## Available Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DOMAIN` | ✅ Yes | - | Website domain |
+| `ADMIN_EMAIL` | ✅ Yes | - | SSL contact email |
+| `REDIS_URL` | ❌ No | `redis://redis:6379` | Redis connection |
+| `PLAUSIBLE_DOMAIN` | ❌ No | Same as `DOMAIN` | Analytics domain |
+| `PLAUSIBLE_SCRIPT_URL` | ❌ No | Plausible default | Analytics script URL |
+| `DEPLOY_HOST` | CI Only | - | Hetzner server IP |
+| `DEPLOY_USER` | CI Only | `root` | SSH user |
+| `SSH_PRIVATE_KEY` | CI Only | - | SSH private key |
+| `SLACK_WEBHOOK` | ❌ No | - | Slack notifications |
+
+---
+
+**Next**: Run `./deploy.sh` or push to trigger CI/CD deployment!