LemonSec/QUICKSTART.md

# LemonSec Quick Start Guide

## 🚀 Deployment Steps

### Step 1: Prepare Your Server

```bash
# On Proxmox (Debian/Ubuntu)
sudo apt update && sudo apt install -y docker.io docker-compose
sudo usermod -aG docker $USER
# Log out and back in
```

### Step 2: Configure Environment

```bash
cd LemonSec

# 1. Copy environment template
cp .env.example .env

# 2. Edit with your details
nano .env
# Required:
# - CF_API_EMAIL (your Cloudflare email)
# - CF_API_KEY (from https://dash.cloudflare.com/profile/api-tokens)
# - TAILSCALE_IP (from `tailscale ip -4`)
```

### Step 3: Setup Authelia

```bash
# Generate password hash for admin user
docker run --rm authelia/authelia:latest \
  authelia crypto hash generate argon2 \
  --password 'YourSecurePassword123!'

# Edit users database
nano authelia/users_database.yml
# Replace the password hash with the one you generated
```

### Step 4: Run Setup Script

```powershell
# On Windows
.\setup.ps1

# On Linux (create first)
# bash setup.sh
```

### Step 5: Start Core Services

```bash
# Start everything
docker-compose up -d

# Check Traefik is working
docker-compose logs -f traefik

# You should see "Configuration loaded from files..." and no errors
```

### Step 6: Configure CrowdSec

```bash
# Generate API key for Traefik bouncer
docker-compose exec crowdsec cscli bouncers add traefik-bouncer

# Copy the key and add to .env:
# CROWDSEC_API_KEY=your-key-here

# Restart to apply
docker-compose up -d
```

### Step 7: Verify DNS

In Cloudflare DNS, ensure you have:

| Type | Name | Target | Proxy |
|------|------|--------|-------|
| A | @ | YOUR_IP | 🟠 |
| A | * | YOUR_IP | 🟠 |
| A | auth | YOUR_IP | 🟠 |

### Step 8: Test Access

```bash
# Test external (after DNS propagates)
curl -I https://auth.lemonlink.eu

# Test internal (via Tailscale)
curl -k -I https://traefik.local.lemonlink.eu:8443
```

## 📝 Adding Services

### External Service (e.g., Nextcloud)

```yaml
# In docker-compose.override.yml
services:
  nextcloud:
    image: nextcloud:latest
    networks:
      - services
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.nextcloud.rule=Host(`cloud.lemonlink.eu`)"
      - "traefik.http.routers.nextcloud.entrypoints=websecure"
      - "traefik.http.routers.nextcloud.tls.certresolver=letsencrypt"
      - "traefik.http.routers.nextcloud.middlewares=authelia@docker"
```

### Internal Service (e.g., Portainer)

```yaml
services:
  portainer:
    image: portainer/portainer-ce:latest
    networks:
      - services
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.portainer.rule=Host(`docker.local.lemonlink.eu`)"
      - "traefik.http.routers.portainer.entrypoints=internal"
      - "traefik.http.routers.portainer.tls.certresolver=letsencrypt"
      - "traefik.http.routers.portainer.middlewares=authelia@docker"
```

## 🔍 Common Commands

```bash
# View all logs
docker-compose logs -f

# View specific service
docker-compose logs -f authelia

# Restart service
docker-compose restart traefik

# Check CrowdSec bans
docker-compose exec crowdsec cscli decisions list

# Unban an IP
docker-compose exec crowdsec cscli decisions delete --ip 1.2.3.4

# Update everything
docker-compose pull && docker-compose up -d

# Full reset (keeps data)
docker-compose down && docker-compose up -d

# Complete wipe (⚠️ destroys data)
docker-compose down -v
```

## 🐛 Troubleshooting

### "Bad Gateway" Error
- Check service is running: `docker-compose ps`
- Check service logs: `docker-compose logs [service]`
- Verify port in labels matches container port

### Certificate Issues
- Check Cloudflare API credentials
- Verify DNS records
- Check Traefik logs for ACME errors
- Use staging first: change `certresolver` to `letsencrypt-staging`

### Authelia Redirect Loop
- Check `session.domain` in authelia/configuration.yml
- Verify time sync: `timedatectl status`
- Clear browser cookies

### Can't Access Internal Services
- Verify Tailscale is connected: `tailscale status`
- Check if port 8443 is bound to Tailscale IP
- Test locally: `curl -k https://localhost:8443`

### CrowdSec Blocking Legitimate Traffic
```bash
# Check what's blocked
docker-compose exec crowdsec cscli decisions list

# Remove false positive
docker-compose exec crowdsec cscli decisions delete --ip YOUR_IP

# Add whitelist
docker-compose exec crowdsec cscli parsers install crowdsecurity/whitelists
```

## 📊 Monitoring Stack (Optional)

```bash
# Start monitoring
docker-compose --profile monitoring up -d

# Access (via Tailscale)
# - Grafana: https://grafana.local.lemonlink.eu:8443
# - Prometheus: https://prometheus.local.lemonlink.eu:8443
```

## 🔄 Backup Strategy

```bash
# Backup script (run weekly)
#!/bin/bash
DATE=$(date +%Y%m%d)
tar czf backup-$DATE.tar.gz \
  traefik/ authelia/ crowdsec/ .env

# Backup volumes
docker run --rm \
  -v lemonsec_authelia-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/authelia-$DATE.tar.gz -C /data .
```

## 🛡️ Security Checklist

- [ ] Changed default Authelia password
- [ ] Enabled 2FA in Authelia
- [ ] Set up email notifications
- [ ] Configured CrowdSec notifications
- [ ] Enabled Cloudflare "Under Attack" mode for DDoS
- [ ] Set up regular backups
- [ ] Reviewed access logs weekly
- [ ] Updated images monthly

## 📚 Next Steps

1. **Add your services** - See `examples/` directory
2. **Configure monitoring** - Enable `--profile monitoring`
3. **Set up notifications** - Email/Discord alerts
4. **Review security** - Follow `docs/SECURITY.md`
5. **Customize** - Edit `docker-compose.override.yml`

## 💬 Getting Help

- **Traefik docs**: https://doc.traefik.io/traefik/
- **Authelia docs**: https://www.authelia.com/
- **CrowdSec docs**: https://docs.crowdsec.net/
- **Logs**: Always check `docker-compose logs [service]` first