LemonSec/README.md

# LemonSec 🍋

A comprehensive, security-focused reverse proxy and authentication stack for homelab and small business deployments.

## Architecture

```
Internet → Cloudflare → Traefik → {Authelia → Your Services}
                              ↓
                         CrowdSec (threat detection)
                              ↓
                    AdGuard Home (internal DNS)
```

### For TrueNAS Scale Users
If you run Nextcloud on TrueNAS Scale (separate VM), LemonSec acts as the secure gateway:

```
Internet → Cloudflare → Traefik (Proxmox VM) → TrueNAS Nextcloud
                              ↓
                         Authelia (family SSO)
```

See [SETUP-TRUENAS-NEXTCLOUD.md](SETUP-TRUENAS-NEXTCLOUD.md) for step-by-step guide.

## Components

| Component | Purpose | External | Internal |
|-----------|---------|----------|----------|
| **Traefik** | Reverse Proxy & Load Balancer | ✅ 443/80 | ✅ 8443 |
| **Authelia** | SSO & 2FA Authentication | ✅ auth.lemonlink.eu | ✅ |
| **CrowdSec** | Intrusion Detection/Prevention | ✅ | ✅ |
| **AdGuard Home** | DNS + Ad Blocking | ❌ | ✅ DNS |
| **Redis** | Session Storage | ❌ | ✅ |

## Network Segmentation

### External Network (`traefik-external`)
- **Entry**: Cloudflare (orange cloud)
- **Security**: CrowdSec + Authelia 2FA
- **Examples**: nextcloud.lemonlink.eu, vault.lemonlink.eu

### Internal Network (`traefik-internal`)
- **Entry**: Tailscale/VPN only
- **Security**: Authelia (one_factor on trusted networks)
- **Examples**: traefik.local.lemonlink.eu, portainer.local.lemonlink.eu

## Quick Start

### 🚀 Deploy via Portainer (Recommended for Proxmox)

The easiest way to deploy on Proxmox with Portainer:

1. **Push to Git**:
```bash
git remote add origin https://git.lemonlink.eu/impulsivefps/LemonSec.git
git push -u origin main
```

2. **In Portainer**:
- **Stacks** → **Add Stack** → **Repository**
- URL: `https://git.lemonlink.eu/impulsivefps/LemonSec`
- Add environment variables from `stack.env`
- **Deploy**

**Full Portainer guide**: [PORTAINER-DEPLOY.md](PORTAINER-DEPLOY.md)

### 🚀 TrueNAS + Nextcloud Quick Start

If your main goal is securing TrueNAS Nextcloud for family:

```bash
# 1. Clone and configure
cd LemonSec
cp .env.example .env
# Edit: Add Cloudflare API, TrueNAS_IP, Nextcloud port

# 2. Setup
./setup.ps1  # or create secrets manually

# 3. Deploy
docker-compose up -d
docker-compose -f docker-compose.yml -f docker-compose.external.yml up -d

# 4. Configure TrueNAS Nextcloud
# Apps → Nextcloud → Add environment variables
# NEXTCLOUD_TRUSTED_DOMAINS=cloud.lemonlink.eu
# OVERWRITEPROTOCOL=https
# TRUSTED_PROXIES=YOUR_PROXMOX_VM_IP
```

**Full guide**: [SETUP-TRUENAS-NEXTCLOUD.md](SETUP-TRUENAS-NEXTCLOUD.md)

### Migrating from Nginx Proxy Manager?

See [MIGRATE-FROM-NPM.md](MIGRATE-FROM-NPM.md) for side-by-side migration guide.

---

### 1. Prerequisites

- Docker & Docker Compose installed
- Domain managed by Cloudflare
- Tailscale installed on server
- Ports 80/443 forwarded to Proxmox server

### 2. Configuration

```bash
# Clone and setup
cd LemonSec

# Copy and edit environment
cp .env.example .env
nano .env

# Run setup script (generates secrets)
./setup.ps1  # On Windows
# or
bash setup.sh  # On Linux
```

### 3. Cloudflare Setup

See [CLOUDFLARE.md](docs/CLOUDFLARE.md) for detailed DNS configuration.

