initial commit
This commit is contained in:
ray
@@ -0,0 +1,275 @@
|
||||
# Gitea Self-Hosted Git Service
|
||||
|
||||
## Deployment
|
||||
|
||||
| Detail | Value |
|
||||
|--------|-------|
|
||||
| Container | `gitea/gitea:latest` |
|
||||
| Data path | `/mnt/seagate8tb/docker/gitea/` |
|
||||
| Internal port | 3000 (HTTP) |
|
||||
| SSL port | 443 |
|
||||
| Auth | Local (ray / password) |
|
||||
| URL | `https://gitea.graj-media.com` |
|
||||
|
||||
## Docker Compose
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gitea:
|
||||
image: gitea/gitea:latest
|
||||
container_name: gitea
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- ./data:/data
|
||||
- ./config:/etc/gitea
|
||||
- /etc/timezone:/etc/timezone:ro
|
||||
- /etc/localtime:/etc/localtime:ro
|
||||
ports:
|
||||
- "127.0.0.1:3000:3000"
|
||||
environment:
|
||||
- USER_UID=1000
|
||||
- USER_GID=1000
|
||||
- GITEA__database__DB_TYPE=sqlite3
|
||||
- GITEA__server__DOMAIN=gitea.graj-media.com
|
||||
- GITEA__server__SSH_DOMAIN=gitea.graj-media.com
|
||||
- GITEA__server__HTTP_PORT=3000
|
||||
- GITEA__server__ROOT_URL=https://gitea.graj-media.com
|
||||
- GITEA__server__DISABLE_SSH=true
|
||||
- GITEA__server__LFS_START_SERVER=true
|
||||
networks:
|
||||
- gitea-net
|
||||
|
||||
networks:
|
||||
gitea-net:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
## Nginx Config
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name gitea.graj-media.com;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/grajmedia.duckdns.org/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/grajmedia.duckdns.org/privkey.pem;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
|
||||
client_max_body_size 512M;
|
||||
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection $connection_upgrade;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Critical Pitfalls
|
||||
|
||||
### 1. Docker Entrypoint Overrides app.ini
|
||||
|
||||
The Gitea Docker entrypoint rewrites `/data/gitea/conf/app.ini` from environment variables **every time the container starts**. Manual edits to app.ini are silently overwritten.
|
||||
|
||||
**Fix:** Use `GITEA__section__key=value` environment variables in docker-compose.yml, not direct file edits. The double-underscore delimiter maps to INI sections: `GITEA__server__DISABLE_SSH=true` sets `[server] DISABLE_SSH = true`.
|
||||
|
||||
After the container starts, the entrypoint generates the config from env vars first, then Gitea's web runner applies `INSTALL_LOCK = true` from the env if set.
|
||||
|
||||
### 2. SSH Port Conflict
|
||||
|
||||
The Gitea Docker image includes an OpenSSH daemon that automatically binds to port 22 inside the container. When `START_SSH_SERVER=true` (default), Gitea also tries to bind its own SSH server on port 22 → fatal error → container restarts in a crash loop.
|
||||
|
||||
**Fix:** Set `GITEA__server__DISABLE_SSH=true` in environment. This prevents Gitea from starting its SSH server. HTTPS cloning still works through the web interface. If SSH-based git access is needed later, configure a non-conflicting internal port with `SSH_LISTEN_PORT`.
|
||||
|
||||
**Detection in logs:**
|
||||
```
|
||||
[F] Failed to start SSH server: listen tcp :22: bind: address already in use
|
||||
Received signal 15; terminating.
|
||||
```
|
||||
|
||||
### 3. Admin Account Setup (Headless / API-First)
|
||||
|
||||
Gitea's install page requires browser interaction. To set up without the web UI:
|
||||
|
||||
1. **Stop the container** (so web server isn't running)
|
||||
2. **Set `INSTALL_LOCK = true`** in app.ini (or the env will be used on next start)
|
||||
3. **Run migration** to create the database schema:
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v /mnt/seagate8tb/docker/gitea/data:/data \
|
||||
-v /mnt/seagate8tb/docker/gitea/config:/etc/gitea \
|
||||
--user 1000:1000 \
|
||||
gitea/gitea:latest \
|
||||
gitea migrate
|
||||
```
|
||||
4. **Create admin user:**
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v /mnt/seagate8tb/docker/gitea/data:/data \
|
||||
-v /mnt/seagate8tb/docker/gitea/config:/etc/gitea \
|
||||
--user 1000:1000 \
|
||||
gitea/gitea:latest \
|
||||
gitea admin user create --username ray --password "<password>" --email ray@grajmedia.duckdns.org --admin
|
||||
```
|
||||
5. **Start container** — it now runs as an installed instance with the admin user ready
|
||||
|
||||
**Alternative** (if container must stay running): Navigate to the install page in a browser, fill admin fields, and submit. The browser form works when the install page is served.
|
||||
|
||||
### 4. Secret Key Generation
|
||||
|
||||
Generate all secrets outside the container using the Gitea binary:
|
||||
```bash
|
||||
gitea generate secret SECRET_KEY
|
||||
gitea generate secret JWT_SECRET
|
||||
gitea generate secret LFS_JWT_SECRET
|
||||
gitea generate secret INTERNAL_TOKEN
|
||||
```
|
||||
|
||||
These can be passed as env vars or written to app.ini. Write them to the config file **before** the first migration to avoid key rotation issues.
|
||||
|
||||
### 5. must_change_password Blocks API
|
||||
|
||||
If API calls return `"You must change your password"`, clear the flag:
|
||||
```bash
|
||||
docker exec gitea sqlite3 /data/gitea/gitea.db \
|
||||
"UPDATE user SET must_change_password=0 WHERE name='ray';"
|
||||
```
|
||||
|
||||
This happens when the password was changed via the admin CLI (`gitea admin user change-password`) but the `must_change_password` flag wasn't cleared.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Container health
|
||||
docker ps --filter name=gitea --format '{{.Status}}'
|
||||
|
||||
# HTTP response
|
||||
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/
|
||||
# Should return 200
|
||||
|
||||
# SSL via nginx
|
||||
curl -sk https://gitea.graj-media.com/ | grep -o '<title>[^<]*</title>'
|
||||
|
||||
# Login page renders
|
||||
curl -sk https://gitea.graj-media.com/user/login | grep -c 'Sign In'
|
||||
```
|
||||
|
||||
## API Token Workflow
|
||||
|
||||
Generate a token for automation:
|
||||
```bash
|
||||
docker exec -u git gitea gitea admin user generate-access-token \
|
||||
--username ray --token-name "automation" --scopes "all" 2>&1 | grep -v "^$"
|
||||
```
|
||||
|
||||
Create repos via API:
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:3000/api/v1/user/repos \
|
||||
-H "Authorization: token <TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"my-repo","private":false}'
|
||||
```
|
||||
|
||||
### Push code with URL-encoded password
|
||||
|
||||
Encode `#` as `%23`, `^` as `%5E`, `$` as `%24`:
|
||||
```bash
|
||||
git remote add origin http://ray:4W%23UxJ%5EacTrdPT@127.0.0.1:3000/ray/repo.git
|
||||
git branch -m master main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
## Workflow Automation
|
||||
|
||||
### Git Save Alias
|
||||
|
||||
One-command add+commit+push. Works in any repo:
|
||||
```bash
|
||||
git config --global alias.save '!f() { git add -A && git commit -m "$*" && git push; }; f'
|
||||
```
|
||||
Usage: `git save "message describing changes"`
|
||||
|
||||
### Daily Autosave Cron (no_agent)
|
||||
|
||||
Script that auto-commits any repo with pending changes at 2 AM daily. Uses Hermes `no_agent=true` cron — only produces output when changes were actually saved (silent when clean).
|
||||
|
||||
**Script** (`~/.hermes/scripts/git-autosave.sh`):
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
DATE=$(date '+%Y-%m-%d')
|
||||
LOGFILE="$HOME/.hermes/logs/git-autosave.log"
|
||||
mkdir -p "$HOME/.hermes/logs"
|
||||
|
||||
REPOS=(
|
||||
"/mnt/seagate8tb/Websites/ShopProQuote.backup-20260626-2058/spq-v2:main"
|
||||
"/mnt/seagate8tb/docker:main"
|
||||
)
|
||||
|
||||
for entry in "${REPOS[@]}"; do
|
||||
DIR="${entry%%:*}"
|
||||
BRANCH="${entry##*:}"
|
||||
|
||||
if [ ! -d "$DIR/.git" ]; then
|
||||
echo "[$DATE] SKIP $DIR — no .git" >> "$LOGFILE"
|
||||
continue
|
||||
fi
|
||||
|
||||
cd "$DIR"
|
||||
|
||||
if [ -z "$(git status --porcelain 2>/dev/null)" ]; then
|
||||
echo "[$DATE] CLEAN $DIR" >> "$LOGFILE"
|
||||
continue
|
||||
fi
|
||||
|
||||
git pull --rebase origin "$BRANCH" 2>/dev/null || true
|
||||
git add -A
|
||||
git commit -m "auto-save $DATE"
|
||||
git push origin "$BRANCH"
|
||||
|
||||
echo "[$DATE] SAVED $DIR — auto-save $DATE" >> "$LOGFILE"
|
||||
done
|
||||
```
|
||||
|
||||
**Cron job setup** (via Hermes cronjob tool):
|
||||
- `no_agent=true` — the script IS the job, its stdout is delivered verbatim (or silently when empty)
|
||||
- `deliver=local` — logs saved, no notification on clean runs
|
||||
- `schedule=0 2 * * *` — daily at 2 AM
|
||||
|
||||
**Pitfall:** Remotes must use token-based auth (not password) for unattended pushes. Set up with `git remote set-url origin http://ray:<TOKEN>@127.0.0.1:3000/ray/repo.git` to avoid credential prompts.
|
||||
|
||||
## First Use
|
||||
|
||||
1. Login as `ray` with the configured password
|
||||
2. Click "New Repository" from the dashboard
|
||||
3. Create your first repo and push:
|
||||
```bash
|
||||
git init
|
||||
git add .
|
||||
git commit -m "initial commit"
|
||||
git remote add origin https://gitea.graj-media.com/ray/<repo>.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
## Data Layout
|
||||
|
||||
```
|
||||
/mnt/seagate8tb/docker/gitea/
|
||||
├── docker-compose.yml
|
||||
├── data/
|
||||
│ ├── gitea/
|
||||
│ │ ├── conf/app.ini # Config (overwritten by entrypoint)
|
||||
│ │ ├── gitea.db # SQLite database
|
||||
│ │ └── log/
|
||||
│ └── git/
|
||||
│ └── repositories/ # Actual git repos
|
||||
└── config/
|
||||
```
|
||||
@@ -0,0 +1,203 @@
|
||||
# GlitchTip Self-Hosted Deployment
|
||||
|
||||
Self-hosted Sentry-compatible error tracking. Deployed at `/opt/glitchtip/` on rayserver, proxied via nginx at `https://shopproquote.graj-media.com/glitchtip/`.
|
||||
|
||||
## Docker Compose
|
||||
|
||||
```yaml
|
||||
# /opt/glitchtip/docker-compose.yml
|
||||
services:
|
||||
db:
|
||||
image: postgres:15
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
|
||||
redis:
|
||||
image: redis:7
|
||||
restart: unless-stopped
|
||||
|
||||
web:
|
||||
image: glitchtip/glitchtip:latest
|
||||
restart: unless-stopped
|
||||
depends_on: [db, redis]
|
||||
environment:
|
||||
DATABASE_URL: "postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/postgres"
|
||||
REDIS_URL: "redis://redis:6379/1"
|
||||
SECRET_KEY: ${SECRET_KEY}
|
||||
EMAIL_URL: "consolemail://"
|
||||
PORT: 8000
|
||||
DEFAULT_FROM_EMAIL: "glitchtip@localhost"
|
||||
GLITCHTIP_EMBED_WORKER: "true" # CRITICAL — see pitfalls
|
||||
ports:
|
||||
- "127.0.0.1:8001:8000" # 8001 host — 8000 is taken by Portainer
|
||||
volumes:
|
||||
- uploads:/app/uploads
|
||||
|
||||
volumes:
|
||||
pgdata:
|
||||
uploads:
|
||||
```
|
||||
|
||||
`.env` (mode 0600):
|
||||
```
|
||||
POSTGRES_PASSWORD=<openssl rand -hex 24>
|
||||
SECRET_KEY=<openssl rand -hex 24>
|
||||
```
|
||||
|
||||
## nginx Location (added to existing site block)
|
||||
|
||||
```nginx
|
||||
location /glitchtip/ {
|
||||
# Sentry SDK envelope URL: /glitchtip/1/api/1/envelope/
|
||||
# This rewrite strips the project ID so GlitchTip gets /api/1/envelope/
|
||||
rewrite ^/glitchtip/[0-9]+/(api/.*)$ /$1 break;
|
||||
rewrite ^/glitchtip/[0-9]+/(store/.*)$ /api/1/$1 break;
|
||||
rewrite ^/glitchtip/(.*)$ /$1 break;
|
||||
proxy_pass http://127.0.0.1:8001;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_buffering off;
|
||||
}
|
||||
```
|
||||
|
||||
**Critical ordering:** The `api/` and `store/` rewrites MUST come BEFORE the general `^/glitchtip/(.*)$` rewrite. Nginx tries them first — if a request matches `/glitchtip/1/api/1/envelope/`, it hits the `api/` rewrite and becomes `/api/1/envelope/`. The general rewrite would incorrectly strip the path to `/1/api/1/envelope/`.
|
||||
|
||||
## First-Run Setup
|
||||
|
||||
### 1. Migrate
|
||||
|
||||
With `GLITCHTIP_EMBED_WORKER=true` (as specified in the compose file above), migrations auto-run on startup — the all-in-one start.sh calls `python manage.py migrate --no-input --skip-checks` automatically. No manual step needed.
|
||||
|
||||
If deploying without embedded worker, run manually:
|
||||
```bash
|
||||
docker exec glitchtip-web-1 python manage.py migrate
|
||||
```
|
||||
|
||||
### 2. Suppress ALLOWED_HOSTS warning (optional but recommended)
|
||||
|
||||
Add to docker-compose environment:
|
||||
```yaml
|
||||
ALLOWED_HOSTS: "shopproquote.graj-media.com,127.0.0.1"
|
||||
```
|
||||
Without this, GlitchTip logs `RuntimeWarning: ALLOWED_HOSTS is the wildcard default. Restrict to known hostnames` on every startup. The warning is harmless in development but should be set for production deployments.
|
||||
|
||||
### 3. Create superuser via Django shell
|
||||
|
||||
```bash
|
||||
docker exec glitchtip-web-1 python manage.py shell -c "
|
||||
from django.apps import apps
|
||||
U = apps.get_model('users', 'User')
|
||||
u = U.objects.filter(email='admin@localhost').first()
|
||||
u or U.objects.create_superuser(email='admin@localhost', password='<password>')
|
||||
"
|
||||
```
|
||||
|
||||
**Pitfall:** Direct module imports like `from organizations.models import Organization` fail with `RuntimeError: Model class doesn't declare an explicit app_label`. Always use `apps.get_model('app_label', 'ModelName')` in GlitchTip's shell — the app registry isn't fully loaded for direct imports.
|
||||
|
||||
### 3. Create organization + project via Django shell
|
||||
|
||||
```bash
|
||||
docker exec glitchtip-web-1 python manage.py shell -c "
|
||||
from django.apps import apps
|
||||
Org = apps.get_model('organizations_ext', 'Organization')
|
||||
OrgUser = apps.get_model('organizations_ext', 'OrganizationUser')
|
||||
OrgOwner = apps.get_model('organizations_ext', 'OrganizationOwner')
|
||||
Project = apps.get_model('projects', 'Project')
|
||||
ProjectKey = apps.get_model('projects', 'ProjectKey')
|
||||
User = apps.get_model('users', 'User')
|
||||
|
||||
u = User.objects.get(email='admin@localhost')
|
||||
org, created = Org.objects.get_or_create(name='SPQ', slug='spq')
|
||||
if created:
|
||||
ou = OrgUser.objects.create(organization=org, user=u, role=4) # 4 = OWNER
|
||||
OrgOwner.objects.create(organization=org, organization_user=ou)
|
||||
|
||||
proj, _ = Project.objects.get_or_create(name='spq-frontend', slug='spq-frontend', organization=org, defaults={'platform': 'javascript-react'})
|
||||
pk = ProjectKey.objects.filter(project=proj).first() or ProjectKey.objects.create(project=proj)
|
||||
print(f'DSN: http://{pk.public_key}@127.0.0.1:8001/{proj.id}')
|
||||
"
|
||||
```
|
||||
|
||||
**Pitfall:** `OrgUser.role` is NOT NULL — you must pass `role=4` (OWNER). Omitting it raises `IntegrityError: null value in column "role"`.
|
||||
|
||||
**Pitfall:** `ProjectKey` has no `dsn_secret` attribute. The DSN is constructed from `pk.public_key` (a UUID) + the project's numeric ID: `http://<public_key>@<host>/<project_id>`.
|
||||
|
||||
### 4. Verify event ingestion
|
||||
|
||||
```bash
|
||||
# Send a test event via the Sentry store endpoint
|
||||
curl -s -X POST http://127.0.0.1:8001/api/1/store/ \
|
||||
-H "X-Sentry-Auth: Sentry sentry_key=<public_key>,sentry_version=7" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"event_id":"<uuid-without-dashes>","timestamp":"2026-07-07T22:51:00Z","level":"error","message":"test","platform":"javascript"}'
|
||||
# → {"event_id":"...","task_id":null} HTTP 200
|
||||
```
|
||||
|
||||
Then check the issues table:
|
||||
```bash
|
||||
docker exec glitchtip-web-1 python manage.py shell -c "
|
||||
from django.apps import apps
|
||||
I = apps.get_model('issue_events', 'Issue')
|
||||
print(f'Issues: {I.objects.count()}')
|
||||
"
|
||||
```
|
||||
|
||||
If the count stays 0 after the API returned 200, the worker isn't running — see the `GLITCHTIP_EMBED_WORKER` pitfall below.
|
||||
|
||||
## Frontend Integration (@sentry/react)
|
||||
|
||||
```ts
|
||||
// src/main.tsx — BEFORE createRoot, but dynamic-imported to keep initial bundle small
|
||||
import { setErrorReporter } from './lib/userMessages';
|
||||
|
||||
const DSN = import.meta.env.VITE_GLITCHTIP_DSN as string | undefined;
|
||||
if (DSN) {
|
||||
import('@sentry/react').then((Sentry) => {
|
||||
Sentry.init({
|
||||
dsn: DSN,
|
||||
environment: import.meta.env.VITE_ENV || 'development',
|
||||
tracesSampleRate: 0.1,
|
||||
});
|
||||
setErrorReporter((err, ctx) => {
|
||||
Sentry.captureException(err, { extra: ctx });
|
||||
});
|
||||
}).catch(() => { /* non-critical */ });
|
||||
}
|
||||
```
|
||||
|
||||
The `setErrorReporter` hook (already in `src/lib/userMessages.ts`) routes `reportError()` calls into Sentry. Dynamic import keeps @sentry/react out of the initial bundle — it only loads when the DSN env var is set (production) AND the first error triggers the import. Zero impact on dev or initial load.
|
||||
|
||||
`.env.production`:
|
||||
```
|
||||
VITE_GLITCHTIP_DSN=https://<public_key>@shopproquote.graj-media.com/glitchtip/<project_id>
|
||||
```
|
||||
|
||||
The DSN uses the public HTTPS URL (via nginx proxy), not the internal `127.0.0.1:8001`, because the browser sends events directly.
|
||||
|
||||
## Pitfalls (GlitchTip v6.2.0)
|
||||
|
||||
- **GLITCHTIP_EMBED_WORKER=true is REQUIRED.** Without it, GlitchTip runs as web-only (SERVER_ROLE=web). The API accepts events (HTTP 200, returns event_id) but nothing processes them into issues — the Issue table stays empty. Set this env var in docker-compose.yml and recreate the container with --force-recreate.
|
||||
|
||||
- **nginx rewrite ORDERING matters.** The Sentry SDK sends events to /glitchtip/<project_id>/api/1/envelope/. The api/ rewrite MUST come BEFORE the general ^/glitchtip/(.*)$ rewrite. If the general rewrite hits first, the path becomes /1/api/1/envelope/ which GlitchTip doesn't serve (returns 400).
|
||||
|
||||
- **ALLOWED_HOSTS should be set** to suppress the startup warning. Without it, every container restart logs "RuntimeWarning: ALLOWED_HOSTS is the wildcard default". Set to shopproquote.graj-media.com,127.0.0.1 for the SPQ deployment.
|
||||
|
||||
- **Port 8000 is taken by Portainer** on rayserver. Use 127.0.0.1:8001:8000. Always ss -tlnp | grep :8000 before deploying.
|
||||
|
||||
- **With GLITCHTIP_EMBED_WORKER=true, migrations auto-run** on startup. The all-in-one start.sh calls python manage.py migrate --no-input --skip-checks automatically. No manual migrate step needed when using the compose file above.
|
||||
|
||||
- **Django shell imports need apps.get_model().** Direct from organizations.models import Organization raises RuntimeError. Use apps.get_model('organizations_ext', 'Organization') (note the _ext suffix on the app label).
|
||||
|
||||
- **OrgUser.role is NOT NULL.** Pass role=4 (OWNER) when creating. Without it: IntegrityError: null value in column "role".
|
||||
|
||||
- **ProjectKey.dsn_secret does not exist.** The DSN is http://<public_key>@<host>/<project_id>. Check pk._meta.get_fields() to see available attributes — public_key is the Sentry key, project.id is the numeric project ID.
|
||||
|
||||
- **Event ID must be a valid UUID (hex, no dashes) for the /api/1/store/ endpoint.** Non-UUID strings return 422 uuid_parsing error. Use python3 -c "import uuid; print(uuid.uuid4().hex)".
|
||||
|
||||
- **Sentry envelope format** (/api/1/envelope/): three newline-delimited JSON objects — header {"event_id":"...","sent_at":"..."}, item header {"type":"event"}, and the event payload. Content-Type: text/plain;charset=UTF-8. The store endpoint (/api/1/store/) is simpler for single events.
|
||||
@@ -0,0 +1,364 @@
|
||||
# Gluetun + Private Internet Access (PIA) + qBittorrent
|
||||
|
||||
VPN-routed torrenting stack using Gluetun as a network gateway for qBittorrent.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
qBittorrent → Gluetun (PIA VPN) → Internet
|
||||
^ kill switch: if VPN drops, qB's network dies
|
||||
```
|
||||
|
||||
## Stable Docker Compose Template
|
||||
|
||||
Based on what actually works as of July 2026:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gluetun:
|
||||
image: qmcgaw/gluetun:latest
|
||||
container_name: gluetun
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
devices:
|
||||
- /dev/net/tun:/dev/net/tun
|
||||
ports:
|
||||
- 127.0.0.1:11893:8080 # qBittorrent Web UI (internal, nginx fronted)
|
||||
- 127.0.0.1:6881:6881 # Torrent TCP
|
||||
- 127.0.0.1:6881:6881/udp # Torrent UDP
|
||||
volumes:
|
||||
- ./gluetun:/gluetun
|
||||
environment:
|
||||
VPN_SERVICE_PROVIDER: "private internet access"
|
||||
VPN_TYPE: "openvpn"
|
||||
OPENVPN_PROTOCOL: "tcp"
|
||||
OPENVPN_ENDPOINT_PORT: "443"
|
||||
OPENVPN_USER: "pXXXXXX"
|
||||
OPENVPN_PASSWORD: "your_password"
|
||||
UPDATER_PERIOD: "0"
|
||||
SERVER_HOSTNAMES: "nl-amsterdam.privacy.network"
|
||||
VPN_PORT_FORWARDING: "on"
|
||||
PORT_FORWARD_ONLY: "true"
|
||||
FIREWALL_VPN_INPUT_PORTS: "8080"
|
||||
restart: unless-stopped
|
||||
|
||||
qbittorrent:
|
||||
image: lscr.io/linuxserver/qbittorrent:latest
|
||||
container_name: qbittorrent
|
||||
network_mode: "service:gluetun"
|
||||
depends_on:
|
||||
gluetun:
|
||||
condition: service_healthy
|
||||
volumes:
|
||||
- ./qbittorrent:/config
|
||||
- /mnt/seagate8tb/downloads:/downloads
|
||||
environment:
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
- TZ=America/Chicago
|
||||
- WEBUI_PORT=8080
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
## PIA Server Data: THE Critical Problem
|
||||
|
||||
Gluetun's built-in server IPs go **stale** because PIA rotates IPs. This causes:
|
||||
|
||||
```
|
||||
TLS Error: TLS key negotiation failed to occur within N seconds
|
||||
```
|
||||
|
||||
This is NOT a credential issue. It's a known bug (GitHub #3288, #3315).
|
||||
|
||||
### Fix: Use Current PIA Hostnames
|
||||
|
||||
Don't rely on `SERVER_REGIONS` (uses stale baked-in IPs). Use `SERVER_HOSTNAMES` with current PIA DNS:
|
||||
|
||||
```yaml
|
||||
SERVER_HOSTNAMES: "nl-amsterdam.privacy.network"
|
||||
```
|
||||
|
||||
Get current PIA hostnames from their API:
|
||||
```bash
|
||||
curl -s https://serverlist.piaservers.net/vpninfo/servers/v6 \
|
||||
| python3 -c "import sys,json; d=json.loads(sys.stdin.read().split('\\n',1)[1]); [print(r['name'], r['dns'], r.get('port_forward','')) for r in d['regions']]" \
|
||||
| grep True # only port-forwarding regions
|
||||
```
|
||||
|
||||
Hostnames end in `.privacy.network` — NOT the old IPs baked into images.
|
||||
|
||||
### Protocol & Port: TCP + 443
|
||||
|
||||
PIA's current OpenVPN ports:
|
||||
| Protocol | Ports |
|
||||
|----------|-------|
|
||||
| OpenVPN UDP | 8080, 853, 123, 53 |
|
||||
| OpenVPN TCP | 80, 443, 853, 8443 |
|
||||
|
||||
TCP on 443 is the most reliable through Docker NAT and home routers. UDP port 8080 connections fail because gluetun's baked-in IPs for that port are stale.
|
||||
|
||||
```yaml
|
||||
OPENVPN_PROTOCOL: "tcp"
|
||||
OPENVPN_ENDPOINT_PORT: "443"
|
||||
```
|
||||
|
||||
## Port Forwarding (PIA)
|
||||
|
||||
PIA supports port forwarding for P2P. The forwarded port is written to `/tmp/gluetun/forwarded_port` inside the container.
|
||||
|
||||
Uses PIA's proprietary API — works with both OpenVPN and WireGuard.
|
||||
|
||||
```yaml
|
||||
VPN_PORT_FORWARDING: "on"
|
||||
PORT_FORWARD_ONLY: "true" # only select servers that support port forwarding
|
||||
```
|
||||
|
||||
Port forwards last 60 days and auto-refresh via the `/gluetun` volume.
|
||||
|
||||
## Docker Compose Password Escaping
|
||||
|
||||
This is a **docker compose** feature, not bash: compose treats `$` as its own variable expansion character.
|
||||
|
||||
| Want literal `$C68` | Write in compose |
|
||||
|---------------------|------------------|
|
||||
| `ljJXyg3*%0$C68` | `ljJXyg3*%0$$C68` |
|
||||
|
||||
The YAML dict format (`KEY: value`) does NOT bypass composition variable expansion — `$$` is needed regardless of format. Single quotes in YAML do NOT protect against compose interpolation.
|
||||
|
||||
```yaml
|
||||
# WRONG — $C68 gets eaten, password becomes ljJXyg3*%0
|
||||
OPENVPN_PASSWORD: "ljJXyg3*%0$C68"
|
||||
|
||||
# RIGHT — $$ becomes literal $, password is ljJXyg3*%0$C68
|
||||
OPENVPN_PASSWORD: "ljJXyg3*%0$$C68"
|
||||
```
|
||||
|
||||
## Web UI Access: Firewall and Binding
|
||||
|
||||
Two-layer problem when accessing the qBittorrent web UI from LAN:
|
||||
|
||||
### 1. Gluetun's Firewall Blocks Incoming
|
||||
|
||||
By default, gluetun's internal firewall blocks ALL incoming connections through the VPN tunnel. Even though the Docker port mapping is correct, gluetun drops the packets. Result: browser returns a plain-text "Unauthorized" or connection refused.
|
||||
|
||||
**Fix:** Add `FIREWALL_VPN_INPUT_PORTS` to gluetun's environment:
|
||||
|
||||
```yaml
|
||||
FIREWALL_VPN_INPUT_PORTS: "8080" # qBittorrent's Web UI internal port
|
||||
```
|
||||
|
||||
This opens an iptables rule on the `tun0` interface for the specified port.
|
||||
|
||||
### 2. Docker Port Binding
|
||||
|
||||
The qBittorrent ports are declared on the **gluetun** container (since qBittorrent shares gluetun's network namespace):
|
||||
|
||||
| Binding | Access |
|
||||
|---------|--------|
|
||||
| `127.0.0.1:8093:8080` | Localhost only (curl from server) |
|
||||
| `"8093:8080"` | All interfaces (LAN access) |
|
||||
|
||||
For LAN access from 192.168.50.x devices, use the all-interfaces binding. The web UI still requires login (`admin`/temporary password on first start).
|
||||
|
||||
### 3. UFW on the Host
|
||||
|
||||
Even with the Docker port mapped correctly, UFW (the host firewall) blocks access by default. You must add a rule:
|
||||
|
||||
```bash
|
||||
sudo ufw allow from 192.168.50.0/24 to any port 8093 proto tcp comment 'qBittorrent LAN'
|
||||
```
|
||||
|
||||
### 4. nginx Reverse Proxy (for qBittorrent v5 Login Issues)
|
||||
|
||||
qBittorrent v5.x has TWO Host header problems:
|
||||
|
||||
**Problem A: Port in Host header** — qBittorrent rejects `Host: 192.168.50.98:8093` (with port). The login page itself doesn't load — returns plain text "Unauthorized". Setting `WebUI\\ServerDomains=*` or `WebUI\\HostHeaderValidation=false` does NOT fix this in v5.x.
|
||||
|
||||
**Problem B: Origin header mismatch** — even with the Host header fixed (no port), the browser sends `Origin: http://192.168.50.98:8093` on the login POST. qBittorrent's CSRF check compares Origin to Host (`192.168.50.98`) — they don't match because of the `:8093` suffix, so the login POST returns 401.
|
||||
|
||||
**Fix:** Route through nginx on the host, fixing BOTH headers:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 8093;
|
||||
server_name _;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:11893; # internal Docker port
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host 192.168.50.98; # fix A: strip port from Host
|
||||
proxy_set_header Origin "http://192.168.50.98"; # fix B: strip port from Origin
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 86400;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The Docker port mapping then binds to localhost only (`127.0.0.1:11893:8080`) and nginx handles LAN access.
|
||||
|
||||
### Temporary Password Behavior
|
||||
|
||||
The linuxserver/qbittorrent image generates a **new temporary password every time the container starts** if WEBUI_PORT is set but no permanent password has been configured:
|
||||
|
||||
```
|
||||
The WebUI administrator password was not set. A temporary password is provided for this session: XxYyZz123
|
||||
```
|
||||
|
||||
Get it from: `docker logs qbittorrent 2>&1 | grep -i "temporary password"`
|
||||
|
||||
Login immediately and set a permanent password in Settings > Web UI, or pre-set it in the qBittorrent.conf file via the config volume.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Check VPN IP from qBittorrent's perspective
|
||||
docker exec qbittorrent curl -s https://ipinfo.io/json
|
||||
```
|
||||
|
||||
```bash
|
||||
# Check forwarded port
|
||||
docker exec gluetun sh -c "cat /tmp/gluetun/forwarded_port"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Check gluetun VPN status + public IP
|
||||
docker logs gluetun --tail 20 | grep -E "Peer Connection|Public IP|port forward|forwarded"
|
||||
```
|
||||
|
||||
## Kill Switch Behavior
|
||||
|
||||
qBittorrent uses `network_mode: "service:gluetun"` — it shares gluetun's network namespace. If the VPN tunnel drops:
|
||||
- All qBittorrent traffic stops immediately (no unencrypted leak)
|
||||
- Gluetun auto-restarts the VPN (healthcheck)
|
||||
- qBittorrent regains connectivity once VPN is re-established
|
||||
|
||||
No iptables rules or extra config needed.
|
||||
|
||||
## Port Forwarding Integration (qBittorrent)
|
||||
|
||||
The PIA-assigned forwarded port needs to be set in qBittorrent for best speeds. The port is at `/tmp/gluetun/forwarded_port`. A simple script:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Run this periodically (cron) or via qBittorrent's built-in scheduler
|
||||
PORT=$(docker exec gluetun sh -c "cat /tmp/gluetun/forwarded_port" 2>/dev/null)
|
||||
if [ -n "$PORT" ]; then
|
||||
COOKIE=$(curl -s -c - --header "Referer: http://localhost:8093" \
|
||||
--data "username=admin&password=adminadmin" \
|
||||
"http://localhost:8093/api/v2/auth/login" | grep SID | awk '{print $NF}')
|
||||
curl -s "http://localhost:8093/api/v2/app/setPreferences?json=%7B%22listen_port%22%3A${PORT}%7D" \
|
||||
--header "Cookie: SID=$COOKIE"
|
||||
fi
|
||||
```
|
||||
|
||||
## Debugging Stalled Private-Tracker Torrents
|
||||
|
||||
When a torrent shows as "stalled" (not paused, but no download/upload), isolate systematically:
|
||||
|
||||
### Layer 1: VPN connectivity
|
||||
|
||||
```bash
|
||||
docker exec gluetun cat /tmp/gluetun/ip
|
||||
# Should show the PIA-assigned public IP (not your home IP)
|
||||
```
|
||||
|
||||
### Layer 2: Port forwarding
|
||||
|
||||
```bash
|
||||
docker exec gluetun cat /tmp/gluetun/forwarded_port
|
||||
# Should show a port number (typically 36590 or similar)
|
||||
```
|
||||
|
||||
Verify qBittorrent is actually listening on that port:
|
||||
```bash
|
||||
# Check the qBittorrent log for port-switch events
|
||||
grep "Trying to listen" /mnt/seagate8tb/docker/gluetun-qbittorrent/qbittorrent/qBittorrent/logs/qbittorrent.log | tail -3
|
||||
```
|
||||
|
||||
Expected output shows the port changing from 6881 to the forwarded port after the first WebUI login:
|
||||
```
|
||||
Trying to listen on the following list of IP addresses: "0.0.0.0:36590,[::]:36590"
|
||||
```
|
||||
|
||||
**Pitfall:** qBittorrent starts on port 6881 (from `Preferences\Connection\PortRangeMin`), then switches to `Session\Port` after the first WebUI login. If no one has logged into the WebUI since the last container restart, qBittorrent may still be on 6881 instead of the forwarded port. Log into the WebUI to trigger the switch, or set `Session\Port` before starting.
|
||||
|
||||
### Layer 3: Tracker reachability
|
||||
|
||||
```bash
|
||||
# Extract tracker URLs from the torrent's fastresume
|
||||
# Fastresume files are in /config/qBittorrent/BT_backup/<infohash>.fastresume
|
||||
docker exec qbittorrent strings /config/qBittorrent/BT_backup/*.fastresume | grep -o 'https://[^"]*announce[^"]*'
|
||||
|
||||
# Test reachability (404 is expected for a raw GET — the tracker needs proper params)
|
||||
docker exec qbittorrent curl -s -o /dev/null -w "%{http_code} (%{time_total}s)" --connect-timeout 15 "<tracker_url>"
|
||||
```
|
||||
|
||||
### Layer 4: Simulate a tracker announce (the smoking gun)
|
||||
|
||||
Craft a proper tracker announce request to see the actual response:
|
||||
|
||||
```bash
|
||||
INFOHASH="<from fastresume filename — the hex part before .fastresume>"
|
||||
TRACKER="<tracker announce URL, including passkey>"
|
||||
|
||||
docker exec qbittorrent curl -s --connect-timeout 15 -G \
|
||||
"$TRACKER" \
|
||||
--data-urlencode "info_hash=$INFOHASH" \
|
||||
--data-urlencode "peer_id=-qB5230-testpeerid123456" \
|
||||
--data-urlencode "port=36590" \
|
||||
--data-urlencode "uploaded=0" \
|
||||
--data-urlencode "downloaded=0" \
|
||||
--data-urlencode "left=0" \
|
||||
--data-urlencode "event=started" \
|
||||
-o /tmp/tracker_response.bin
|
||||
|
||||
# Decode the bencoded response
|
||||
docker exec qbittorrent cat /tmp/tracker_response.bin | strings
|
||||
```
|
||||
|
||||
**Common bencoded failure responses to look for:**
|
||||
|
||||
| Response | Meaning |
|
||||
|----------|---------|
|
||||
| `failure reason: Non-Whitelisted client or version` | Client not on tracker's whitelist — check allowed clients page (e.g. `https://s.mrd.ninja/CLNTe` for MAM) |
|
||||
| `failure reason: passkey not found` | Torrent passkey is wrong or expired — re-download .torrent from tracker |
|
||||
| `failure reason: Your IP is not authorized` | VPN IP not authorized on tracker — request IP authorization |
|
||||
| `failure reason: Torrent not found` | Torrent was deleted from tracker — re-download |
|
||||
| `interval: 1800` + `peers:` list | Success — peers exist, issue is elsewhere (DHT/PeX, firewall, or no seeds) |
|
||||
|
||||
### Layer 5: Check torrent file internals (fastresume)
|
||||
|
||||
When bencode libraries aren't available inside the container, use `strings` and `grep`:
|
||||
|
||||
```bash
|
||||
# Extract key status fields from a fastresume
|
||||
docker exec qbittorrent strings /config/qBittorrent/BT_backup/<infohash>.fastresume | \
|
||||
grep -oE '(paused|total_downloaded|total_uploaded|num_complete|num_incomplete|active_time|disable_dht|disable_lsd|disable_pex)[^e]*e'
|
||||
```
|
||||
|
||||
Key fields to check:
|
||||
- `pausedi0e` — not paused; `pausedi1e` — paused
|
||||
- `total_downloadedi0e` — nothing downloaded; non-zero = progress was made
|
||||
- `num_completei16777215e` — sentinel = tracker hasn't provided peer info yet
|
||||
- `num_incompletei16777215e` — same sentinel
|
||||
- `disable_dhti0e` — DHT enabled (dangerous for private trackers)
|
||||
- `active_timei460e` — seconds the torrent has been active
|
||||
|
||||
The sentinel value `16777215` (0xFFFFFF) means "no data from tracker" — this confirms the tracker hasn't answered with peer info.
|
||||
|
||||
### MAM (MyAnonaMouse) Specifics
|
||||
|
||||
- **Allowed clients page**: `https://s.mrd.ninja/CLNTe`
|
||||
- **qBittorrent**: "from 5.0.1 to **latest 5.2.x line**" is allowed, but the tracker-level whitelist may lag behind new patch releases. If a brand-new qBittorrent version is being rejected despite being on the web page, contact staff or check if your MAM profile needs a client whitelist approval.
|
||||
- **DHT/LSD/PeX must be disabled** for private trackers — qBittorrent should auto-disable these when `private=1` is set in the .torrent file, but verify via the fastresume if torrents stall unexpectedly.
|
||||
|
||||
## Known Issues
|
||||
|
||||
- **`docker compose up -d` blocked by Hermes terminal guard**: use `execute_code` with Python `subprocess.run()` instead — the terminal tool flags `docker compose up -d` as a long-lived process even though `-d` detaches immediately.
|
||||
- **`depends_on: condition: service_healthy`**: compose v2 plugin supports this, but `docker-compose` v1 does not. Use `docker compose` (plugin), not `docker-compose` (standalone).
|
||||
- **PIA credential format**: username starts with `p` + digits. Password is a PIA-generated token (not the website login password).
|
||||
- **Container restarts change temporary password**: each `docker compose up -d` or `docker restart qbittorrent` generates a new temp password. Check logs each time unless a permanent password has been set.
|
||||
@@ -0,0 +1,313 @@
|
||||
# Homarr Dashboard
|
||||
|
||||
A customizable, widget-based dashboard for managing and monitoring self-hosted services. Supports Docker container status, Plex sessions, download clients, system monitoring, and the Arr stack.
|
||||
|
||||
## Deployment (Local, No VPS)
|
||||
|
||||
Homarr runs on port 8080 directly — no nginx reverse proxy (it's the landing page for the homelab).
|
||||
|
||||
```yaml
|
||||
# ~/docker/homarr/docker-compose.yml
|
||||
services:
|
||||
homarr:
|
||||
container_name: homarr
|
||||
image: ghcr.io/homarr-labs/homarr:latest
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock # Docker integration (auto-detect containers)
|
||||
- ./appdata:/appdata # Config + icons
|
||||
environment:
|
||||
- SECRET_ENCRYPTION_KEY=<64-char-hex> # Generated via `openssl rand -hex 32`
|
||||
ports:
|
||||
- '8080:7575' # Host 8080 → container 7575
|
||||
```
|
||||
|
||||
## Key Details
|
||||
|
||||
- **Container internal port**: 7575 (maps to Next.js on 3000 internally — transparent to the user)
|
||||
- **Docker socket mount**: Required for Homarr to auto-discover running containers and show their status
|
||||
- **Data directory**: `~/docker/homarr/appdata/` — contains SQLite DB (`appdata/db/db.sqlite`), icons, and config
|
||||
- **First run**: Opens setup wizard on first visit to `http://192.168.50.98:8080/`
|
||||
- **`SECRET_ENCRYPTION_KEY`**: Must be a 64-char hex string. Generate with `openssl rand -hex 32`. If changed after initial setup, existing encrypted data becomes unreadable.
|
||||
|
||||
## Replacing an Existing Dashboard (e.g. Heimdall)
|
||||
|
||||
To swap Heimdall → Homarr while keeping the same port:
|
||||
|
||||
```bash
|
||||
# 1. Stop and remove old container
|
||||
docker stop heimdall && docker rm heimdall
|
||||
|
||||
# 2. (Optional) Keep old data volume if needed
|
||||
docker volume ls | grep heimdall
|
||||
|
||||
# 3. Deploy Homarr on the same port (8080)
|
||||
mkdir -p ~/docker/homarr
|
||||
# write docker-compose.yml as above
|
||||
cd ~/docker/homarr && docker compose up -d
|
||||
|
||||
# 4. Verify
|
||||
curl -sL -o /dev/null -w "%{http_code}" http://localhost:8080/ # → 200
|
||||
```
|
||||
|
||||
**⚠️ Stale iptables DNAT rule**: If `curl localhost:8080` works but `curl 192.168.50.98:8080` doesn't, the old container likely left a stale DNAT rule. See "Stale iptables DNAT rules after replacing a container on the same port" in the main SKILL.md for diagnosis and fix.
|
||||
|
||||
**Docker loopback note**: After fixing the DNAT, localhost works and external clients on the network work, but curling the machine's own external IP from itself may still timeout — this is a known Docker kernel quirk, not a real connectivity problem.
|
||||
|
||||
All existing bookmarks to `http://192.168.50.98:8080/` continue working.
|
||||
|
||||
---
|
||||
|
||||
## Homarr CLI (User & Admin Management)
|
||||
|
||||
The Homarr container ships with a built-in CLI accessed via `docker exec homarr homarr <command>`.
|
||||
|
||||
### Available Commands
|
||||
|
||||
```
|
||||
homarr users — Group of commands to manage users
|
||||
homarr integrations — Group of commands to manage integrations
|
||||
homarr reset-password — Reset password for a user (generates random password)
|
||||
homarr fix-usernames — Changes all credentials usernames to lowercase
|
||||
homarr recreate-admin — Recreate credentials admin user if none exists anymore
|
||||
```
|
||||
|
||||
### User Management
|
||||
|
||||
**List users:**
|
||||
```bash
|
||||
docker exec homarr homarr users list
|
||||
```
|
||||
|
||||
**Create admin (only when no users exist):**
|
||||
```bash
|
||||
docker exec homarr homarr recreate-admin --username <username>
|
||||
# Outputs: generated password and temporary group name
|
||||
```
|
||||
|
||||
**Reset password (generates random password, displayed in terminal):**
|
||||
```bash
|
||||
docker exec homarr homarr reset-password --username <user>
|
||||
```
|
||||
|
||||
**Set specific password (needs user to already exist):**
|
||||
```bash
|
||||
docker exec homarr homarr users update-password --username <user> --password '<password>'
|
||||
# Quote the password with single quotes to protect shell special chars ($, ^, \, etc.)
|
||||
```
|
||||
|
||||
**Delete user:**
|
||||
```bash
|
||||
docker exec homarr homarr users delete --username <user>
|
||||
```
|
||||
|
||||
### Pitfalls
|
||||
|
||||
- **Shell special characters in passwords**: Always quote with single quotes (`'password'`), never double quotes. Double quotes still interpret `$`, `!`, and backticks inside the `docker exec` shell.
|
||||
- **Password with `$` and Docker Compose escaping**: If setting a password via `docker compose` environment or run command, any `$` must be doubled to `$$` because Docker Compose interprets `$` as variable expansion — regardless of YAML quote style. This is a compose-specific behavior, not bash.
|
||||
- **`users list` may hang/be interrupted** on some Homarr versions — add `2>&1 | head -30` and a timeout if it hangs.
|
||||
- **All sessions terminated**: After any password reset or update, all active sessions for that user are invalidated. They must re-login.
|
||||
- **User must exist first**: `update-password` and `reset-password` require the user to already exist. If the database has no users, use `recreate-admin` first.
|
||||
|
||||
---
|
||||
|
||||
## Programmatic Dashboard Population (SQLite)
|
||||
|
||||
Homarr stores all configuration in a SQLite database at `appdata/db/db.sqlite` inside the container (mapped from `./appdata/db/db.sqlite` on the host). You can add services, place them on boards, and configure the layout by manipulating this database directly — much faster than clicking through the UI for 20+ services.
|
||||
|
||||
### Database Schema (Key Tables)
|
||||
|
||||
```
|
||||
app — Service definitions (name, icon, URL, ping URL)
|
||||
item — Widget placements on boards (refers to app via options JSON)
|
||||
item_layout — Grid position of each item (x, y, width, height)
|
||||
board — Board definitions (name, colors, CSS)
|
||||
section — Board sections (empty/dynamic layouts)
|
||||
section_layout — Layout of sections on a board
|
||||
group — User groups
|
||||
user — Users (id, name, email, password hash)
|
||||
```
|
||||
|
||||
### The `app` Table
|
||||
|
||||
Service definitions. Homarr auto-discovers Docker containers via the Docker socket and populates this table.
|
||||
|
||||
```sql
|
||||
CREATE TABLE `app` (
|
||||
`id` TEXT PRIMARY KEY NOT NULL, -- ~25 char alphanumeric ID
|
||||
`name` TEXT NOT NULL, -- Display name
|
||||
`description` TEXT, -- Optional tooltip
|
||||
`icon_url` TEXT NOT NULL, -- URL to icon image
|
||||
`href` TEXT, -- URL to open on click
|
||||
`ping_url` TEXT -- URL for status checks (optional)
|
||||
);
|
||||
```
|
||||
|
||||
**Insert an app:**
|
||||
```sql
|
||||
INSERT INTO app (id, name, description, icon_url, href, ping_url)
|
||||
VALUES ('<generated-id>', 'Service Name', '', 'https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/<icon>.png', 'http://192.168.50.98:<port>', '');
|
||||
```
|
||||
|
||||
### The `item` Table
|
||||
|
||||
Widget placements on a board. The `kind` field determines the widget type.
|
||||
|
||||
```sql
|
||||
CREATE TABLE `item` (
|
||||
`id` TEXT PRIMARY KEY NOT NULL,
|
||||
`board_id` TEXT NOT NULL, -- References board.id
|
||||
`kind` TEXT NOT NULL, -- 'app', 'clock', 'weather', 'bookmarks', etc.
|
||||
`options` TEXT DEFAULT '{"json": {}}' NOT NULL, -- Widget-specific JSON config
|
||||
`advanced_options` TEXT DEFAULT '{"json": {}}' NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
**Insert an app item:**
|
||||
```sql
|
||||
INSERT INTO item (id, board_id, kind, options, advanced_options)
|
||||
VALUES ('<generated-id>', '<board-id>', 'app',
|
||||
'{"json":{"appId":"<app-id>","openInNewTab":true,"showTitle":true}}',
|
||||
'{"json":{}}');
|
||||
```
|
||||
|
||||
**Other widget kinds:**
|
||||
- `clock`: Simple clock widget — options: `{"json":{}}`
|
||||
- `weather`: Weather widget — options: `{"json":{"showCity":true,"hasForecast":true,"forecastDayCount":3}}`
|
||||
- `bookmarks`: Links collection — options: `{"json":{"title":"Name","layout":"grid","openNewTab":true,"items":["<app-id1>","<app-id2>"]}}`
|
||||
|
||||
### The `item_layout` Table
|
||||
|
||||
Grid position for each item on a section.
|
||||
|
||||
```sql
|
||||
CREATE TABLE `item_layout` (
|
||||
`id` TEXT PRIMARY KEY NOT NULL,
|
||||
`section_id` TEXT NOT NULL, -- References section.id
|
||||
`item_id` TEXT NOT NULL, -- References item.id
|
||||
`x` INTEGER NOT NULL, -- Column position (0-indexed)
|
||||
`y` INTEGER NOT NULL, -- Row position (0-indexed)
|
||||
`width` INTEGER NOT NULL, -- Width in grid units
|
||||
`height` INTEGER NOT NULL -- Height in grid units
|
||||
);
|
||||
```
|
||||
|
||||
**Insert a layout position:**
|
||||
```sql
|
||||
INSERT INTO item_layout (id, section_id, item_id, x, y, width, height)
|
||||
VALUES ('<generated-id>', '<section-id>', '<item-id>', <x>, <y>, 1, 1);
|
||||
```
|
||||
|
||||
### Finding IDs for Existing Records
|
||||
|
||||
```bash
|
||||
sqlite3 /home/ray/docker/homarr/appdata/db/db.sqlite "SELECT id, name FROM board;"
|
||||
sqlite3 /home/ray/docker/homarr/appdata/db/db.sqlite "SELECT id FROM section LIMIT 5;"
|
||||
sqlite3 /home/ray/docker/homarr/appdata/db/db.sqlite "SELECT lid, section_id FROM section_layout LIMIT 5;"
|
||||
```
|
||||
|
||||
### Icon URLs
|
||||
|
||||
Use one of the icon repositories:
|
||||
|
||||
```
|
||||
# Homarr Labs dashboard-icons (PNG - most comprehensive)
|
||||
https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/<service>.png
|
||||
https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/<service>.svg
|
||||
|
||||
# WalkXcode dashboard-icons (SVG)
|
||||
https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons@master/svg/<service>.svg
|
||||
|
||||
# Logan Marchione homelab-svg-assets
|
||||
https://cdn.jsdelivr.net/gh/loganmarchione/homelab-svg-assets@latest/assets/<service>.svg
|
||||
```
|
||||
|
||||
Common icon filenames: `immich`, `home-assistant`, `paperless-ngx`, `plex`, `audiobookshelf`, `mealie`, `qbittorrent`, `pihole`, `portainer`, `uptime-kuma`, `scrutiny`, `vaultwarden`, `pocketbase`, `glitchtip`, `searxng`, `sunshine`, `homarr`, `github`, `redis`, `postgres`, `valkey`, `chrome-beta`.
|
||||
|
||||
### Complete Population Workflow
|
||||
|
||||
```python
|
||||
import sqlite3
|
||||
import secrets
|
||||
import string
|
||||
import json
|
||||
|
||||
DB_PATH = "/home/ray/docker/homarr/appdata/db/db.sqlite"
|
||||
|
||||
def gen_id():
|
||||
"""Generate a ~25 char alphanumeric ID matching Homarr's format."""
|
||||
alphabet = string.ascii_lowercase + string.digits
|
||||
return ''.join(secrets.choice(alphabet) for _ in range(25))
|
||||
|
||||
def add_service(conn, board_id, section_id, name, icon_name, href, x, y, w=1, h=1):
|
||||
app_id = gen_id()
|
||||
item_id = gen_id()
|
||||
layout_id = gen_id()
|
||||
|
||||
# 1. Create app
|
||||
icon_url = f"https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/{icon_name}.png"
|
||||
conn.execute("INSERT INTO app (id, name, description, icon_url, href, ping_url) VALUES (?, ?, '', ?, '', '')",
|
||||
(app_id, name, icon_url, href))
|
||||
|
||||
# 2. Create item
|
||||
options = json.dumps({"json": {"appId": app_id, "openInNewTab": True, "showTitle": True}})
|
||||
conn.execute("INSERT INTO item (id, board_id, kind, options, advanced_options) VALUES (?, ?, 'app', ?, '{\"json\":{}}')",
|
||||
(item_id, board_id, options))
|
||||
|
||||
# 3. Create layout
|
||||
conn.execute("INSERT INTO item_layout (id, section_id, item_id, x, y, width, height) VALUES (?, ?, ?, ?, ?, ?, ?)",
|
||||
(layout_id, section_id, item_id, x, y, w, h))
|
||||
|
||||
conn.commit()
|
||||
print(f" Added {name} at ({x},{y})")
|
||||
|
||||
# Usage:
|
||||
# conn = sqlite3.connect(DB_PATH)
|
||||
# board_id = "un39cd3f4sj9ik35dkhuvo92" # from SELECT on board table
|
||||
# section_id = "r6ly519w0mp0ez7mgd8klg3z" # from SELECT on section table
|
||||
# services = [
|
||||
# ("Immich", "immich", "http://192.168.50.98:2283", 0, 0, 2, 1),
|
||||
# ("Home Assistant", "home-assistant", "http://192.168.50.98:8123", 2, 0),
|
||||
# ...
|
||||
# ]
|
||||
# for name, icon, url, x, y, *size in services:
|
||||
# w, h = size if size else (1, 1)
|
||||
# add_service(conn, board_id, section_id, name, icon, url, x, y, w, h)
|
||||
# conn.close()
|
||||
```
|
||||
|
||||
### Restart After Population
|
||||
|
||||
After any database modification, restart the container to reload:
|
||||
|
||||
```bash
|
||||
docker restart homarr
|
||||
```
|
||||
|
||||
### Pitfalls
|
||||
|
||||
- **IDs must be unique across their respective tables** — generate them with `secrets.token_urlsafe()` or custom alphanumeric generation, never hardcode.
|
||||
- **Board and section IDs differ per instance** — always query the live database first to discover them.
|
||||
- **`openInNewTab` is optional but recommended** — set `true` so clicking a service opens it in a new browser tab rather than navigating away from the dashboard.
|
||||
- **`showTitle` defaults to true** — set `false` for icon-only widgets if the grid is dense.
|
||||
- **Docker auto-discovery may recreate apps** — if Homarr detects a container name matching an app name, it may overwrite the `href` field. Workaround: edit the `app` entry via the Homarr Web UI after database insertion, or in the `options` JSON reference the Homarr-generated `app.id` instead of creating new `app` rows.
|
||||
- **Restart required** — Homarr caches the board layout aggressively. SQLite writes alone won't reflect on the page until the container restarts.
|
||||
- **Backup before bulk edit** — always copy `db.sqlite` before adding many services: `cp /home/ray/docker/homarr/appdata/db/db.sqlite{,.bak}`
|
||||
|
||||
### Grid Layout Design
|
||||
|
||||
Design a clean grid before inserting. Common patterns:
|
||||
|
||||
- **4-column grid** works well for most layouts
|
||||
- **2-wide for primary services** (Immich, Home Assistant, Plex)
|
||||
- **1-wide** for standard services
|
||||
- **Leave gaps for future additions** at the end of each row
|
||||
|
||||
Example layout for 16 services:
|
||||
```
|
||||
Row 0: Immich (2w), HA (1w), Paperless (1w)
|
||||
Row 1: Plex (1w), Audiobk (1w), Mealie (1w), qBit (1w)
|
||||
Row 2: Portainer (1w), Pi-hole (1w), Kuma (1w), Scrutiny (1w)
|
||||
Row 3: Vaultwrdn (1w), SearXNG (1w), PocketB (1w), HermesDb(1w)
|
||||
Row 4: HermesUI (1w), Sunshine(1w), Chrome (1w), GlitchT(1w)
|
||||
```
|
||||
@@ -0,0 +1,284 @@
|
||||
# KasmVNC Chrome Browser (Browser-in-Browser)
|
||||
|
||||
Deploy a full Chrome browser accessible via web browser (no VNC client needed) using `kasmweb/chrome`.
|
||||
|
||||
## Architecture
|
||||
|
||||
- Docker container: `kasmweb/chrome:1.16.0`
|
||||
- KasmVNC serves its own built-in noVNC web UI on port **6901** (HTTPS with self-signed cert)
|
||||
- No separate web server needed — Xvnc process runs `-httpd /usr/share/kasmvnc/www` internally
|
||||
- Auth: HTTP Basic Auth, username `kasm_user`, password set via `VNC_PW` env var
|
||||
- Chrome runs inside the container with `--shm-size=2g` (required)
|
||||
|
||||
## Deployment
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name chrome-vnc \
|
||||
--restart unless-stopped \
|
||||
--shm-size=2g \
|
||||
-p 127.0.0.1:6901:6901 \
|
||||
-e VNC_PW=<password> \
|
||||
-e LANG=en_US.UTF-8 \
|
||||
-v /mnt/seagate8tb/docker/chrome-vnc:/home/kasm-user \
|
||||
kasmweb/chrome:1.16.0
|
||||
```
|
||||
|
||||
## Nginx Reverse Proxy
|
||||
|
||||
CRITICAL: KasmVNC sends `Cross-Origin-Embedder-Policy: require-corp` and `Cross-Origin-Opener-Policy: same-origin` headers that break browser rendering when the page is proxied. These MUST be stripped on EVERY nginx layer in the chain (home server + VPS).
|
||||
|
||||
### Home server nginx
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen <PORT> ssl;
|
||||
server_name grajmedia.duckdns.org browser.graj-media.com;
|
||||
|
||||
# ... SSL cert config ...
|
||||
|
||||
location / {
|
||||
proxy_pass https://127.0.0.1:6901;
|
||||
proxy_http_version 1.1;
|
||||
proxy_ssl_verify off;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 86400;
|
||||
proxy_buffering off;
|
||||
proxy_hide_header Cross-Origin-Embedder-Policy;
|
||||
proxy_hide_header Cross-Origin-Opener-Policy;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### VPS nginx
|
||||
|
||||
```nginx
|
||||
server {
|
||||
server_name browser.graj-media.com;
|
||||
location / {
|
||||
proxy_pass https://100.93.253.36:<PORT>;
|
||||
proxy_http_version 1.1;
|
||||
proxy_ssl_verify off;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 86400;
|
||||
proxy_buffering off;
|
||||
proxy_hide_header Cross-Origin-Embedder-Policy;
|
||||
proxy_hide_header Cross-Origin-Opener-Policy;
|
||||
}
|
||||
# ... SSL ...
|
||||
}
|
||||
```
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **Port mapping confusion**: Do NOT map to 4902 or other internal service ports. Map `6901:6901` — KasmVNC's built-in HTTP server runs on 6901 alongside the VNC server.
|
||||
2. **COEP/COOP headers**: If the page shows "This page isn't working" or a blank screen, check that `proxy_hide_header` directives are present on ALL nginx layers. These headers are set by KasmVNC internally.
|
||||
3. **Must use `proxy_ssl_verify off`** — KasmVNC uses a self-signed cert internally.
|
||||
4. **WebSocket upgrade required** — noVNC uses WebSockets for the VNC connection.
|
||||
5. **DO NOT use `--network host`**: KasmVNC detects the host X display (`/tmp/.X11-unix/X0`) and fails with "Authorization required, but no authorization protocol specified". This is a fatal error — the container will not serve the web UI. Use bridge networking instead.
|
||||
6. **Bridge → host access**: Docker's default bridge network isolates containers from the host. If the remote Chrome needs to access host services (PocketBase, Immich, HA, etc.), use `--add-host=host.docker.internal:host-gateway` and add an iptables rule:
|
||||
```bash
|
||||
sudo iptables -I INPUT -i docker0 -p tcp --dport <PORT> -j ACCEPT
|
||||
```
|
||||
Then access services from inside Chrome at `https://host.docker.internal:<PORT>`. This rule does NOT survive reboots — make it persistent via `iptables-persistent` or a systemd unit.
|
||||
|
||||
## Password change
|
||||
|
||||
Recreate the container with a new `VNC_PW` value:
|
||||
|
||||
```bash
|
||||
docker stop chrome-vnc && docker rm chrome-vnc
|
||||
docker run -d --name chrome-vnc --restart unless-stopped --shm-size=2g \
|
||||
-p 127.0.0.1:6901:6901 \
|
||||
-e VNC_PW=<new_password> \
|
||||
-e LANG=en_US.UTF-8 \
|
||||
-v /mnt/seagate8tb/docker/chrome-vnc:/home/kasm-user \
|
||||
kasmweb/chrome:1.16.0
|
||||
```
|
||||
|
||||
The `/home/kasm-user` volume preserves Chrome profile data across recreates.
|
||||
|
||||
## Security Assessment
|
||||
|
||||
When auditing or hardening a browser.graj-media.com-style deployment (KasmVNC + Chrome behind nginx + VPS reverse proxy), check these areas:
|
||||
|
||||
### Firewall Posture (STRONG)
|
||||
- UFW restricts port to LAN (192.168.50.0/24) and Tailscale (100.64.0.0/10, fd7a::/48) only
|
||||
- Public DNS points to VPS proxy, not the home server IP directly
|
||||
- External traffic traverses VPS → Tailscale encrypted tunnel → home server
|
||||
- **This is the single strongest defense** — even if KasmVNC had an 0-day, the network is unreachable from the internet
|
||||
|
||||
### Authentication (MODERATE)
|
||||
- Single auth layer: KasmVNC web UI username + password (set via `VNC_PW`)
|
||||
- No nginx-level `auth_basic` for defense-in-depth
|
||||
- **Recommendation**: Add nginx HTTP Basic Auth as a second factor. Even simple shared credentials at the nginx layer prevent unauthenticated scans from reaching the KasmVNC login prompt.
|
||||
|
||||
### Host Networking Risk (CRITICAL if used)
|
||||
When running with `--network host` (as opposed to bridge):
|
||||
- The Chrome browser has full network-level access to the host machine
|
||||
- All Docker services (Immich, PocketBase, Paperless, HA, Mealie, etc.) are reachable from inside the browser at `localhost:<port>` — no additional auth required beyond what the service itself has
|
||||
- A malicious site visited in the remote browser could attempt DNS rebinding or CSRF against host services
|
||||
- **Recommendation**: Prefer bridge networking with `--add-host=host.docker.internal:host-gateway` + iptables rules for specific host port access. See "Bridge → host access" section above.
|
||||
### Missing Security Headers (nginx)
|
||||
|
||||
No security headers were set on the nginx proxy. Add them at the **location block** level (they do NOT take effect at the server level when `proxy_pass` is in a nested location):
|
||||
|
||||
```nginx
|
||||
# Home server nginx location block:
|
||||
location / {
|
||||
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||||
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), midi=(), sync-xhr=(), clipboard-read=(), clipboard-write=()" always;
|
||||
# ... existing proxy_pass directives ...
|
||||
}
|
||||
```
|
||||
|
||||
**Important**: `add_header` directives in the `server` block may be silently dropped when a `location` block with `proxy_pass` is present. Put them inside the `location` block for guaranteed effect. Use the `always` parameter to include them on error responses (4xx/5xx) too.
|
||||
|
||||
KasmVNC already sends COEP/COOP headers that must be hidden (already in the config above). CSP is tricky with noVNC since it needs inline scripts and WebSocket connections — test before adding.
|
||||
|
||||
### No Rate Limiting
|
||||
|
||||
No `limit_req` on the nginx endpoint. An attacker with credentials can brute-force the KasmVNC login without throttling.
|
||||
|
||||
**Add zone to nginx.conf http block:**
|
||||
```nginx
|
||||
limit_req_zone $binary_remote_addr zone=kasmvnc:10m rate=5r/m;
|
||||
```
|
||||
|
||||
**Apply in the server block (before location):**
|
||||
```nginx
|
||||
limit_req zone=kasmvnc burst=5 nodelay;
|
||||
```
|
||||
|
||||
### No fail2ban
|
||||
|
||||
The VPS proxy lacks brute-force protection beyond nginx's rate limiter. Install fail2ban and create a jail for nginx HTTP auth failures — note it watches **error.log**, not access.log:
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y fail2ban
|
||||
sudo tee /etc/fail2ban/jail.d/nginx-http-auth.conf << 'EOF'
|
||||
[nginx-http-auth]
|
||||
enabled = true
|
||||
port = http,https
|
||||
filter = nginx-http-auth
|
||||
logpath = /var/log/nginx/error.log
|
||||
maxretry = 5
|
||||
bantime = 3600
|
||||
findtime = 300
|
||||
EOF
|
||||
sudo systemctl restart fail2ban
|
||||
```
|
||||
|
||||
### Old Base OS
|
||||
- Image built August 2025 (~11 months old as of July 2026)
|
||||
- KasmVNC server 1.2.0, Chrome 138.0.7204.183 (current)
|
||||
- **Recommendation**: Periodically pull a fresh `kasmweb/chrome` image to get updated base OS packages. The Chrome binary updates within the container but system libraries don't.
|
||||
### Default Container Capabilities
|
||||
|
||||
- No `--cap-drop` flags — container runs with default Docker capabilities
|
||||
- **Recommendation**: Drop the most dangerous capabilities. Chrome needs CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID for its sandbox, but does NOT need SYS_ADMIN, SYS_PTRACE, SYS_BOOT, SYS_MODULE, NET_ADMIN, SYS_RAWIO, SYS_TIME, or similar high-risk caps. Apply when recreating:
|
||||
```bash
|
||||
docker run -d \
|
||||
--name chrome-vnc \
|
||||
--restart unless-stopped \
|
||||
--shm-size=2g \
|
||||
-p 127.0.0.1:6901:6901 \
|
||||
-e VNC_PW=<password> \
|
||||
-e LANG=en_US.UTF-8 \
|
||||
-v /mnt/seagate8tb/docker/chrome-vnc:/home/kasm-user \
|
||||
--cap-drop=SETPCAP \
|
||||
--cap-drop=SYS_ADMIN \
|
||||
--cap-drop=SYS_PTRACE \
|
||||
--cap-drop=SYS_BOOT \
|
||||
--cap-drop=SYS_MODULE \
|
||||
--cap-drop=NET_ADMIN \
|
||||
--cap-drop=SYS_RAWIO \
|
||||
--cap-drop=SYS_TIME \
|
||||
--cap-drop=SYSLOG \
|
||||
--cap-drop=AUDIT_CONTROL \
|
||||
--cap-drop=MKNOD \
|
||||
--cap-drop=SETFCAP \
|
||||
--cap-drop=NET_RAW \
|
||||
--cap-drop=IPC_LOCK \
|
||||
kasmweb/chrome:1.16.0
|
||||
```
|
||||
Verify with: `docker inspect chrome-vnc --format 'CapDrop: {{.HostConfig.CapDrop}}'`
|
||||
|
||||
### DOCKER-USER Firewall Blocks Container Outbound Internet (Not Just Ports)
|
||||
|
||||
The host iptables DOCKER-USER chain restricts Docker containers broadly. Managed by `docker-iptables-restrict.service` (at `/home/ray/docker/docker-iptables-restrict.sh`), the rules allow LAN, Tailscale, and established connections — everything else is DROPPED.
|
||||
|
||||
**Two failure modes:**
|
||||
|
||||
1. **"No internet at all"** — the container can't reach ANY external IP. Root cause: the DOCKER-USER chain allows traffic from LAN (192.168.50.0/24) and Tailscale (100.64.0.0/10) but has **no egress rule for Docker bridge subnets**. New outgoing connections from bridge containers hit the DROP.
|
||||
|
||||
Fix:
|
||||
```bash
|
||||
sudo iptables -I DOCKER-USER -o enp2s0 -s 172.16.0.0/12 -j ACCEPT
|
||||
```
|
||||
Add the same rule to `/home/ray/docker/docker-iptables-restrict.sh` using its idempotency pattern.
|
||||
|
||||
2. **"Specific ports blocked"** — container has internet (HTTP/HTTPS work) but SFTP (22), FTP (21), or other ports time out. This is the classic FileZilla scenario.
|
||||
|
||||
Fix: Add a per-container exception to DOCKER-USER + persist in the script.
|
||||
|
||||
### FileZilla Setup
|
||||
|
||||
Install and configure FileZilla in the Kasm container for FTP/SFTP transfers:
|
||||
|
||||
```bash
|
||||
# Install
|
||||
docker exec -u root chrome-vnc apt-get install -y filezilla
|
||||
|
||||
# Launch
|
||||
docker exec -u kasm-user -d chrome-vnc sh -c "DISPLAY=:1 filezilla"
|
||||
|
||||
# Configure site via sitemanager.xml
|
||||
PASS_B64=$(echo -n "password" | base64)
|
||||
docker exec -i -u kasm-user chrome-vnc tee /home/kasm-user/.config/filezilla/sitemanager.xml > /dev/null << FZEOF
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<FileZilla3>
|
||||
<Servers>
|
||||
<Server>
|
||||
<Host>example.com</Host>
|
||||
<Port>22</Port>
|
||||
<Protocol>1</Protocol>
|
||||
<Type>0</Type>
|
||||
<User>username</User>
|
||||
<Pass encoding="base64">$PASS_B64</Pass>
|
||||
<Logontype>1</Logontype>
|
||||
<Name>Seedbox (SFTP)</Name>
|
||||
<PasvMode>0</PasvMode>
|
||||
</Server>
|
||||
</Servers>
|
||||
</FileZilla3>
|
||||
FZEOF
|
||||
```
|
||||
|
||||
If FileZilla was running when the XML was written, restart it: `docker exec -u kasm-user chrome-vnc pkill filezilla` then relaunch.
|
||||
|
||||
### Pitfall: nginx `sites-enabled` version skew
|
||||
|
||||
If you edit `sites-available/<config>` and nginx doesn't pick up the change even after a reload, check whether `sites-enabled/<config>` is a **symlink** or a **separate copy**:
|
||||
|
||||
```bash
|
||||
ls -la /etc/nginx/sites-enabled/<config>
|
||||
# Want: lrwxrwxrwx (symlink to sites-available)
|
||||
# Have: -rw-r--r-- (separate file — changes to sites-available are ignored)
|
||||
```
|
||||
|
||||
If it's a copy, replace it with a symlink:
|
||||
```bash
|
||||
sudo rm /etc/nginx/sites-enabled/<config>
|
||||
sudo ln -s /etc/nginx/sites-available/<config> /etc/nginx/sites-enabled/<config>
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
This can happen when configs were manually deployed or migrated from another setup rather than created fresh via `ln -sf`.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Mealie Batch Recipe Import
|
||||
|
||||
Authenticate via API and bulk-import recipes from URLs. Mealie's built-in scraper handles ~300+ sites but reliability varies wildly.
|
||||
|
||||
## API Auth Pattern
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
MEALIE = "http://127.0.0.1:9925" # or https://grajmedia.duckdns.org:3449
|
||||
|
||||
resp = requests.post(
|
||||
f"{MEALIE}/api/auth/token",
|
||||
data={"username": "email@example.com", "password": "password", "grant_type": ""},
|
||||
headers={"Content-Type": "application/x-www-form-urlencoded"}
|
||||
)
|
||||
token = resp.json()["access_token"]
|
||||
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
|
||||
```
|
||||
|
||||
## Batch Import
|
||||
|
||||
```python
|
||||
urls = ["https://example.com/recipe-1", "https://example.com/recipe-2"]
|
||||
|
||||
for url in urls:
|
||||
resp = requests.post(
|
||||
f"{MEALIE}/api/recipes/create/url",
|
||||
json={"url": url},
|
||||
headers=headers,
|
||||
timeout=60
|
||||
)
|
||||
# 200/201 = success, 400 = scraper failed
|
||||
```
|
||||
|
||||
## Scraper Reliability (as of June 2026)
|
||||
|
||||
| Site | Reliability | Notes |
|
||||
|---|---|---|
|
||||
| BBC Good Food | High | Consistently works |
|
||||
| RecipeTin Eats | High | Good parser support |
|
||||
| Budget Bytes | Medium | HTTPException ~30% of the time, retry helps |
|
||||
| Damn Delicious | Medium | Intermittent blocks |
|
||||
| AllRecipes | Low | Frequently blocked (Cloudflare) |
|
||||
| Simply Recipes | Low | Frequently blocked |
|
||||
| Gimme Some Oven | Low | Frequently blocked |
|
||||
|
||||
Add `time.sleep(1.5)` between requests to avoid rate limiting.
|
||||
|
||||
## URL Format
|
||||
|
||||
The `/api/recipes/create/url` endpoint expects a full recipe page URL. It does NOT accept search results, category pages, or non-recipe URLs. The scraper extracts title, ingredients, steps, image, and metadata automatically.
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
# Paperless Scanner Integration (SANE/AirScan)
|
||||
|
||||
When the printer's web admin password is unknown or scan-to-FTP can't be configured from the touchscreen, scan from the server directly using SANE and the AirScan/eSCL network protocol. No printer configuration needed — the server pulls scans from the printer over the network.
|
||||
|
||||
Tested with Brother MFC-J5855DW on Ubuntu 26.04.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Server command: scan-to-paperless
|
||||
→ SANE/AirScan (eSCL over HTTP)
|
||||
→ Brother MFC (192.168.50.219:80)
|
||||
→ PDF saved to /mnt/seagate8tb/paperless/consume/
|
||||
→ Paperless auto-ingests (OCR, classify, tag)
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install sane-airscan
|
||||
|
||||
```bash
|
||||
sudo apt install -y sane-airscan sane-utils
|
||||
```
|
||||
|
||||
No Brother drivers needed — `sane-airscan` uses the driverless eSCL/AirScan protocol that most modern network MFCs support.
|
||||
|
||||
### 2. Verify detection
|
||||
|
||||
```bash
|
||||
scanimage -L
|
||||
# Should show:
|
||||
# device `airscan:e0:Brother MFC-J5855DW' is a eSCL Brother MFC-J5855DW ip=192.168.50.219
|
||||
```
|
||||
|
||||
### 3. Fix consume folder permissions
|
||||
|
||||
The consume folder may be owned by a Docker-created user. Add ACL for the local user:
|
||||
|
||||
```bash
|
||||
sudo setfacl -m u:ray:rwx /mnt/seagate8tb/paperless/consume
|
||||
```
|
||||
|
||||
### 4. Install scan script
|
||||
|
||||
```bash
|
||||
sudo tee /usr/local/bin/scan-to-paperless << 'SCRIPT'
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
DEVICE="airscan:e0:Brother MFC-J5855DW"
|
||||
CONSUME="/mnt/seagate8tb/paperless/consume"
|
||||
MODE="Color"
|
||||
RES="300"
|
||||
SOURCE="ADF"
|
||||
|
||||
NAME=""
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--flatbed) SOURCE="Flatbed" ;;
|
||||
--gray) MODE="Gray" ;;
|
||||
--150dpi) RES="150" ;;
|
||||
*) NAME="$1" ;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
SCAN_OPTS="--mode $MODE --resolution $RES"
|
||||
[ "$SOURCE" = "ADF" ] && SCAN_OPTS="$SCAN_OPTS --source ADF --batch-count=1"
|
||||
|
||||
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
|
||||
FILENAME="${NAME:-scan}_${TIMESTAMP}.pdf"
|
||||
OUTFILE="$CONSUME/$FILENAME"
|
||||
|
||||
echo "Scanning ($SOURCE, $MODE, ${RES}dpi) → $FILENAME"
|
||||
scanimage --device "$DEVICE" $SCAN_OPTS --format pdf -o "$OUTFILE"
|
||||
|
||||
SIZE=$(du -h "$OUTFILE" | cut -f1)
|
||||
echo "Done — $SIZE saved to Paperless"
|
||||
SCRIPT
|
||||
|
||||
sudo chmod +x /usr/local/bin/scan-to-paperless
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
scan-to-paperless # ADF, color 300dpi
|
||||
scan-to-paperless invoice # names it "invoice_20260614_172310.pdf"
|
||||
scan-to-paperless --flatbed # use flatbed instead of document feeder
|
||||
scan-to-paperless --gray # black & white
|
||||
scan-to-paperless --150dpi # lower resolution (smaller file)
|
||||
scan-to-paperless receipt --flatbed --gray # combine flags
|
||||
```
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **`/usr/local/bin` may be noexec**: If direct execution fails, use `bash /usr/local/bin/scan-to-paperless` or install the script to `~/.local/bin/`.
|
||||
- **No paper in ADF**: If the ADF is empty, `scanimage` exits with error. The `set -e` in the script catches this. Use `--flatbed` if loading a single page.
|
||||
- **Permission denied on consume folder**: Docker often creates the consume folder with root ownership. Use `setfacl` to grant the local user write access without changing Docker's ownership.
|
||||
- **vsftpd `nologin` shell**: If also setting up FTP, vsftpd's PAM rejects `/usr/sbin/nologin`. Add it to `/etc/shells`.
|
||||
@@ -0,0 +1,89 @@
|
||||
# Paperless Scanner Integration (FTP)
|
||||
|
||||
Connect a network scanner (Brother MFC, etc.) to Paperless-ngx so scans land directly in the consume folder and are auto-ingested. Uses a lightweight FTP server (vsftpd) chrooted to the consume folder.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Brother MFC (192.168.50.219)
|
||||
→ Scan-to-FTP profile
|
||||
→ vsftpd on rayserver (192.168.50.98:21)
|
||||
→ /mnt/seagate8tb/paperless/consume/
|
||||
→ Paperless auto-ingests (OCR, classify, tag)
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install vsftpd
|
||||
|
||||
```bash
|
||||
sudo apt install -y vsftpd
|
||||
```
|
||||
|
||||
### 2. Create restricted user
|
||||
|
||||
```bash
|
||||
sudo useradd -m -d /mnt/seagate8tb/paperless/consume -s /usr/sbin/nologin paperscan
|
||||
sudo chown paperscan:paperscan /mnt/seagate8tb/paperless/consume
|
||||
echo "/usr/sbin/nologin" | sudo tee -a /etc/shells # PAM needs valid shell
|
||||
sudo passwd paperscan # set to e.g. brotherscan123
|
||||
```
|
||||
|
||||
### 3. vsftpd config (`/etc/vsftpd.conf`)
|
||||
|
||||
```
|
||||
listen=YES
|
||||
listen_ipv6=NO
|
||||
anonymous_enable=NO
|
||||
local_enable=YES
|
||||
write_enable=YES
|
||||
local_umask=022
|
||||
chroot_local_user=YES
|
||||
allow_writeable_chroot=YES
|
||||
seccomp_sandbox=NO
|
||||
|
||||
# Passive mode — needed for Brother printers
|
||||
pasv_enable=YES
|
||||
pasv_min_port=40000
|
||||
pasv_max_port=40005
|
||||
pasv_address=192.168.50.98
|
||||
|
||||
# Restrict to paperscan user only
|
||||
userlist_enable=YES
|
||||
userlist_file=/etc/vsftpd.userlist
|
||||
userlist_deny=NO
|
||||
```
|
||||
|
||||
Create userlist: `echo "paperscan" | sudo tee /etc/vsftpd.userlist`
|
||||
|
||||
Start: `sudo systemctl enable --now vsftpd`
|
||||
|
||||
### 4. Verify
|
||||
|
||||
```bash
|
||||
# Upload test file
|
||||
echo "test" > /tmp/ftp_test.txt
|
||||
curl -s -T /tmp/ftp_test.txt --user paperscan:brotherscan123 ftp://127.0.0.1/test.txt
|
||||
ls -la /mnt/seagate8tb/paperless/consume/test.txt
|
||||
rm /mnt/seagate8tb/paperless/consume/test.txt
|
||||
```
|
||||
|
||||
### 5. Configure Brother printer
|
||||
|
||||
Open `http://192.168.50.219/` in a browser:
|
||||
- **Scan** → **Scan to FTP/SFTP/Network** → **Create New Profile**
|
||||
- Host: `192.168.50.98`, Port: `21`
|
||||
- Username: `paperscan`, Password: `<password>`
|
||||
- Store Directory: `/` (root)
|
||||
- Quality: Color 300dpi, PDF
|
||||
|
||||
### Daily use
|
||||
|
||||
On the printer touchscreen: **Scan** → select profile → **Start**. The PDF appears in Paperless within seconds.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **PAM rejects nologin shell**: vsftpd uses PAM, which checks `/etc/shells`. Add `/usr/sbin/nologin` to it.
|
||||
- **Passive ports**: Brother printers need passive mode FTP. Set `pasv_enable=YES` and open ports 40000-40005 if using a firewall.
|
||||
- **Chroot writable**: `allow_writeable_chroot=YES` is required when the chroot directory (consume) is writable by the FTP user.
|
||||
- **Ownership**: Files uploaded via FTP are owned by the FTP user (`paperscan`). Paperless needs read access to the consume folder — `paperscan:paperscan` ownership works as long as Paperless runs as a user that can traverse the path. Verify with a test scan.
|
||||
@@ -0,0 +1,65 @@
|
||||
# SearXNG Deployment
|
||||
|
||||
Self-hosted metasearch engine — aggregates Google, Bing, DDG, etc. Hermes-native search backend. Privacy: all web searches go through your own instance instead of third-party API servers.
|
||||
|
||||
## Port: 8888 (bound to 127.0.0.1)
|
||||
|
||||
## Docker Compose
|
||||
|
||||
Location: `/mnt/seagate8tb/docker/searxng/docker-compose.yml`
|
||||
|
||||
```yaml
|
||||
services:
|
||||
searxng:
|
||||
image: searxng/searxng:latest
|
||||
container_name: searxng
|
||||
ports:
|
||||
- "127.0.0.1:8888:8080"
|
||||
volumes:
|
||||
- ./searxng:/etc/searxng:rw
|
||||
environment:
|
||||
- SEARXNG_BASE_URL=http://localhost:8888/
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
```bash
|
||||
cd /mnt/seagate8tb/docker/searxng
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Enable JSON Format
|
||||
|
||||
SearXNG with `use_default_settings: true` has JSON disabled by default. The settings file is owned by the container user, so modify via docker exec:
|
||||
|
||||
```bash
|
||||
docker exec searxng sh -c 'echo "search:" >> /etc/searxng/settings.yml && echo " formats:" >> /etc/searxng/settings.yml && echo " - html" >> /etc/searxng/settings.yml && echo " - json" >> /etc/searxng/settings.yml'
|
||||
docker restart searxng
|
||||
```
|
||||
|
||||
Verify: `curl -s "http://localhost:8888/search?q=test&format=json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['results']))"`
|
||||
|
||||
## Hermes Integration
|
||||
|
||||
```bash
|
||||
# Add to ~/.hermes/.env
|
||||
echo 'SEARXNG_URL=http://localhost:8888' >> ~/.hermes/.env
|
||||
|
||||
# Set search backend
|
||||
hermes config set web.search_backend searxng
|
||||
```
|
||||
|
||||
SearXNG is search-only — still need an extract backend (Firecrawl free tier) for `web_extract`.
|
||||
|
||||
## Maintenance
|
||||
|
||||
Google scraper breaks periodically when Google changes HTML. Fix: pull latest image and force-recreate:
|
||||
|
||||
```bash
|
||||
cd /mnt/seagate8tb/docker/searxng
|
||||
docker compose pull
|
||||
docker compose up -d --force-recreate
|
||||
```
|
||||
|
||||
Check for engine errors: `docker logs searxng 2>&1 | grep -i error | tail -10`
|
||||
|
||||
Rate limiting: Google may throttle with `SearxEngineTooManyRequestsException (suspended_time=180)`. This is normal — SearXNG falls back to other engines automatically.
|
||||
@@ -0,0 +1,159 @@
|
||||
# Self-Hosted Service Security Audit
|
||||
|
||||
A comprehensive methodology for assessing the security posture of any self-hosted web service (KasmVNC, Immich, Paperless, Mealie, etc.) behind a VPS reverse proxy.
|
||||
|
||||
## Audit Checklist (Run in Order)
|
||||
|
||||
### 1. Network Exposure
|
||||
```bash
|
||||
# DNS resolution — where does the domain point?
|
||||
dig +short <subdomain>.<domain> @1.1.1.1
|
||||
|
||||
# Compare against server's public IP
|
||||
curl -s ifconfig.me
|
||||
|
||||
# If they differ → VPS reverse proxy in front → good
|
||||
# If they match → service directly exposed → verify UFW
|
||||
```
|
||||
|
||||
### 2. TLS / Transport Security
|
||||
```bash
|
||||
# Full handshake info + headers
|
||||
curl -sI -v https://<domain>/ 2>&1 | grep -E '(SSL|TLS|certificate|HTTP/|Server|Strict-Transport|X-Content|X-Frame|CSP|Referrer)'
|
||||
|
||||
# Certificate details
|
||||
echo | openssl s_client -servername <domain> -connect <domain>:443 2>/dev/null | openssl x509 -noout -text | grep -E '(Subject:|Issuer:|Not Before|Not After|Subject Alternative)'
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- TLS 1.2+ only (no TLS 1.0/1.1, no SSLv3)
|
||||
- Strong ciphers (AES-GCM, ChaCha20) — not RC4, 3DES, or MD5
|
||||
- Let's Encrypt or similar trusted CA (not self-signed)
|
||||
- HSTS header present (`Strict-Transport-Security`)
|
||||
- Certificate covers the domain (Subject Alternative Name)
|
||||
|
||||
### 3. HTTP Security Headers
|
||||
```bash
|
||||
curl -sI https://<domain>/ | grep -i -E '(strict-transport-security|x-content-type-options|x-frame-options|content-security-policy|referrer-policy|permissions-policy)'
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- `Strict-Transport-Security` — HSTS, ideally `max-age>=31536000`
|
||||
- `X-Content-Type-Options: nosniff` — prevents MIME sniffing
|
||||
- `X-Frame-Options: DENY` or `SAMEORIGIN` — clickjacking protection
|
||||
- `Content-Security-Policy` — XSS mitigation (can be tricky with SPAs/WebSockets)
|
||||
- `Referrer-Policy` — controls referrer leakage
|
||||
- Missing headers are a hardening opportunity, not always critical for internal services
|
||||
|
||||
### 4. Nginx / Reverse Proxy Config
|
||||
```bash
|
||||
# Inspect the nginx site config
|
||||
cat /etc/nginx/sites-available/<service>
|
||||
|
||||
# Check for server_name — does it match the subdomain?
|
||||
# Check for auth_basic — any nginx-level auth?
|
||||
grep -rn "auth_basic" /etc/nginx/ 2>/dev/null
|
||||
|
||||
# Check for rate limiting
|
||||
grep -rn "limit_req" /etc/nginx/ 2>/dev/null
|
||||
|
||||
# Check for proxy_hide_header — which headers are stripped?
|
||||
grep "proxy_hide_header" /etc/nginx/sites-available/<service>
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- `server_name` includes ALL valid domains (DuckDNS + custom domain)
|
||||
- `auth_basic` for defense-in-depth (recommended for single-user services)
|
||||
- `limit_req` to prevent brute force
|
||||
- `proxy_hide_header` — strips unwanted backend headers (critical for KasmVNC COEP/COOP)
|
||||
- `proxy_ssl_verify off` — acceptable for localhost backends, note it's not verifying
|
||||
|
||||
### 5. Docker Container Security
|
||||
```bash
|
||||
# List containers with status
|
||||
docker ps --format "table {{.Names}}\t{{.Status}}"
|
||||
|
||||
# Deep inspect
|
||||
docker inspect <container> --format '{{.HostConfig.NetworkMode}}' # network mode
|
||||
docker inspect <container> --format '{{.HostConfig.CapDrop}}' # dropped capabilities
|
||||
docker inspect <container> --format '{{.HostConfig.CapAdd}}' # added capabilities
|
||||
docker inspect <container> --format '{{.HostConfig.SecurityOpt}}' # security opts
|
||||
docker inspect <container> --format '{{.Config.User}}' # running user
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- **Network mode**: `bridge` (isolated, preferred) vs `host` (full host network access — riskier)
|
||||
- **Capabilities**: ideally `--cap-drop=ALL` with explicit `--cap-add` for what's needed
|
||||
- **Running user**: non-root inside container (e.g., `kasm-user` is good)
|
||||
- **Security opts**: `no-new-privileges:true` is a hardening bonus
|
||||
- **Restart policy**: `unless-stopped` (good) vs `always` (also fine)
|
||||
|
||||
### 6. Container Internals
|
||||
```bash
|
||||
# Inside the container
|
||||
docker exec <container> whoami
|
||||
docker exec <container> cat /etc/os-release 2>/dev/null
|
||||
docker exec <container> cat /etc/debian_version 2>/dev/null
|
||||
docker exec <container> uname -r 2>/dev/null
|
||||
|
||||
# Application version
|
||||
docker exec <container> <app> --version 2>/dev/null
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- Base OS age (Ubuntu 20.04 is past standard EOL in April 2025)
|
||||
- Application version recency
|
||||
- Image build date (`docker inspect <image> --format '{{.Created}}'`)
|
||||
- Whether the image is regularly updated
|
||||
|
||||
### 7. Firewall and Host Defense
|
||||
```bash
|
||||
# UFW rules
|
||||
sudo ufw status verbose
|
||||
|
||||
# iptables rules for the service port
|
||||
sudo iptables -L INPUT -n --line-numbers | grep <port>
|
||||
|
||||
# Security monitoring
|
||||
dpkg -l fail2ban crowdsec rkhunter chkrootkit 2>/dev/null | grep '^ii'
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- Default inbound policy: DROP (not ACCEPT)
|
||||
- Service port allowed only from needed ranges (LAN, Tailscale VPN)
|
||||
- Public internet blocked at the firewall level
|
||||
- fail2ban or similar running for brute-force protection
|
||||
|
||||
### 8. VPS Reverse Proxy Architecture
|
||||
```bash
|
||||
# Trace the architecture
|
||||
dig +short <subdomain>.<domain> # → VPS IP
|
||||
# VPS proxies to home server via Tailscale
|
||||
ssh ubuntu@<vps-ip> 'grep proxy_pass /etc/nginx/sites-enabled/<service>'
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- DNS points to VPS, not home server IP
|
||||
- VPS nginx proxies via Tailscale IP (100.x.x.x), not public IP
|
||||
- UFW on home server allows port only from LAN + Tailscale ranges
|
||||
- Home router has NO port forward for this service (zero open ports)
|
||||
|
||||
### 9. Risk Summary Matrix
|
||||
|
||||
| Layer | Weakness | Severity | Mitigation |
|
||||
|-------|----------|----------|------------|
|
||||
| Network | Public exposure via DNS | Low if behind VPS | UFW, VPS proxy |
|
||||
| Transport | Missing HSTS | Low | `add_header` in nginx |
|
||||
| Auth | Single auth layer | Medium | Add nginx `auth_basic` |
|
||||
| Container | Host networking | High | Switch to bridge + iptables |
|
||||
| Container | Default capabilities | Medium | `--cap-drop=ALL` + explicit adds |
|
||||
| Container | Old base OS | Medium | Regular image pulls |
|
||||
| App | No rate limiting | Low | `limit_req` in nginx |
|
||||
|
||||
## Interpretation Guide
|
||||
|
||||
- **Low severity** = hardening opportunity, not urgent. Benefits of fixing may not justify risk of breaking the service.
|
||||
- **Medium severity** = address when convenient. Adds defense-in-depth.
|
||||
- **High severity** = actively exploitable if attacker gains any toehold. Prioritize.
|
||||
|
||||
The firewall + VPS architecture is almost always the strongest defense. Even a poorly-configured container behind a proper firewall is hard to reach from the internet. Focus hardening effort where it reduces blast radius once an attacker is inside the network.
|
||||
@@ -0,0 +1,113 @@
|
||||
# Vaultwarden Deployment (rayserver)
|
||||
|
||||
Complete worked example for deploying Vaultwarden (Bitwarden-compatible password manager) on rayserver infrastructure.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Browser → VPS (vault.graj-media.com:443, nginx SSL)
|
||||
↳ Tailscale → Home server (100.93.253.36:3446, nginx SSL)
|
||||
↳ Vaultwarden (127.0.0.1:8812, Docker)
|
||||
```
|
||||
|
||||
## Docker Compose
|
||||
|
||||
```yaml
|
||||
services:
|
||||
vaultwarden:
|
||||
image: vaultwarden/server:latest
|
||||
container_name: vaultwarden
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- /mnt/seagate8tb/docker/vaultwarden:/data
|
||||
ports:
|
||||
- "127.0.0.1:8812:80"
|
||||
environment:
|
||||
- DOMAIN=https://vault.graj-media.com
|
||||
- SIGNUPS_ALLOWED=false
|
||||
- WEBSOCKET_ENABLED=true
|
||||
- LOG_FILE=/data/vaultwarden.log
|
||||
- LOG_LEVEL=warn
|
||||
```
|
||||
|
||||
**Key settings:**
|
||||
- `DOMAIN` — must match the public URL for correct invite links and CORS
|
||||
- `SIGNUPS_ALLOWED` — enable temporarily for account creation, disable after
|
||||
- `WEBSOCKET_ENABLED` — required for live sync with browser extensions
|
||||
- Bind to `127.0.0.1` — all access goes through nginx
|
||||
|
||||
## Nginx WebSocket Configuration
|
||||
|
||||
Vaultwarden uses WebSocket for the notifications hub. The nginx config needs a dedicated location block for `/notifications/hub` with `Upgrade` and `Connection` headers, plus a separate block for the negotiate endpoint:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 3446 ssl;
|
||||
server_name vault.graj-media.com;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/grajmedia.duckdns.org/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/grajmedia.duckdns.org/privkey.pem;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
client_max_body_size 128M;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8812;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
location /notifications/hub {
|
||||
proxy_pass http://127.0.0.1:8812;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
|
||||
location /notifications/hub/negotiate {
|
||||
proxy_pass http://127.0.0.1:8812;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Without the WebSocket blocks, browser extensions can't maintain a live sync connection — they'll work for manual syncs but won't push changes in real-time.
|
||||
|
||||
## Admin Token Setup
|
||||
|
||||
After first deployment, set the admin token via Docker environment variable. The token MUST be hashed with argon2id:
|
||||
|
||||
```bash
|
||||
# Generate random token
|
||||
ADMIN_TOKEN=$(openssl rand -hex 32)
|
||||
|
||||
# Hash with argon2id using the Vaultwarden container
|
||||
HASHED=$(echo -n "$ADMIN_TOKEN" | sudo docker exec -i vaultwarden /vaultwarden hash)
|
||||
|
||||
# Add to docker-compose.yml environment section
|
||||
# - ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'
|
||||
# Then restart: sudo docker compose up -d
|
||||
```
|
||||
|
||||
Access admin panel at `https://vault.graj-media.com/admin` — use the raw (unhashed) token to log in.
|
||||
|
||||
## Post-Deploy Steps
|
||||
|
||||
1. **Open signups temporarily**: set `SIGNUPS_ALLOWED=true`, restart container
|
||||
2. **Create user account**: visit https://vault.graj-media.com, register
|
||||
3. **Disable signups**: set `SIGNUPS_ALLOWED=false`, restart container
|
||||
4. **Configure Bitwarden apps**: Settings → Self-hosted → Server URL: `https://vault.graj-media.com`
|
||||
|
||||
## Bitwarden Client Setup
|
||||
|
||||
All official Bitwarden clients support self-hosted servers:
|
||||
- **Browser extension**: Settings → Self-Hosted Environment → Server URL
|
||||
- **Desktop app**: Settings → Self-Hosted Environment
|
||||
- **Mobile (iOS/Android)**: Settings → Self-Hosted Environment
|
||||
|
||||
Enter `https://vault.graj-media.com` as the server URL. No trailing slash.
|
||||
@@ -0,0 +1,151 @@
|
||||
# VPS Reverse Proxy Migration
|
||||
|
||||
Full pattern for migrating from port-forwarded home server to VPS reverse proxy with Tailscale tunnel.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Internet → VPS (nginx SSL, ports 80/443)
|
||||
↳ Tailscale tunnel (41641 UDP)
|
||||
↳ Home server (zero ports open to internet)
|
||||
```
|
||||
|
||||
## VPS Setup
|
||||
|
||||
### 1. Purchase VPS
|
||||
|
||||
OVH VPS Starter ($5/mo, 4GB RAM, 40GB NVMe, Ubuntu 26.04 LTS) or equivalent.
|
||||
|
||||
### 2. Install essentials
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt install -y nginx certbot python3-certbot-nginx curl ufw
|
||||
sudo ufw allow 80/tcp && sudo ufw allow 443/tcp && sudo ufw allow 22/tcp
|
||||
sudo ufw --force enable
|
||||
```
|
||||
|
||||
### 3. Install Tailscale
|
||||
|
||||
```bash
|
||||
curl -fsSL https://tailscale.com/install.sh | sudo sh
|
||||
sudo tailscale up --accept-routes --accept-dns=false
|
||||
# Authenticate at the URL shown
|
||||
```
|
||||
|
||||
Verify: `tailscale status` should show home server (`rayserver`) online.
|
||||
|
||||
### 4. Domain DNS (Porkbun)
|
||||
|
||||
Two A records:
|
||||
- `*` → VPS IP
|
||||
- `@` (root) → VPS IP
|
||||
|
||||
Via Porkbun API:
|
||||
```bash
|
||||
curl -X POST "https://api.porkbun.com/api/json/v3/dns/create/DOMAIN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"apikey":"pk1_...","secretapikey":"sk1_...","name":"*","type":"A","content":"VPS_IP","ttl":300}'
|
||||
```
|
||||
|
||||
Delete any default parking records (CNAME/ALIAS → uixie.porkbun.com) first.
|
||||
|
||||
### 5. Nginx reverse proxy template
|
||||
|
||||
Each service gets a subdomain config:
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name <name>.graj-media.com;
|
||||
client_max_body_size 500M;
|
||||
location / {
|
||||
proxy_pass http://100.93.253.36:<port>;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 86400;
|
||||
proxy_buffering off;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For services behind home nginx SSL (Mealie, ShopProQuote), use HTTPS proxy:
|
||||
```nginx
|
||||
proxy_pass https://100.93.253.36:3449;
|
||||
proxy_ssl_verify off;
|
||||
proxy_ssl_server_name on;
|
||||
proxy_ssl_name graj-media.com;
|
||||
```
|
||||
|
||||
### 6. SSL via Let's Encrypt
|
||||
|
||||
Single cert for all subdomains:
|
||||
```bash
|
||||
sudo certbot --nginx -d graj-media.com \
|
||||
-d immich.graj-media.com -d paperless.graj-media.com \
|
||||
-d ha.graj-media.com -d shopproquote.graj-media.com \
|
||||
-d mealie.graj-media.com -d audiobookshelf.graj-media.com
|
||||
```
|
||||
|
||||
Auto-renews via systemd timer.
|
||||
|
||||
### 7. LLM proxy (ShopProQuote)
|
||||
|
||||
Add `/llm/` location block to ShopProQuote config:
|
||||
```nginx
|
||||
location /llm/ {
|
||||
proxy_pass http://100.93.253.36:11434/;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_read_timeout 120;
|
||||
}
|
||||
```
|
||||
|
||||
### 8. Home Assistant trusted proxies
|
||||
|
||||
HA behind VPS reverse proxy returns 400 without trusted proxy config:
|
||||
```yaml
|
||||
http:
|
||||
use_x_forwarded_for: true
|
||||
trusted_proxies:
|
||||
- 127.0.0.1
|
||||
- 100.86.68.23 # VPS Tailscale IP
|
||||
```
|
||||
Restart: `docker restart homeassistant`
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Check all services from VPS
|
||||
for url in \
|
||||
https://graj-media.com \
|
||||
https://immich.graj-media.com \
|
||||
https://paperless.graj-media.com \
|
||||
https://ha.graj-media.com \
|
||||
https://shopproquote.graj-media.com \
|
||||
https://mealie.graj-media.com \
|
||||
https://audiobookshelf.graj-media.com; do
|
||||
curl -skL -o /dev/null -w "%{http_code} $url\n" $url
|
||||
done
|
||||
```
|
||||
|
||||
## Close home router ports
|
||||
|
||||
After verifying all services work via VPS, delete ALL port forwarding rules on the ASUS RT-AX82U router. Home server should have zero ports exposed.
|
||||
|
||||
```bash
|
||||
# Verify from outside
|
||||
for port in 80 443 2283 3443 3444 3445 3446 3447 3448 3449 3450 8010 8123 13378; do
|
||||
timeout 2 bash -c "echo >/dev/tcp/HOME_PUBLIC_IP/$port" 2>/dev/null && echo "PORT $port OPEN" || echo "PORT $port closed"
|
||||
done
|
||||
```
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Bash variable expansion in heredocs.** When writing nginx configs via `ssh host "sudo tee << 'EOF' ..."`, `$http_upgrade` and `$host` are expanded by the local shell despite the quoted EOF marker. Workaround: write to temp file locally, scp, or use sed to fix after writing.
|
||||
- **Certbot namespace collision.** Old certbot configs for DuckDNS domains conflict with new ones. Delete all old certs and configs before re-issuing for the new domain.
|
||||
- **Mealie direct port is localhost-only.** Mealie Docker binds `127.0.0.1:9925`, unreachable via Tailscale. Proxy through the home nginx SSL endpoint instead (`https://100.93.253.36:3449`).
|
||||
- **DuckDNS 5-domain limit.** Can't use subdomain-per-service with DuckDNS. A proper domain ($11/yr) with wildcard DNS is required.
|
||||
Reference in New Issue
Block a user