Initial commit: homelab configuration and documentation
This commit is contained in:
288
docs/guides/traefik_setup_guide.md
Normal file
288
docs/guides/traefik_setup_guide.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# Traefik Setup Guide for Docker Swarm
|
||||
|
||||
This guide provides the step-by-step instructions to correctly configure and deploy Traefik in a Docker Swarm environment, especially when dealing with potentially read-only host filesystems.
|
||||
|
||||
This method uses Docker Configs and Docker Volumes to manage Traefik's configuration and data, which is the standard best practice for Swarm. All commands should be run on your **Docker Swarm manager node**.
|
||||
|
||||
---
|
||||
|
||||
### Step 1: Create the `traefik.yml` Configuration File
|
||||
|
||||
This step creates the Traefik static configuration file. You have two options:
|
||||
|
||||
#### Option A: Using `sudo tee` (Direct Host Write)
|
||||
|
||||
This command uses a `HEREDOC` with `sudo tee` to write the `traefik.yml` file directly to your manager node's filesystem. This is generally straightforward if your manager node's filesystem is writable.
|
||||
|
||||
**Action:**
|
||||
1. **IMPORTANT:** Replace `your-email@example.com` with your actual email address in the command below.
|
||||
2. Copy and paste the entire block into your Zsh terminal on the manager node.
|
||||
|
||||
```zsh
|
||||
# --- Creates the traefik.yml file ---
|
||||
sudo tee ./traefik.yml > /dev/null <<'EOF'
|
||||
global:
|
||||
checkNewVersion: true
|
||||
sendAnonymousUsage: false
|
||||
|
||||
log:
|
||||
level: INFO
|
||||
|
||||
api:
|
||||
dashboard: true
|
||||
insecure: false
|
||||
|
||||
entryPoints:
|
||||
web:
|
||||
address: ":80"
|
||||
http:
|
||||
redirections:
|
||||
entryPoint:
|
||||
to: websecure
|
||||
scheme: https
|
||||
websecure:
|
||||
address: ":443"
|
||||
|
||||
providers:
|
||||
docker:
|
||||
network: traefik-public
|
||||
exposedByDefault: false
|
||||
|
||||
certificatesResolvers:
|
||||
leresolver:
|
||||
acme:
|
||||
email: "your-email@example.com"
|
||||
storage: "/letsencrypt/acme.json"
|
||||
dnsChallenge:
|
||||
provider: duckdns
|
||||
delayBeforeCheck: "120s"
|
||||
EOF
|
||||
```
|
||||
|
||||
#### Option B: Using `docker run` (Via Temporary Container)
|
||||
|
||||
This method creates the `traefik.yml` file *inside* a temporary `busybox` container and then copies it to your manager node's current directory. This is useful if you prefer to avoid direct `sudo tee` or if you're working in an environment where direct file creation is restricted.
|
||||
|
||||
**Action:**
|
||||
1. **IMPORTANT:** Replace `your-email@example.com` with your actual email address in the command below.
|
||||
2. Copy and paste the entire block into your Zsh terminal on the manager node.
|
||||
|
||||
```zsh
|
||||
# --- Creates the traefik.yml file in a temporary container and copies it out ---
|
||||
docker run --rm -i -v "$(pwd):/host" busybox sh -c 'cat > /host/traefik.yml <<\'EOF\'
|
||||
checkNewVersion: true
|
||||
sendAnonymousUsage: false
|
||||
|
||||
log:
|
||||
level: INFO
|
||||
|
||||
api:
|
||||
dashboard: true
|
||||
insecure: false
|
||||
|
||||
entryPoints:
|
||||
web:
|
||||
address: ":80"
|
||||
http:
|
||||
redirections:
|
||||
entryPoint:
|
||||
to: websecure
|
||||
scheme: https
|
||||
websecure:
|
||||
address: ":443"
|
||||
http:
|
||||
tls:
|
||||
certResolver: leresolver
|
||||
|
||||
providers:
|
||||
docker:
|
||||
network: traefik-public
|
||||
exposedByDefault: false
|
||||
|
||||
certificatesResolvers:
|
||||
leresolver:
|
||||
acme:
|
||||
email: "your-email@example.com"
|
||||
storage: "/letsencrypt/acme.json"
|
||||
dnsChallenge:
|
||||
provider: duckdns
|
||||
delayBeforeCheck: 30s
|
||||
resolvers:
|
||||
- "192.168.1.196:53"
|
||||
- "192.168.1.245:53"
|
||||
- "192.168.1.62:53"
|
||||
EOF'
|
||||
```
|
||||
|
||||
> **Note on Versioning:** The `traefik:latest` tag can introduce unexpected breaking changes, as seen here. For production or stable environments, it is highly recommended to pin to a specific version in your stack file, for example: `image: traefik:v2.11` or `image: traefik:v3.0`.
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Create the Docker Swarm Config
|
||||
|
||||
This command ingests the `traefik.yml` file (created in Step 1) into Docker Swarm, making it securely available to services.
|
||||
|
||||
**Action:** Run the following command on your manager node.
|
||||
|
||||
```zsh
|
||||
docker config create traefik.yml ./traefik.yml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Create the Let's Encrypt Volume
|
||||
|
||||
This creates a managed Docker Volume that will persist your TLS certificates.
|
||||
|
||||
**Action:** Run the following command on your manager node.
|
||||
|
||||
```zsh
|
||||
docker volume create traefik_letsencrypt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Prepare the `acme.json` File
|
||||
|
||||
Traefik requires an `acme.json` file to exist with the correct permissions before it can start. This command creates the empty file inside the volume you just made.
|
||||
|
||||
**Action:** Run the following command on your manager node.
|
||||
|
||||
```zsh
|
||||
docker run --rm -v traefik_letsencrypt:/letsencrypt busybox sh -c "touch /letsencrypt/acme.json && chmod 600 /letsencrypt/acme.json"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Update and Deploy the `networking-stack.yml`
|
||||
|
||||
You can now deploy your `networking-stack` using the YAML below. It has been modified to use the Swarm config and volume instead of host paths.
|
||||
|
||||
**Action:**
|
||||
1. **IMPORTANT:** Replace `YOUR_DUCKDNS_TOKEN` with your actual DuckDNS token in the `environment` section.
|
||||
2. Upload this YAML content to Portainer to deploy your stack.
|
||||
|
||||
```yaml
|
||||
version: '3.9'
|
||||
|
||||
networks:
|
||||
traefik-public:
|
||||
external: true
|
||||
|
||||
volumes:
|
||||
traefik_letsencrypt:
|
||||
external: true
|
||||
|
||||
configs:
|
||||
traefik_yml:
|
||||
external: true
|
||||
name: traefik.yml
|
||||
|
||||
services:
|
||||
traefik:
|
||||
image: traefik:latest
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- traefik_letsencrypt:/letsencrypt
|
||||
networks:
|
||||
- traefik-public
|
||||
environment:
|
||||
- "DUCKDNS_TOKEN=YOUR_DUCKDNS_TOKEN"
|
||||
configs:
|
||||
- source: traefik_yml
|
||||
target: /traefik.yml
|
||||
deploy:
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.traefik.rule=Host(`traefik.sj98.duckdns.org`)"
|
||||
- "traefik.http.routers.traefik.entrypoints=websecure"
|
||||
- "traefik.http.routers.traefik.tls.certresolver=leresolver"
|
||||
- "traefik.http.routers.traefik.service=api@internal"
|
||||
placement:
|
||||
constraints:
|
||||
- node.role == manager
|
||||
|
||||
whoami:
|
||||
image: traefik/whoami
|
||||
networks:
|
||||
- traefik-public
|
||||
deploy:
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.whoami.rule=Host(`whoami.sj98.duckdns.org`)"
|
||||
- "traefik.http.routers.whoami.entrypoints=websecure"
|
||||
- "traefik.http.routers.whoami.tls.certresolver=leresolver"
|
||||
- "traefik.http.services.whoami.loadbalancer.server.port=80"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Clean Up (Optional)
|
||||
|
||||
Since the configuration is now stored in Docker Swarm, you can remove the local `traefik.yml` file from your manager node's filesystem.
|
||||
|
||||
**Action:** Run the following command on your manager node.
|
||||
|
||||
```zsh
|
||||
rm ./traefik.yml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Troubleshooting and Removal
|
||||
|
||||
If you encounter an error and need to start the setup process over, follow these steps to cleanly remove all the components you created. Run these commands on your **Docker Swarm manager node**.
|
||||
|
||||
#### Step 1: Remove the Stack
|
||||
|
||||
First, remove the deployed stack from your Swarm.
|
||||
|
||||
**Action:**
|
||||
- In Portainer, go to "Stacks", select your `networking-stack`, and click "Remove".
|
||||
|
||||
#### Step 2: Remove the Docker Config
|
||||
|
||||
This removes the Traefik configuration that was stored in the Swarm.
|
||||
|
||||
**Action:**
|
||||
|
||||
```zsh
|
||||
docker config rm traefik.yml
|
||||
```
|
||||
|
||||
#### Step 3: Remove the Docker Volume
|
||||
|
||||
This deletes the volume that was storing your Let's Encrypt certificates. **Warning:** This will delete your existing certificates.
|
||||
|
||||
**Action:**
|
||||
|
||||
```zsh
|
||||
docker volume rm traefik_letsencrypt
|
||||
```
|
||||
|
||||
#### Step 4: Remove the Local Config File (If Present)
|
||||
|
||||
If you didn't delete the `traefik.yml` file in the optional clean-up step, remove it now.
|
||||
|
||||
**Action:**
|
||||
|
||||
```zsh
|
||||
rm ./traefik.yml
|
||||
```
|
||||
|
||||
After completing these steps, your environment will be clean, and you can safely re-run the setup guide from the beginning.
|
||||
|
||||
---
|
||||
|
||||
### Step 7: Verify Traefik Dashboard
|
||||
|
||||
Once your `networking-stack` is deployed and Traefik has started, you can verify its functionality by accessing the Traefik dashboard.
|
||||
|
||||
**Action:**
|
||||
1. Open your web browser and navigate to the Traefik dashboard:
|
||||
- **Traefik Dashboard:** `https://traefik.sj98.duckdns.org`
|
||||
|
||||
You should see the Traefik dashboard, listing your routers and services. If you see a certificate warning, it might take a moment for Let's Encrypt to issue the certificate. If the dashboard loads, Traefik is running correctly.
|
||||
Reference in New Issue
Block a user