Quick checklist:
- [ ] Create API token with DNS:Edit permissions
- [ ] Add A record pointing to your server IP
- [ ] Enable orange cloud (proxy)
- [ ] Set SSL/TLS mode to "Full (strict)"
- [ ] Enable "Always Use HTTPS"

### 4. Deploy

```bash
# Start core services
docker-compose up -d

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

# Generate CrowdSec API key
docker-compose exec crowdsec cscli bouncers add traefik-bouncer
# Add key to .env, then restart
docker-compose up -d

# Setup Authelia users
docker run authelia/authelia:latest authelia crypto hash generate argon2 --password 'YOUR_PASSWORD'
# Add hash to authelia/users_database.yml
```

### 5. Add Your Services

See [examples/](examples/) for service templates.

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

## Security Features

### 1. Multi-Factor Authentication
- TOTP (Google Authenticator, Authy, etc.)
- WebAuthn/FIDO2 (YubiKey, Windows Hello, etc.)
- Duo Push (with configuration)

### 2. Threat Detection (CrowdSec)
- Real-time log analysis
- Community blocklists
- Automatic IP banning
- Metrics and alerts

### 3. Network Isolation
- Internal services inaccessible from internet
- External services protected by auth
- Docker network segmentation

### 4. TLS/SSL
- Automatic Let's Encrypt certificates
- Wildcard certificates for subdomains
- Modern TLS 1.3 configuration

### 5. Security Headers
- HSTS (1 year)
- CSP (Content Security Policy)
- X-Frame-Options, X-Content-Type-Options
- Referrer-Policy

## Directory Structure

```
LemonSec/
├── docker-compose.yml          # Main stack
├── .env                        # Your secrets (gitignored)
├── .env.example                # Template
├── setup.ps1                   # Windows setup
├── traefik/
│   ├── traefik.yml             # Static config
│   ├── dynamic/                # Dynamic config
│   │   ├── middlewares.yml     # Security middlewares
│   │   └── tls.yml             # TLS options
│   ├── crowdsec/               # CrowdSec bouncer config
│   └── logs/                   # Access logs
├── authelia/
│   ├── configuration.yml       # Authelia settings
│   └── users_database.yml      # User accounts
├── crowdsec/
│   └── acquis.yaml             # Log sources
├── adguard/                    # AdGuard data (volumes)
├── monitoring/                 # Prometheus/Grafana configs
├── examples/                   # Service examples
└── docs/                       # Documentation
```

## Common Operations

### View Logs
```bash
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f traefik

# CrowdSec decisions
docker-compose exec crowdsec cscli decisions list

# CrowdSec metrics
docker-compose exec crowdsec cscli metrics
```

### Update
```bash
# Pull latest images
docker-compose pull

# Recreate containers
docker-compose up -d
```

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

# Backup configs
tar czf lemonsec-config-backup.tar.gz traefik/ authelia/ crowdsec/ .env
```

### Add User to Authelia
```bash
# Generate password hash
docker run authelia/authelia:latest authelia crypto hash generate argon2 --password 'NEWPASSWORD'

# Edit authelia/users_database.yml
# Add user entry with hash
# Restart authelia
docker-compose restart authelia
```

## Troubleshooting

### Traefik not getting certificates
1. Check Cloudflare API credentials in `.env`
2. Verify DNS records point to your IP
3. Check Traefik logs: `docker-compose logs traefik`
4. Test with staging first: change `certresolver` to `letsencrypt-staging`

### Authelia redirect loops
1. Check `session.domain` matches your domain
2. Verify cookies aren't blocked
3. Check time sync on server: `ntpdate -s time.cloudflare.com`

### CrowdSec blocking legitimate traffic
```bash
# Check decisions
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
```

## Security Checklist

- [ ] Change all default passwords
- [ ] Enable 2FA for all users
- [ ] Set up email notifications for Authelia
- [ ] Configure CrowdSec notifications
- [ ] Review Cloudflare security settings
- [ ] Enable fail2ban on host (optional)
- [ ] Regular backups
- [ ] Update images monthly

## License

MIT - Use at your own risk. This is a homelab security stack, not enterprise-grade.