Revamp Swarm example documentation and streamline deployment instructions
- Consolidated and simplified Swarm example README to focus on YAML header comments for documentation. - Removed redundant and extended sections, replacing with concise steps for getting started. - Standardized YAML headers across `easyhaproxy.yml`, `services.yml`, and `portainer.yml` with a clearer and more readable format. - Enhanced user guidance for deployment, setup requirements, verification, and cleanup.
This commit is contained in:
Joao Gilberto Magalhaes
parent
5397f0166e
commit
b9a9bee0b9
29 changed files with 1459 additions and 2861 deletions
|
|
@ -1,170 +1,52 @@
|
|||
# Docker Swarm Examples
|
||||
|
||||
This directory contains Docker Swarm stack examples demonstrating EasyHAProxy in a Swarm cluster environment.
|
||||
|
||||
## What is Docker Swarm Mode?
|
||||
|
||||
Docker Swarm mode enables:
|
||||
- **Service orchestration** across multiple nodes
|
||||
- **Service scaling** with replicas
|
||||
- **Load balancing** across service replicas
|
||||
- **Rolling updates** with zero downtime
|
||||
- **Service discovery** via overlay networks
|
||||
|
||||
EasyHAProxy automatically discovers Swarm services and routes traffic based on service labels.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### 1. Initialize Docker Swarm
|
||||
|
||||
```bash
|
||||
# On manager node
|
||||
docker swarm init
|
||||
|
||||
# On worker nodes (use token from swarm init output)
|
||||
docker swarm join --token <token> <manager-ip>:2377
|
||||
```
|
||||
|
||||
### 2. Create Overlay Network
|
||||
|
||||
```bash
|
||||
# Create attachable overlay network for EasyHAProxy
|
||||
docker network create --driver overlay --attachable easyhaproxy
|
||||
```
|
||||
|
||||
**Why attachable?** Allows both swarm services and standalone containers to connect.
|
||||
|
||||
---
|
||||
|
||||
## Files in This Directory
|
||||
|
||||
- `easyhaproxy.yml` - EasyHAProxy service stack
|
||||
- `services.yml` - Example application services
|
||||
- `portainer.yml` - Portainer management interface
|
||||
- `certs/` - Directory for SSL certificates
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites: Generate SSL Certificates
|
||||
|
||||
**IMPORTANT:** Before running any examples, you must generate the required SSL certificates:
|
||||
|
||||
```bash
|
||||
# From the repository root
|
||||
./examples/generate-keys.sh
|
||||
```
|
||||
|
||||
This script automatically generates:
|
||||
- SSL certificates for host1.local and host2.local (placed in `examples/swarm/certs/`)
|
||||
- JWT keys for authentication examples
|
||||
- All other .pem files needed for testing
|
||||
|
||||
**Note:** These are self-signed certificates for testing only. Do not use in production.
|
||||
|
||||
---
|
||||
Self-contained examples for EasyHAProxy in Docker Swarm mode. **All documentation is in the YAML files as header comments.**
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Deploy EasyHAProxy
|
||||
1. Pick an example below
|
||||
2. Open the YAML file
|
||||
3. Read the header comments for complete instructions
|
||||
4. Run the commands step-by-step
|
||||
|
||||
```bash
|
||||
cd examples/swarm
|
||||
## Prerequisites
|
||||
|
||||
# Edit easyhaproxy.yml and change:
|
||||
# EASYHAPROXY_CERTBOT_EMAIL: your-email@example.com
|
||||
All examples require:
|
||||
- Docker Swarm initialized (`docker swarm init`)
|
||||
- Overlay network created (`docker network create --driver overlay --attachable easyhaproxy`)
|
||||
- EasyHAProxy deployed (`docker stack deploy -c easyhaproxy.yml easyhaproxy`)
|
||||
|
||||
# Deploy stack
|
||||
docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
```
|
||||
See header comments in each file for detailed setup instructions.
|
||||
|
||||
**What this creates:**
|
||||
- EasyHAProxy service with 1 replica
|
||||
- Exposed ports: 80, 443, 1936
|
||||
- Mounts Docker socket for service discovery
|
||||
- Mounts volume for certbot certificates
|
||||
## Basic Examples
|
||||
|
||||
### 2. Deploy Example Services
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [easyhaproxy.yml](easyhaproxy.yml) | EasyHAProxy service for Swarm with stats and certbot |
|
||||
| [services.yml](services.yml) | Basic services with SSL (embedded cert and file-based) |
|
||||
| [portainer.yml](portainer.yml) | Portainer management UI behind EasyHAProxy |
|
||||
|
||||
```bash
|
||||
docker stack deploy -c services.yml myapp
|
||||
```
|
||||
## Plugin Examples
|
||||
|
||||
### 3. (Optional) Deploy Portainer
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [jwt-validator.yml](jwt-validator.yml) | JWT token validation for API protection |
|
||||
| [ip-whitelist.yml](ip-whitelist.yml) | IP whitelist for admin panels or sensitive services |
|
||||
| [cloudflare.yml](cloudflare.yml) | Restore real client IPs when behind Cloudflare CDN |
|
||||
| [plugins-combined.yml](plugins-combined.yml) | Multiple plugins combined for layered security |
|
||||
|
||||
```bash
|
||||
docker stack deploy -c portainer.yml portainer
|
||||
```
|
||||
## Documentation Structure
|
||||
|
||||
---
|
||||
Each YAML file contains:
|
||||
- **WHAT THIS DEMONSTRATES** - Key features and concepts
|
||||
- **REQUIREMENTS** - Idempotent setup commands (safe to run multiple times)
|
||||
- **HOW TO START** - Command to deploy the stack
|
||||
- **HOW TO VERIFY IT'S WORKING** - Test commands with expected outputs
|
||||
- **CLEAN UP** - Commands to remove resources
|
||||
|
||||
## Example Files Explained
|
||||
## Important: Service Labels
|
||||
|
||||
### easyhaproxy.yml
|
||||
|
||||
```yaml
|
||||
services:
|
||||
haproxy:
|
||||
image: byjg/easy-haproxy:4.6.0
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock # Service discovery
|
||||
- ./certs:/certs/haproxy # SSL certificates
|
||||
- certs_certbot:/certs/certbot # Let's Encrypt certs
|
||||
deploy:
|
||||
replicas: 1 # Single instance
|
||||
environment:
|
||||
EASYHAPROXY_DISCOVER: swarm # Swarm mode!
|
||||
EASYHAPROXY_SSL_MODE: "loose"
|
||||
EASYHAPROXY_CERTBOT_EMAIL: changeme@example.org # Change this!
|
||||
HAPROXY_CUSTOMERRORS: "true"
|
||||
HAPROXY_USERNAME: admin
|
||||
HAPROXY_PASSWORD: password
|
||||
HAPROXY_STATS_PORT: 1936
|
||||
ports:
|
||||
- "80:80/tcp"
|
||||
- "443:443/tcp"
|
||||
- "1936:1936/tcp"
|
||||
networks:
|
||||
- easyhaproxy # Overlay network
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true # Created separately
|
||||
|
||||
volumes:
|
||||
certs_certbot: # Persistent certbot data
|
||||
```
|
||||
|
||||
**Key differences from Docker Compose mode:**
|
||||
- `EASYHAPROXY_DISCOVER: swarm` - Discovery mode
|
||||
- `deploy.replicas: 1` - Swarm deployment config
|
||||
- External overlay network
|
||||
|
||||
---
|
||||
|
||||
## Service Labels in Swarm
|
||||
|
||||
Service labels are similar to container labels but applied to **services**, not containers.
|
||||
|
||||
### Basic Service Example
|
||||
|
||||
```yaml
|
||||
services:
|
||||
webapp:
|
||||
image: nginx:alpine
|
||||
deploy:
|
||||
replicas: 3 # 3 instances for load balancing
|
||||
labels:
|
||||
# Service labels (not container labels!)
|
||||
easyhaproxy.http.host: "webapp.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "80"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
```
|
||||
|
||||
**Important:** Use `deploy.labels`, NOT top-level `labels`!
|
||||
In Swarm mode, labels must be under `deploy.labels`, NOT top-level `labels`:
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT - Service labels
|
||||
|
|
@ -177,760 +59,9 @@ labels:
|
|||
easyhaproxy.http.host: example.com
|
||||
```
|
||||
|
||||
---
|
||||
## Additional Documentation
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Use Case 1: Simple HTTP Service
|
||||
|
||||
```yaml
|
||||
services:
|
||||
myapp:
|
||||
image: my-app:latest
|
||||
deploy:
|
||||
replicas: 3
|
||||
labels:
|
||||
easyhaproxy.http.host: "myapp.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "3000"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true
|
||||
```
|
||||
|
||||
Deploy:
|
||||
```bash
|
||||
docker stack deploy -c myapp.yml myapp
|
||||
```
|
||||
|
||||
### Use Case 2: HTTPS with Let's Encrypt
|
||||
|
||||
```yaml
|
||||
services:
|
||||
secure-app:
|
||||
image: secure-app:latest
|
||||
deploy:
|
||||
replicas: 2
|
||||
labels:
|
||||
easyhaproxy.http.host: "secure.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "8080"
|
||||
easyhaproxy.http.certbot: "true"
|
||||
easyhaproxy.http.redirect_ssl: "true"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
- Public IP with DNS pointing to swarm
|
||||
- Ports 80/443 open
|
||||
- Certbot email configured in `easyhaproxy.yml`
|
||||
|
||||
### Use Case 3: Multiple Domains, One Service
|
||||
|
||||
```yaml
|
||||
services:
|
||||
webapp:
|
||||
image: webapp:latest
|
||||
deploy:
|
||||
replicas: 4
|
||||
labels:
|
||||
# Primary domain
|
||||
easyhaproxy.http.host: "example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "8080"
|
||||
|
||||
# Additional domain (www)
|
||||
easyhaproxy.http2.host: "www.example.com"
|
||||
easyhaproxy.http2.port: "80"
|
||||
easyhaproxy.http2.localport: "8080"
|
||||
|
||||
# API subdomain
|
||||
easyhaproxy.api.host: "api.example.com"
|
||||
easyhaproxy.api.port: "80"
|
||||
easyhaproxy.api.localport: "8080"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
```
|
||||
|
||||
### Use Case 4: Service with Plugins
|
||||
|
||||
```yaml
|
||||
services:
|
||||
api:
|
||||
image: api-server:latest
|
||||
deploy:
|
||||
replicas: 3
|
||||
labels:
|
||||
easyhaproxy.http.host: "api.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "8080"
|
||||
# Enable plugins
|
||||
easyhaproxy.http.plugins: "jwt_validator,deny_pages"
|
||||
# Configure JWT validator
|
||||
easyhaproxy.http.plugin.jwt_validator.algorithm: "RS256"
|
||||
easyhaproxy.http.plugin.jwt_validator.issuer: "https://auth.example.com/"
|
||||
easyhaproxy.http.plugin.jwt_validator.pubkey_path: "/etc/haproxy/jwt_keys/api.pem"
|
||||
# Configure deny_pages
|
||||
easyhaproxy.http.plugin.deny_pages.paths: "/admin,/private"
|
||||
easyhaproxy.http.plugin.deny_pages.status_code: "403"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
```
|
||||
|
||||
### Use Case 5: Multiple Services with Load Balancing
|
||||
|
||||
```yaml
|
||||
services:
|
||||
frontend:
|
||||
image: frontend-app:latest
|
||||
deploy:
|
||||
replicas: 2
|
||||
labels:
|
||||
easyhaproxy.http.host: "example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "3000"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
api:
|
||||
image: api-server:latest
|
||||
deploy:
|
||||
replicas: 5 # More replicas for API
|
||||
labels:
|
||||
easyhaproxy.http.host: "api.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "8080"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
admin:
|
||||
image: admin-panel:latest
|
||||
deploy:
|
||||
replicas: 1
|
||||
labels:
|
||||
easyhaproxy.http.host: "admin.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "4000"
|
||||
# Restrict access
|
||||
easyhaproxy.http.plugins: "ip_whitelist"
|
||||
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: "192.168.1.0/24"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin Examples
|
||||
|
||||
### JWT Validator Plugin
|
||||
|
||||
Secure your API with JWT token validation in Swarm:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
haproxy:
|
||||
image: byjg/easy-haproxy:4.6.0
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- jwt_keys:/etc/haproxy/jwt_keys
|
||||
deploy:
|
||||
replicas: 1
|
||||
environment:
|
||||
EASYHAPROXY_DISCOVER: swarm
|
||||
ports:
|
||||
- "80:80/tcp"
|
||||
- "443:443/tcp"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
api:
|
||||
image: my-api:latest
|
||||
deploy:
|
||||
replicas: 5
|
||||
labels:
|
||||
easyhaproxy.http.host: "api.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "8080"
|
||||
# Enable JWT validation
|
||||
easyhaproxy.http.plugins: "jwt_validator"
|
||||
easyhaproxy.http.plugin.jwt_validator.algorithm: "RS256"
|
||||
easyhaproxy.http.plugin.jwt_validator.issuer: "https://auth.example.com/"
|
||||
easyhaproxy.http.plugin.jwt_validator.audience: "https://api.example.com"
|
||||
easyhaproxy.http.plugin.jwt_validator.pubkey_path: "/etc/haproxy/jwt_keys/api_pubkey.pem"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true
|
||||
|
||||
volumes:
|
||||
jwt_keys:
|
||||
```
|
||||
|
||||
**Deploy public key using Docker config:**
|
||||
```bash
|
||||
# Create Docker config with public key
|
||||
docker config create jwt_api_pubkey ./api_pubkey.pem
|
||||
|
||||
# Update EasyHAProxy service to use config
|
||||
docker service update \
|
||||
--config-add source=jwt_api_pubkey,target=/etc/haproxy/jwt_keys/api_pubkey.pem \
|
||||
easyhaproxy_haproxy
|
||||
```
|
||||
|
||||
**Test:**
|
||||
```bash
|
||||
# Without token
|
||||
curl http://api.example.com/users
|
||||
# Response: Missing Authorization HTTP header
|
||||
|
||||
# With valid token
|
||||
curl -H "Authorization: Bearer eyJhbGc..." http://api.example.com/users
|
||||
# Response: Success
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cloudflare IP Restoration Plugin
|
||||
|
||||
Restore original visitor IPs in Swarm environment:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
haproxy:
|
||||
image: byjg/easy-haproxy:4.6.0
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
configs:
|
||||
- source: cloudflare_ips
|
||||
target: /etc/haproxy/cloudflare_ips.lst
|
||||
deploy:
|
||||
replicas: 1
|
||||
environment:
|
||||
EASYHAPROXY_DISCOVER: swarm
|
||||
ports:
|
||||
- "80:80/tcp"
|
||||
- "443:443/tcp"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
webapp:
|
||||
image: webapp:latest
|
||||
deploy:
|
||||
replicas: 3
|
||||
labels:
|
||||
easyhaproxy.http.host: "myapp.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "8080"
|
||||
# Enable Cloudflare plugin
|
||||
easyhaproxy.http.plugins: "cloudflare"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true
|
||||
|
||||
configs:
|
||||
cloudflare_ips:
|
||||
file: ./cloudflare_ips.lst
|
||||
```
|
||||
|
||||
**Create Cloudflare IP list:**
|
||||
```bash
|
||||
# Download Cloudflare IPs
|
||||
curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
|
||||
curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
|
||||
|
||||
# Deploy stack
|
||||
docker stack deploy -c cloudflare-stack.yml myapp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### IP Whitelist Plugin
|
||||
|
||||
Restrict admin panel to specific IPs in Swarm:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
admin:
|
||||
image: admin-panel:latest
|
||||
deploy:
|
||||
replicas: 2
|
||||
labels:
|
||||
easyhaproxy.http.host: "admin.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "4000"
|
||||
# Enable IP whitelist
|
||||
easyhaproxy.http.plugins: "ip_whitelist"
|
||||
# Allow office network and VPN
|
||||
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24,198.51.100.0/24,10.8.0.0/16"
|
||||
easyhaproxy.http.plugin.ip_whitelist.status_code: "403"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true
|
||||
```
|
||||
|
||||
**Test:**
|
||||
```bash
|
||||
# From office IP (203.0.113.50)
|
||||
curl http://admin.example.com
|
||||
# Response: Success
|
||||
|
||||
# From home/blocked IP
|
||||
curl http://admin.example.com
|
||||
# Response: HTTP 403 Forbidden
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Multiple Plugins Combined
|
||||
|
||||
Production-ready setup with multiple security layers:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
haproxy:
|
||||
image: byjg/easy-haproxy:4.6.0
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
configs:
|
||||
- source: cloudflare_ips
|
||||
target: /etc/haproxy/cloudflare_ips.lst
|
||||
- source: jwt_pubkey
|
||||
target: /etc/haproxy/jwt_keys/api_pubkey.pem
|
||||
deploy:
|
||||
replicas: 1
|
||||
placement:
|
||||
constraints:
|
||||
- node.role == manager
|
||||
environment:
|
||||
EASYHAPROXY_DISCOVER: swarm
|
||||
EASYHAPROXY_SSL_MODE: "loose"
|
||||
EASYHAPROXY_CERTBOT_EMAIL: admin@example.com
|
||||
ports:
|
||||
- "80:80/tcp"
|
||||
- "443:443/tcp"
|
||||
- "1936:1936/tcp"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
# Public website with Cloudflare
|
||||
website:
|
||||
image: website:latest
|
||||
deploy:
|
||||
replicas: 4
|
||||
labels:
|
||||
easyhaproxy.http.host: "example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "3000"
|
||||
easyhaproxy.http.certbot: "true"
|
||||
easyhaproxy.http.redirect_ssl: "true"
|
||||
# Cloudflare + block sensitive paths
|
||||
easyhaproxy.http.plugins: "cloudflare,deny_pages"
|
||||
easyhaproxy.http.plugin.deny_pages.paths: "/admin,/.env,/config"
|
||||
easyhaproxy.http.plugin.deny_pages.status_code: "404"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
# Authenticated API with JWT
|
||||
api:
|
||||
image: api:latest
|
||||
deploy:
|
||||
replicas: 6
|
||||
labels:
|
||||
easyhaproxy.http.host: "api.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "8080"
|
||||
easyhaproxy.http.certbot: "true"
|
||||
# Cloudflare + JWT + block internal endpoints
|
||||
easyhaproxy.http.plugins: "cloudflare,jwt_validator,deny_pages"
|
||||
easyhaproxy.http.plugin.jwt_validator.algorithm: "RS256"
|
||||
easyhaproxy.http.plugin.jwt_validator.issuer: "https://auth.example.com/"
|
||||
easyhaproxy.http.plugin.jwt_validator.audience: "https://api.example.com"
|
||||
easyhaproxy.http.plugin.jwt_validator.pubkey_path: "/etc/haproxy/jwt_keys/api_pubkey.pem"
|
||||
easyhaproxy.http.plugin.deny_pages.paths: "/internal,/metrics"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
# Admin panel with strict IP restrictions
|
||||
admin:
|
||||
image: admin:latest
|
||||
deploy:
|
||||
replicas: 2
|
||||
labels:
|
||||
easyhaproxy.http.host: "admin.example.com"
|
||||
easyhaproxy.http.port: "80"
|
||||
easyhaproxy.http.localport: "4000"
|
||||
easyhaproxy.http.certbot: "true"
|
||||
# IP whitelist only (no public access)
|
||||
easyhaproxy.http.plugins: "ip_whitelist"
|
||||
easyhaproxy.http.plugin.ip_whitelist.allowed_ips: "203.0.113.0/24"
|
||||
easyhaproxy.http.plugin.ip_whitelist.status_code: "403"
|
||||
networks:
|
||||
- easyhaproxy
|
||||
|
||||
networks:
|
||||
easyhaproxy:
|
||||
external: true
|
||||
|
||||
configs:
|
||||
cloudflare_ips:
|
||||
file: ./cloudflare_ips.lst
|
||||
jwt_pubkey:
|
||||
file: ./api_pubkey.pem
|
||||
```
|
||||
|
||||
**Deploy:**
|
||||
```bash
|
||||
docker stack deploy -c production-stack.yml production
|
||||
```
|
||||
|
||||
**Security layers:**
|
||||
- **Website**: Cloudflare IP restoration + path blocking
|
||||
- **API**: Cloudflare + JWT validation + internal path blocking
|
||||
- **Admin**: Strict IP whitelist (office network only)
|
||||
|
||||
---
|
||||
|
||||
## Scaling Services
|
||||
|
||||
Scale services dynamically:
|
||||
|
||||
```bash
|
||||
# Scale up
|
||||
docker service scale myapp_webapp=10
|
||||
|
||||
# Scale down
|
||||
docker service scale myapp_webapp=2
|
||||
|
||||
# Check replicas
|
||||
docker service ls
|
||||
```
|
||||
|
||||
EasyHAProxy automatically detects all replicas and load balances across them.
|
||||
|
||||
---
|
||||
|
||||
## Rolling Updates
|
||||
|
||||
Update services with zero downtime:
|
||||
|
||||
```bash
|
||||
# Update service image
|
||||
docker service update --image webapp:v2 myapp_webapp
|
||||
|
||||
# Update with custom settings
|
||||
docker service update \
|
||||
--image webapp:v2 \
|
||||
--update-parallelism 2 \
|
||||
--update-delay 10s \
|
||||
myapp_webapp
|
||||
```
|
||||
|
||||
EasyHAProxy continues routing to healthy containers during rollout.
|
||||
|
||||
---
|
||||
|
||||
## Management Commands
|
||||
|
||||
### View Stacks
|
||||
|
||||
```bash
|
||||
docker stack ls
|
||||
```
|
||||
|
||||
### View Services in Stack
|
||||
|
||||
```bash
|
||||
docker stack services myapp
|
||||
```
|
||||
|
||||
### View Service Details
|
||||
|
||||
```bash
|
||||
docker service inspect myapp_webapp
|
||||
```
|
||||
|
||||
### View Service Logs
|
||||
|
||||
```bash
|
||||
docker service logs -f myapp_webapp
|
||||
```
|
||||
|
||||
### Update Service Labels
|
||||
|
||||
```bash
|
||||
docker service update \
|
||||
--label-add easyhaproxy.http.certbot=true \
|
||||
myapp_webapp
|
||||
```
|
||||
|
||||
### Remove Stack
|
||||
|
||||
```bash
|
||||
docker stack rm myapp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SSL Certificates in Swarm
|
||||
|
||||
### Option 1: Let's Encrypt (Recommended)
|
||||
|
||||
Configure in `easyhaproxy.yml`:
|
||||
```yaml
|
||||
environment:
|
||||
EASYHAPROXY_CERTBOT_EMAIL: your-email@example.com
|
||||
```
|
||||
|
||||
Enable per-service:
|
||||
```yaml
|
||||
deploy:
|
||||
labels:
|
||||
easyhaproxy.http.certbot: "true"
|
||||
```
|
||||
|
||||
### Option 2: Custom Certificates
|
||||
|
||||
Mount certificates directory:
|
||||
```yaml
|
||||
# easyhaproxy.yml
|
||||
volumes:
|
||||
- ./certs:/certs/haproxy
|
||||
```
|
||||
|
||||
Place certificate files:
|
||||
```bash
|
||||
./certs/
|
||||
├── example.com.pem
|
||||
├── api.example.com.pem
|
||||
└── secure.example.com.pem
|
||||
```
|
||||
|
||||
### Option 3: Docker Secrets (Production)
|
||||
|
||||
```bash
|
||||
# Create secret
|
||||
docker secret create example_com_cert ./example.com.pem
|
||||
|
||||
# Use in stack
|
||||
|
||||
services:
|
||||
haproxy:
|
||||
secrets:
|
||||
- example_com_cert
|
||||
environment:
|
||||
EASYHAPROXY_SSL_CERT_example_com: /run/secrets/example_com_cert
|
||||
|
||||
secrets:
|
||||
example_com_cert:
|
||||
external: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring and Stats
|
||||
|
||||
### HAProxy Stats Interface
|
||||
|
||||
Access at: `http://<swarm-ip>:1936`
|
||||
- Username: `admin` (configured in `easyhaproxy.yml`)
|
||||
- Password: `password` (configured in `easyhaproxy.yml`)
|
||||
|
||||
### Service Health
|
||||
|
||||
```bash
|
||||
# Check service health
|
||||
docker service ps myapp_webapp
|
||||
|
||||
# View detailed service info
|
||||
docker service inspect --pretty myapp_webapp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Not Detected
|
||||
|
||||
**Check service labels:**
|
||||
```bash
|
||||
docker service inspect myapp_webapp | grep -A 20 Labels
|
||||
```
|
||||
|
||||
Ensure labels are under `deploy.labels`, not top-level `labels`.
|
||||
|
||||
**Check EasyHAProxy logs:**
|
||||
```bash
|
||||
docker service logs -f easyhaproxy_haproxy
|
||||
```
|
||||
|
||||
### Service Unreachable (503)
|
||||
|
||||
**Causes:**
|
||||
- Service containers not ready yet
|
||||
- Wrong network configuration
|
||||
- Service crashed
|
||||
|
||||
**Debug:**
|
||||
```bash
|
||||
# Check service is running
|
||||
docker service ps myapp_webapp
|
||||
|
||||
# Check network
|
||||
docker network inspect easyhaproxy
|
||||
|
||||
# Test service directly
|
||||
docker run --rm --network easyhaproxy alpine \
|
||||
wget -O- http://myapp_webapp:8080
|
||||
```
|
||||
|
||||
### Overlay Network Issues
|
||||
|
||||
**Create network if missing:**
|
||||
```bash
|
||||
docker network create --driver overlay --attachable easyhaproxy
|
||||
```
|
||||
|
||||
**Verify service is on network:**
|
||||
```bash
|
||||
docker service inspect myapp_webapp | grep -A 5 Networks
|
||||
```
|
||||
|
||||
### EasyHAProxy Not Starting
|
||||
|
||||
**Check Docker socket permissions:**
|
||||
```bash
|
||||
docker service logs easyhaproxy_haproxy
|
||||
```
|
||||
|
||||
**Verify socket is mounted:**
|
||||
```bash
|
||||
docker service inspect easyhaproxy_haproxy | grep -A 5 Mounts
|
||||
```
|
||||
|
||||
### Certificate Issues
|
||||
|
||||
**Certbot fails:**
|
||||
- Ensure swarm is publicly accessible
|
||||
- Check DNS points to swarm IP
|
||||
- Verify ports 80/443 are open
|
||||
- Check certbot logs: `docker service logs easyhaproxy_haproxy | grep certbot`
|
||||
|
||||
**Custom cert not found:**
|
||||
```bash
|
||||
# Exec into service container
|
||||
docker exec -it $(docker ps -q -f name=easyhaproxy) sh
|
||||
ls -la /certs/haproxy/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## High Availability Setup
|
||||
|
||||
### Multiple Manager Nodes
|
||||
|
||||
```bash
|
||||
# On additional manager nodes
|
||||
docker swarm join-token manager
|
||||
# Use token on new nodes
|
||||
```
|
||||
|
||||
### EasyHAProxy Constraints
|
||||
|
||||
Run EasyHAProxy on specific node:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
haproxy:
|
||||
deploy:
|
||||
placement:
|
||||
constraints:
|
||||
- node.role == manager
|
||||
- node.labels.haproxy == true
|
||||
```
|
||||
|
||||
Label node:
|
||||
```bash
|
||||
docker node update --label-add haproxy=true <node-name>
|
||||
```
|
||||
|
||||
### Multiple EasyHAProxy Replicas
|
||||
|
||||
**Not recommended** - EasyHAProxy should run as single instance because:
|
||||
- Multiple instances would compete for port binding
|
||||
- Use external load balancer (cloud LB, keepalived, etc.) for HA
|
||||
|
||||
**Alternative HA pattern:**
|
||||
```
|
||||
Internet → Cloud Load Balancer → Multiple Swarm Nodes
|
||||
└→ EasyHAProxy (runs on 1 node)
|
||||
└→ Services (distributed across nodes)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Overlay Networks:**
|
||||
- Create dedicated network for EasyHAProxy
|
||||
- Use `--attachable` for flexibility
|
||||
|
||||
2. **Service Labels:**
|
||||
- Always use `deploy.labels`, never top-level `labels`
|
||||
- Use clear, descriptive domain names
|
||||
|
||||
3. **Replicas:**
|
||||
- Start with 2-3 replicas per service
|
||||
- Scale based on load monitoring
|
||||
- Use odd number for consensus (3, 5, 7)
|
||||
|
||||
4. **Updates:**
|
||||
- Use rolling updates for zero downtime
|
||||
- Set appropriate `update-delay`
|
||||
- Test in staging first
|
||||
|
||||
5. **Monitoring:**
|
||||
- Enable HAProxy stats
|
||||
- Use Portainer for visual management
|
||||
- Monitor service health regularly
|
||||
|
||||
6. **Security:**
|
||||
- Use Docker secrets for sensitive data
|
||||
- Restrict admin panel access
|
||||
- Use SSL/TLS for production
|
||||
- Apply IP whitelisting for admin interfaces
|
||||
|
||||
7. **Persistence:**
|
||||
- Use volumes for certbot certificates
|
||||
- Backup certificate volumes
|
||||
- Store custom certs in version control (encrypted)
|
||||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Docker Swarm Documentation](../../docs/swarm.md)
|
||||
- [Docker Swarm Guide](../../docs/swarm.md)
|
||||
- [Container Labels Reference](../../docs/container-labels.md)
|
||||
- [Using Plugins](../../docs/plugins.md)
|
||||
- [Using Plugins](../../docs/plugins/)
|
||||
- [ACME/Let's Encrypt](../../docs/acme.md)
|
||||
- [Environment Variables](../../docs/environment-variable.md)
|
||||
- [Official Docker Swarm Docs](https://docs.docker.com/engine/swarm/)
|
||||
|
|
|
|||
|
|
@ -1,26 +1,69 @@
|
|||
# Cloudflare IP Restoration Plugin Example for Docker Swarm
|
||||
# ==============================================================================
|
||||
# EXAMPLE: Cloudflare IP Restoration (Swarm)
|
||||
# ==============================================================================
|
||||
#
|
||||
# This example demonstrates restoring original visitor IPs when using Cloudflare CDN
|
||||
# WHAT THIS DEMONSTRATES:
|
||||
# - Restoring original visitor IPs when behind Cloudflare CDN
|
||||
# - Using Docker configs to manage Cloudflare IP lists
|
||||
# - Service discovery in Swarm mode with plugins
|
||||
# - Load balancing across multiple replicas
|
||||
#
|
||||
# Prerequisites:
|
||||
# 1. Docker Swarm initialized:
|
||||
# docker swarm init
|
||||
# REQUIREMENTS (run these first):
|
||||
# ```bash
|
||||
# # Initialize Docker Swarm (if not already initialized)
|
||||
# docker swarm init
|
||||
#
|
||||
# 2. Create overlay network:
|
||||
# docker network create --driver overlay --attachable easyhaproxy
|
||||
# # Create overlay network (idempotent)
|
||||
# docker network ls | grep -q easyhaproxy || docker network create --driver overlay --attachable easyhaproxy
|
||||
#
|
||||
# 3. Download Cloudflare IPs and create Docker config:
|
||||
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
|
||||
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
|
||||
# docker config create cloudflare_ips cloudflare_ips.lst
|
||||
# # Ensure EasyHAProxy is deployed
|
||||
# docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
#
|
||||
# 4. Deploy the stack:
|
||||
# docker stack deploy -c cloudflare.yml webapp
|
||||
# # Download Cloudflare IP ranges and create Docker config
|
||||
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
|
||||
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
|
||||
# docker config create cloudflare_ips cloudflare_ips.lst
|
||||
# rm cloudflare_ips.lst
|
||||
#
|
||||
# 5. Test:
|
||||
# curl http://<swarm-ip>/
|
||||
# # Add to /etc/hosts for local testing (idempotent)
|
||||
# grep -q "myapp.example.com" /etc/hosts || echo "127.0.0.1 myapp.example.com" | sudo tee -a /etc/hosts
|
||||
# ```
|
||||
#
|
||||
# Note: This plugin is most useful when your site is actually behind Cloudflare.
|
||||
# HOW TO START:
|
||||
# ```bash
|
||||
# docker stack deploy -c cloudflare.yml webapp
|
||||
# ```
|
||||
#
|
||||
# HOW TO VERIFY IT'S WORKING:
|
||||
# ```bash
|
||||
# # Check stack is deployed
|
||||
# docker stack ls | grep webapp
|
||||
# # Expected: webapp stack listed
|
||||
#
|
||||
# # Check service is running
|
||||
# docker service ls | grep webapp_webapp
|
||||
# # Expected: webapp_webapp with 4/4 replicas
|
||||
#
|
||||
# # Test the application
|
||||
# curl -H "Host: myapp.example.com" http://localhost/
|
||||
# # Expected: 200 OK with "App Behind Cloudflare"
|
||||
#
|
||||
# # Check HAProxy config includes Cloudflare IPs
|
||||
# docker exec $(docker ps -q -f name=easyhaproxy_haproxy) cat /etc/haproxy/haproxy.cfg | grep -A 5 "cloudflare"
|
||||
# # Expected: ACL rules for Cloudflare IP ranges
|
||||
# ```
|
||||
#
|
||||
# CLEAN UP:
|
||||
# ```bash
|
||||
# docker stack rm webapp
|
||||
# # To also remove the Cloudflare IPs config:
|
||||
# # docker config rm cloudflare_ips
|
||||
# ```
|
||||
#
|
||||
# NOTE: This plugin is most useful when your site is actually behind Cloudflare CDN.
|
||||
# The plugin uses the CF-Connecting-IP header to restore the original visitor IP.
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
version: "3.7"
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,55 @@
|
|||
# To Install
|
||||
# docker network create --driver overlay --attachable easyhaproxy
|
||||
# ==============================================================================
|
||||
# EXAMPLE: EasyHAProxy for Docker Swarm
|
||||
# ==============================================================================
|
||||
#
|
||||
# WHAT THIS DEMONSTRATES:
|
||||
# - EasyHAProxy running in Swarm mode with service discovery
|
||||
# - HAProxy stats interface
|
||||
# - Let's Encrypt/Certbot support
|
||||
# - Shared overlay network for services
|
||||
#
|
||||
# REQUIREMENTS (run these first):
|
||||
# ```bash
|
||||
# # Initialize Docker Swarm (if not already initialized)
|
||||
# docker swarm init
|
||||
#
|
||||
# # Create overlay network (idempotent)
|
||||
# docker network ls | grep -q easyhaproxy || docker network create --driver overlay --attachable easyhaproxy
|
||||
#
|
||||
# # Edit this file and change:
|
||||
# # Line 18: EASYHAPROXY_CERTBOT_EMAIL to your email
|
||||
# ```
|
||||
#
|
||||
# HOW TO START:
|
||||
# ```bash
|
||||
# docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
# ```
|
||||
#
|
||||
# HOW TO VERIFY IT'S WORKING:
|
||||
# ```bash
|
||||
# # Check stack is deployed
|
||||
# docker stack ls
|
||||
# # Expected: easyhaproxy stack listed
|
||||
#
|
||||
# # Check service is running
|
||||
# docker service ls
|
||||
# # Expected: easyhaproxy_haproxy with 1/1 replicas
|
||||
#
|
||||
# # View HAProxy stats
|
||||
# # URL: http://localhost:1936
|
||||
# # Username: admin
|
||||
# # Password: password
|
||||
#
|
||||
# # Check logs
|
||||
# docker service logs -f easyhaproxy_haproxy
|
||||
# ```
|
||||
#
|
||||
# CLEAN UP:
|
||||
# ```bash
|
||||
# docker stack rm easyhaproxy
|
||||
# ```
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
|
||||
services:
|
||||
|
|
|
|||
|
|
@ -1,25 +1,65 @@
|
|||
# IP Whitelist Plugin Example for Docker Swarm
|
||||
# ==============================================================================
|
||||
# EXAMPLE: IP Whitelist Plugin (Swarm)
|
||||
# ==============================================================================
|
||||
#
|
||||
# This example demonstrates restricting access to specific IP addresses in Swarm
|
||||
# WHAT THIS DEMONSTRATES:
|
||||
# - Restricting access to specific IP addresses/networks
|
||||
# - IP-based access control for admin panels or sensitive services
|
||||
# - Returning custom status codes for blocked IPs
|
||||
# - Service discovery in Swarm mode with plugins
|
||||
#
|
||||
# Prerequisites:
|
||||
# 1. Docker Swarm initialized:
|
||||
# docker swarm init
|
||||
# REQUIREMENTS (run these first):
|
||||
# ```bash
|
||||
# # Initialize Docker Swarm (if not already initialized)
|
||||
# docker swarm init
|
||||
#
|
||||
# 2. Create overlay network:
|
||||
# docker network create --driver overlay --attachable easyhaproxy
|
||||
# # Create overlay network (idempotent)
|
||||
# docker network ls | grep -q easyhaproxy || docker network create --driver overlay --attachable easyhaproxy
|
||||
#
|
||||
# 3. Update allowed_ips label with your actual IP addresses/networks
|
||||
# # Ensure EasyHAProxy is deployed
|
||||
# docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
#
|
||||
# 4. Deploy the stack:
|
||||
# docker stack deploy -c ip-whitelist.yml admin
|
||||
# # Add to /etc/hosts for local testing (idempotent)
|
||||
# grep -q "admin.example.com" /etc/hosts || echo "127.0.0.1 admin.example.com" | sudo tee -a /etc/hosts
|
||||
#
|
||||
# 5. Test from allowed IP:
|
||||
# curl http://<swarm-ip>/
|
||||
# # Response: Success (200 OK)
|
||||
# # IMPORTANT: Edit this file (ip-whitelist.yml) line 64 to add your actual IP addresses!
|
||||
# # Get your current IP: curl ifconfig.me
|
||||
# ```
|
||||
#
|
||||
# 6. Test from non-allowed IP:
|
||||
# # Response: HTTP 403 Forbidden
|
||||
# HOW TO START:
|
||||
# ```bash
|
||||
# docker stack deploy -c ip-whitelist.yml admin
|
||||
# ```
|
||||
#
|
||||
# HOW TO VERIFY IT'S WORKING:
|
||||
# ```bash
|
||||
# # Check stack is deployed
|
||||
# docker stack ls | grep admin
|
||||
# # Expected: admin stack listed
|
||||
#
|
||||
# # Check service is running
|
||||
# docker service ls | grep admin_admin
|
||||
# # Expected: admin_admin with 3/3 replicas
|
||||
#
|
||||
# # Test from allowed IP (assumes 127.0.0.1 or your IP is in the whitelist)
|
||||
# curl -H "Host: admin.example.com" http://localhost/
|
||||
# # Expected: 200 OK with "Admin Panel - IP Restricted"
|
||||
#
|
||||
# # Test from blocked IP (using a different IP via proxy or VPN)
|
||||
# # Expected: HTTP 403 Forbidden
|
||||
#
|
||||
# # View HAProxy stats to see IP whitelist rules
|
||||
# # URL: http://localhost:1936
|
||||
# # Username: admin
|
||||
# # Password: password
|
||||
# ```
|
||||
#
|
||||
# CLEAN UP:
|
||||
# ```bash
|
||||
# docker stack rm admin
|
||||
# ```
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
version: "3.7"
|
||||
|
||||
|
|
|
|||
|
|
@ -1,35 +1,78 @@
|
|||
# JWT Validator Plugin Example for Docker Swarm
|
||||
# ==============================================================================
|
||||
# EXAMPLE: JWT Validator Plugin (Swarm)
|
||||
# ==============================================================================
|
||||
#
|
||||
# This example demonstrates JWT token validation for API protection in Swarm
|
||||
# WHAT THIS DEMONSTRATES:
|
||||
# - JWT token validation for API authentication
|
||||
# - Using Docker configs to manage JWT public keys
|
||||
# - Validating issuer, audience, and expiration claims
|
||||
# - Service discovery in Swarm mode with plugins
|
||||
#
|
||||
# Prerequisites:
|
||||
# 1. Docker Swarm initialized:
|
||||
# docker swarm init
|
||||
# REQUIREMENTS (run these first):
|
||||
# ```bash
|
||||
# # Initialize Docker Swarm (if not already initialized)
|
||||
# docker swarm init
|
||||
#
|
||||
# 2. Create overlay network:
|
||||
# docker network create --driver overlay --attachable easyhaproxy
|
||||
# # Create overlay network (idempotent)
|
||||
# docker network ls | grep -q easyhaproxy || docker network create --driver overlay --attachable easyhaproxy
|
||||
#
|
||||
# 3. Generate JWT keys and create Docker config:
|
||||
# openssl genrsa -out jwt_private.pem 2048
|
||||
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
|
||||
# docker config create jwt_api_pubkey jwt_pubkey.pem
|
||||
# # Ensure EasyHAProxy is deployed
|
||||
# docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
#
|
||||
# 4. Deploy the stack:
|
||||
# docker stack deploy -c jwt-validator.yml api
|
||||
# # Generate JWT key pair (RS256 algorithm)
|
||||
# openssl genrsa -out jwt_private.pem 2048
|
||||
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
|
||||
#
|
||||
# 5. Test without token (should fail):
|
||||
# curl http://<swarm-ip>/
|
||||
# # Response: Missing Authorization HTTP header
|
||||
# # Create Docker config with public key
|
||||
# docker config create jwt_api_pubkey jwt_pubkey.pem
|
||||
#
|
||||
# 6. Generate test JWT at https://jwt.io with:
|
||||
# - Algorithm: RS256
|
||||
# - Payload: {"iss":"https://auth.example.com/","aud":"https://api.example.com","exp":9999999999}
|
||||
# - Use your jwt_private.pem for signing
|
||||
# # Add to /etc/hosts for local testing (idempotent)
|
||||
# grep -q "api.example.com" /etc/hosts || echo "127.0.0.1 api.example.com" | sudo tee -a /etc/hosts
|
||||
# ```
|
||||
#
|
||||
# 7. Test with token:
|
||||
# TOKEN="eyJhbGc..."
|
||||
# curl -H "Authorization: Bearer $TOKEN" http://<swarm-ip>/
|
||||
# # Response: Success
|
||||
# HOW TO START:
|
||||
# ```bash
|
||||
# docker stack deploy -c jwt-validator.yml api
|
||||
# ```
|
||||
#
|
||||
# HOW TO VERIFY IT'S WORKING:
|
||||
# ```bash
|
||||
# # Check stack is deployed
|
||||
# docker stack ls | grep api
|
||||
# # Expected: api stack listed
|
||||
#
|
||||
# # Check service is running
|
||||
# docker service ls | grep api_api
|
||||
# # Expected: api_api with 5/5 replicas
|
||||
#
|
||||
# # Test without token (should fail)
|
||||
# curl -H "Host: api.example.com" http://localhost/
|
||||
# # Expected: HTTP 401 with "Missing Authorization HTTP header"
|
||||
#
|
||||
# # Generate test JWT at https://jwt.io with:
|
||||
# # - Algorithm: RS256
|
||||
# # - Payload: {"iss":"https://auth.example.com/","aud":"https://api.example.com","exp":9999999999}
|
||||
# # - Use your jwt_private.pem content in "Verify Signature" section
|
||||
#
|
||||
# # Test with valid token (replace TOKEN with your JWT)
|
||||
# TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
# curl -H "Host: api.example.com" -H "Authorization: Bearer $TOKEN" http://localhost/
|
||||
# # Expected: 200 OK with "Protected API - JWT Required"
|
||||
#
|
||||
# # Test with invalid/expired token
|
||||
# curl -H "Host: api.example.com" -H "Authorization: Bearer invalid_token" http://localhost/
|
||||
# # Expected: HTTP 401 with error message
|
||||
# ```
|
||||
#
|
||||
# CLEAN UP:
|
||||
# ```bash
|
||||
# docker stack rm api
|
||||
# # To also remove the JWT public key config and generated keys:
|
||||
# # docker config rm jwt_api_pubkey
|
||||
# # rm jwt_private.pem jwt_pubkey.pem
|
||||
# ```
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
version: "3.7"
|
||||
|
||||
|
|
|
|||
|
|
@ -1,31 +1,93 @@
|
|||
# Multiple Plugins Combined Example for Docker Swarm
|
||||
# ==============================================================================
|
||||
# EXAMPLE: Multiple Plugins Combined (Swarm)
|
||||
# ==============================================================================
|
||||
#
|
||||
# This example demonstrates using multiple plugins together for enhanced security
|
||||
# WHAT THIS DEMONSTRATES:
|
||||
# - Using multiple plugins together for layered security
|
||||
# - Three different security profiles for different service types:
|
||||
# * Public website: Cloudflare IP restoration + path blocking
|
||||
# * Protected API: JWT authentication + path blocking
|
||||
# * Admin panel: Strict IP whitelist
|
||||
# - Complex production-ready security configuration
|
||||
#
|
||||
# Prerequisites:
|
||||
# 1. Docker Swarm initialized:
|
||||
# docker swarm init
|
||||
# REQUIREMENTS (run these first):
|
||||
# ```bash
|
||||
# # Initialize Docker Swarm (if not already initialized)
|
||||
# docker swarm init
|
||||
#
|
||||
# 2. Create overlay network:
|
||||
# docker network create --driver overlay --attachable easyhaproxy
|
||||
# # Create overlay network (idempotent)
|
||||
# docker network ls | grep -q easyhaproxy || docker network create --driver overlay --attachable easyhaproxy
|
||||
#
|
||||
# 3. Generate JWT keys and create Docker config:
|
||||
# openssl genrsa -out jwt_private.pem 2048
|
||||
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
|
||||
# docker config create jwt_api_pubkey jwt_pubkey.pem
|
||||
# # Ensure EasyHAProxy is deployed
|
||||
# docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
#
|
||||
# 4. Download Cloudflare IPs and create Docker config:
|
||||
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
|
||||
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
|
||||
# docker config create cloudflare_ips cloudflare_ips.lst
|
||||
# # Generate JWT key pair (RS256 algorithm)
|
||||
# openssl genrsa -out jwt_private.pem 2048
|
||||
# openssl rsa -in jwt_private.pem -pubout -out jwt_pubkey.pem
|
||||
# docker config create jwt_api_pubkey jwt_pubkey.pem
|
||||
#
|
||||
# 5. Deploy the stack:
|
||||
# docker stack deploy -c plugins-combined.yml production
|
||||
# # Download Cloudflare IP ranges and create Docker config
|
||||
# curl https://www.cloudflare.com/ips-v4 > cloudflare_ips.lst
|
||||
# curl https://www.cloudflare.com/ips-v6 >> cloudflare_ips.lst
|
||||
# docker config create cloudflare_ips cloudflare_ips.lst
|
||||
# rm cloudflare_ips.lst jwt_private.pem jwt_pubkey.pem
|
||||
#
|
||||
# This creates three services with different security profiles:
|
||||
# - Public website: Cloudflare + path blocking
|
||||
# - Protected API: JWT validation + path blocking
|
||||
# - Admin panel: Strict IP whitelist
|
||||
# # Add to /etc/hosts for local testing (idempotent)
|
||||
# grep -q "website.example.com" /etc/hosts || echo "127.0.0.1 website.example.com api.example.com admin.example.com" | sudo tee -a /etc/hosts
|
||||
#
|
||||
# # IMPORTANT: Edit this file (plugins-combined.yml) line 124 to add your actual IP!
|
||||
# ```
|
||||
#
|
||||
# HOW TO START:
|
||||
# ```bash
|
||||
# docker stack deploy -c plugins-combined.yml production
|
||||
# ```
|
||||
#
|
||||
# HOW TO VERIFY IT'S WORKING:
|
||||
# ```bash
|
||||
# # Check stack is deployed
|
||||
# docker stack ls | grep production
|
||||
# # Expected: production stack listed
|
||||
#
|
||||
# # Check all services are running
|
||||
# docker service ls | grep production
|
||||
# # Expected: 3 services (website, api, admin) with all replicas running
|
||||
#
|
||||
# # Test public website (Cloudflare + deny_pages)
|
||||
# curl -H "Host: website.example.com" http://localhost/
|
||||
# # Expected: 200 OK with "Public Website"
|
||||
# curl -H "Host: website.example.com" http://localhost/admin
|
||||
# # Expected: HTTP 404 (blocked by deny_pages)
|
||||
#
|
||||
# # Test protected API (JWT + deny_pages)
|
||||
# curl -H "Host: api.example.com" http://localhost/
|
||||
# # Expected: HTTP 401 with "Missing Authorization HTTP header"
|
||||
#
|
||||
# # Generate JWT at https://jwt.io (see jwt-validator.yml for details)
|
||||
# TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
# curl -H "Host: api.example.com" -H "Authorization: Bearer $TOKEN" http://localhost/
|
||||
# # Expected: 200 OK with "Protected API"
|
||||
# curl -H "Host: api.example.com" -H "Authorization: Bearer $TOKEN" http://localhost/internal
|
||||
# # Expected: HTTP 403 (blocked by deny_pages)
|
||||
#
|
||||
# # Test admin panel (IP whitelist)
|
||||
# curl -H "Host: admin.example.com" http://localhost/
|
||||
# # Expected: 200 OK if your IP is whitelisted, 403 otherwise
|
||||
#
|
||||
# # View HAProxy stats to see all plugin configurations
|
||||
# # URL: http://localhost:1936
|
||||
# # Username: admin
|
||||
# # Password: password
|
||||
# ```
|
||||
#
|
||||
# CLEAN UP:
|
||||
# ```bash
|
||||
# docker stack rm production
|
||||
# # To also remove Docker configs:
|
||||
# # docker config rm cloudflare_ips jwt_api_pubkey
|
||||
# ```
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
version: "3.7"
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,46 @@
|
|||
# To install:
|
||||
# ==============================================================================
|
||||
# EXAMPLE: Portainer Behind EasyHAProxy (Swarm)
|
||||
# ==============================================================================
|
||||
#
|
||||
# WHAT THIS DEMONSTRATES:
|
||||
# - Running Portainer management UI in Swarm mode
|
||||
# - Service discovery with EasyHAProxy
|
||||
# - Using persistent volumes for Portainer data
|
||||
#
|
||||
# REQUIREMENTS (run these first):
|
||||
# ```bash
|
||||
# # Ensure EasyHAProxy is deployed
|
||||
# docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
#
|
||||
# # Add to /etc/hosts (idempotent)
|
||||
# grep -q "portainer.local" /etc/hosts || echo "127.0.0.1 portainer.local" | sudo tee -a /etc/hosts
|
||||
# ```
|
||||
#
|
||||
# HOW TO START:
|
||||
# ```bash
|
||||
# docker stack deploy -c portainer.yml portainer
|
||||
# ```
|
||||
#
|
||||
# HOW TO VERIFY IT'S WORKING:
|
||||
# ```bash
|
||||
# # Check service is running
|
||||
# docker service ls | grep portainer
|
||||
# # Expected: portainer_portainer with 1/1 replicas
|
||||
#
|
||||
# # Access Portainer
|
||||
# curl http://portainer.local
|
||||
# # Or open in browser: http://portainer.local
|
||||
# # First time: Create admin user
|
||||
# ```
|
||||
#
|
||||
# CLEAN UP:
|
||||
# ```bash
|
||||
# docker stack rm portainer
|
||||
# # To also remove data volume:
|
||||
# # docker volume rm portainer_portainer_data
|
||||
# ```
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
services:
|
||||
portainer:
|
||||
|
|
|
|||
|
|
@ -1,22 +1,58 @@
|
|||
# To install:
|
||||
# ==============================================================================
|
||||
# EXAMPLE: Basic Swarm Services with SSL
|
||||
# ==============================================================================
|
||||
#
|
||||
# WHAT THIS DEMONSTRATES:
|
||||
# - Basic Swarm services with SSL configuration
|
||||
# - HTTP to HTTPS redirect
|
||||
# - Two services with different SSL setups (embedded cert vs SSL file)
|
||||
# - Using deploy.labels for service discovery in Swarm
|
||||
#
|
||||
# REQUIREMENTS (run these first):
|
||||
# ```bash
|
||||
# # Ensure EasyHAProxy is deployed
|
||||
# docker stack deploy -c easyhaproxy.yml easyhaproxy
|
||||
#
|
||||
# # Generate SSL certificates
|
||||
# cd ../.. && ./examples/generate-keys.sh && cd examples/swarm
|
||||
#
|
||||
# # Add to /etc/hosts (idempotent)
|
||||
# grep -q "host1.local" /etc/hosts || echo "127.0.0.1 host1.local host2.local" | sudo tee -a /etc/hosts
|
||||
# ```
|
||||
#
|
||||
# HOW TO START:
|
||||
# ```bash
|
||||
# docker stack deploy -c services.yml services
|
||||
# ```
|
||||
#
|
||||
# To test:
|
||||
# HOW TO VERIFY IT'S WORKING:
|
||||
# ```bash
|
||||
# # Check services are running
|
||||
# docker service ls | grep services
|
||||
# # Expected: services_container and services_container2 with 1/1 replicas
|
||||
#
|
||||
# # Test HTTPS for host1.local
|
||||
# curl -k -H "Host: host1.local" https://127.0.0.1/
|
||||
# # Expected: 200 OK with hostname
|
||||
#
|
||||
# # Test HTTPS for host2.local
|
||||
# curl -k -H "Host: host2.local" https://127.0.0.1/
|
||||
#
|
||||
# curl -I -H Host:host1.local http://127.0.0.1
|
||||
# HTTP/1.1 301 Moved Permanently
|
||||
# content-length: 0
|
||||
# location: https://host1.local/
|
||||
# # Expected: 200 OK with hostname
|
||||
#
|
||||
# curl -I -H Host:host2.local http://127.0.0.1
|
||||
# HTTP/1.1 301 Moved Permanently
|
||||
# content-length: 0
|
||||
# location: https://host1.local/
|
||||
# # Test HTTP redirect
|
||||
# curl -I -H "Host: host1.local" http://127.0.0.1
|
||||
# # Expected: HTTP/1.1 301 Moved Permanently, Location: https://host1.local/
|
||||
#
|
||||
# Test SSL:
|
||||
# openssl s_client -showcerts -connect 127.0.0.1:443 -servername host1.local
|
||||
# # Verify SSL certificate
|
||||
# openssl s_client -showcerts -connect 127.0.0.1:443 -servername host1.local < /dev/null
|
||||
# ```
|
||||
#
|
||||
# CLEAN UP:
|
||||
# ```bash
|
||||
# docker stack rm services
|
||||
# ```
|
||||
#
|
||||
# ==============================================================================
|
||||
|
||||
services:
|
||||
container:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue