inspired-by-atmosphere/ops-troubleshooting-skills/home-server-deployment

Home Server Deployment (自建服务部署)

Deploy and operate self-hosted services (cloud drive, database, file aggregator, mesh VPN, messaging) on a home/LAN Linux server, driven remotely from a Windows laptop over SSH. Covers China-network constraints and the user's actual stack (小服务器 your-server, Ubuntu 22.04, 8核/15G/329G).

Remote control from Windows laptop (git-bash)

• SSH key auth: ssh -i ~/.ssh/id_ed25519_<host> <user>@<server-lan-ip> (免密已配). Non-interactive SSH does NOT load ~/.bashrc → custom-path binaries (Node/Go/npm in ~/.node/bin, ~/.go/bin) are not on PATH; use full paths or export PATH.
• sudo over SSH: sudo -S with a piped password is BLOCKED by the terminal security guard (brute-force prevention). Do NOT try to work around it (askpass hacks). Sanctioned path: user runs ONE sudoers command once on the server (they choose), then the agent uses sudo -n freely:

``bash echo "<user> ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/<user> sudo chmod 440 /etc/sudoers.d/<user> ``

• pkill self-kill trap (caused SSH exit 255 twice this session): pkill -f "docker pull X" matches your OWN remote shell's command line — the pattern literal appears inside your command — killing your SSH session mid-run. Never put pkill -f and the bare target string in the same command. Use the bracket trick pkill -f "[d]ocker pull X" AND make sure no other part of the command (printf, echo) contains the un-bracketed string.
• MSYS/git-bash quirks: taskkill /F /PID n needs MSYS_NO_PATHCONV=1 prefix (bare /F gets path-converted); PowerShell $_ is mangled by MSYS path conversion → write a .ps1 file and run powershell -File instead; Chinese console output → pipe iconv -f GBK -t UTF-8.
• scp to root-owned dirs (/srv, /opt) fails → keep compose/config in ~/<app>-deploy/; docker creates the data volumes itself.
• Fresh Ubuntu has apache2 on :80 → sudo systemctl stop apache2 && sudo systemctl disable apache2 before binding port 80.

China network / Docker images

Docker Hub is unreachable from CN servers. Registry mirrors are required — see references/china-docker-mirrors.md for install + testing + a measured mirror status table. Key rules:

• Test per-image mirror support via curl to /v2/<repo>/manifests/<tag> (401 = proxied, 404 = not proxied).
• Public mirrors have allowlists (daocloud rejected seafileltd/*); docker.1ms.run worked for Seafile.
• Some images publish NO latest tag → query Docker Hub API for real tags (via laptop + HTTPS_PROXY).
• Large pulls: write a script, launch setsid nohup ... & so it survives SSH drops; poll docker images; docker pull resumes completed layers on retry. Transient unexpected EOF → kill + retry.
• Ubuntu 22.04 docker-compose-plugin is NOT in the Ubuntu repo → install docker-ce + plugin from Docker's apt repo via 阿里云 mirror.

Credentials convention

All passwords/keys for deployed services go in %USERPROFILE%\AppData\Local\hermes\ (the Hermes secrets dir — ~/.ssh/ is write-protected by the system). Name files <app>-pass, <app>-admin-pass, <app>-jwt-key. Keep only a pointer (file path) in memory/viking, never the password text itself.

Service recipes

• Seafile Pro (docker-compose MC, 13.x): license-free for ≤3 users (built into image — NO customer.seafile.com application needed; that flow is outdated). Full env/.env/redis requirements + symptom→cause map: references/seafile-pro-docker-compose.md. Working template: templates/seafile-docker-compose.yml.
• Alist: docker run -d --name alist --restart=always -p 5244:5244 -v /srv/alist:/opt/alist/data xhofe/alist:latest; admin pw: docker exec alist ./alist admin set <pw>. Baidu Netdisk mount uses Alist's official shared client_id/secret + QR authorize (NO Baidu open-platform application needed).
• PostgreSQL: docker run -d --name postgres --restart=always -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=<pw> -p 127.0.0.1:5432:5432 -v /srv/postgres:/var/lib/postgresql/data postgres:16-alpine (bind 127.0.0.1 only — never expose).
• Tailscale: official install script works in CN (curl -fsSL https://tailscale.com/install.sh | sh; github.com blocked but tailscale.com/pkgs reachable). Auth flow: sudo tailscale up in background, read log for https://login.tailscale.com/a/..., user approves in browser, node joins. Stale/offline nodes need manual deletion in the admin console.

Verification discipline

• docker compose config --quiet validates YAML before up.
• Poll docker ps/docker logs, don't sleep-and-hope.
• Seafile first-boot symptom progression (each maps to a root cause): nginx 502 → seahub not started → 500 (missing redis) → 302 login page = DONE.
• Compose up after a failed first start may leave a container without port bindings → docker compose up -d --force-recreate <svc>.