mintel.me/ENV_SETUP.md

# 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!