diff --git a/README.md b/README.md index d43948e..923de6b 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ The documentation is based only on stated facts. Missing details are recorded as - [Networking](docs/networking.md) - [Access](docs/access.md) - [Services](docs/services.md) +- [Hetzner VPS](docs/hetzner-vps.md) +- [Joplin Server](docs/joplin-server.md) - [Unknowns and clarification questions](docs/questions.md) ## Known facts @@ -38,6 +40,12 @@ The documentation is based only on stated facts. Missing details are recorded as - The homelab is behind NAT. - Public services are exposed through Nginx Proxy Manager with HTTPS certificates from Let's Encrypt. - Private access is provided through Tailscale. +- A Hetzner VPS handoff has been received from another Codex session. +- The Hetzner VPS hostname is `ubuntu-4gb-hel1-1`. +- The Hetzner VPS Tailscale IP is `100.95.58.48`. +- `100.108.208.3` is explicitly not the Hetzner VPS Tailscale IP. +- Nginx Proxy Manager is running on the Hetzner VPS as container `npm`. +- Joplin Server files exist on the Hetzner VPS, but Joplin is not running yet. ## Unknown / needs clarification @@ -45,9 +53,10 @@ The documentation is based only on stated facts. Missing details are recorded as - Storage layout and attached disks. - Network interface configuration. - LAN IP addresses. -- Public domain names. +- Public domain names for the Raspberry Pi 5 services. - List of all running containers. - Exact Nginx Proxy Manager proxy host configuration. - Tailscale tailnet, device name, and subnet/exit-node configuration if any. - Backup configuration. - Monitoring and alerting configuration. +- Whether the Hetzner VPS is part of the homelab, a separate public edge, or both. diff --git a/docs/hetzner-vps.md b/docs/hetzner-vps.md new file mode 100644 index 0000000..89f0c19 --- /dev/null +++ b/docs/hetzner-vps.md @@ -0,0 +1,79 @@ +# Hetzner VPS + +## Description + +This page documents facts received from the Codex session running on the Hetzner VPS / homelab server. + +The relationship between this VPS and the Raspberry Pi 5 homelab is not yet clarified. + +## Current configuration + +- Hostname: `ubuntu-4gb-hel1-1` +- Public IPv4: `135.181.153.108` +- Public IPv6: `2a01:4f9:c014:98f0::1` +- Tailscale IP: `100.95.58.48` +- Incorrect Tailscale IP explicitly ruled out: `100.108.208.3` + +Network interfaces reported: + +- `docker0`: `172.17.0.1/16`, `DOWN` +- `br-b467702c0f28`: `172.18.0.1/16`, `DOWN` +- `br-40cc27c6ea24`: `172.19.0.1/16`, `DOWN` + +Docker networks: + +- `bridge` +- `host` +- `none` +- `npm_default` +- `proxy` +- Planned after Joplin start: `joplin-net` + +Docker volumes: + +- No Docker named volumes currently exist. +- Planned after Joplin start: `joplin_postgres_data` + +Running containers: + +- `npm` + +## Known facts + +- `npm` uses image `jc21/nginx-proxy-manager:latest`. +- `npm` status was reported as `Up about an hour`. +- `npm` Compose path is `/home/dockeruser/docker/npm`. +- `npm` uses `network_mode: host`. +- Because `npm` uses host networking, Nginx Proxy Manager binds directly to host ports. +- Nginx Proxy Manager admin UI responds `200 OK` internally at `http://127.0.0.1:81`. +- Nginx Proxy Manager HTTP listener responds `200 OK` internally at `http://127.0.0.1:80`. +- Nginx Proxy Manager responded `200 OK` at `http://100.95.58.48:81`. +- Nginx Proxy Manager responded `200 OK` at `http://135.181.153.108:81`. +- Nginx config test passes. +- From a laptop/browser, the reported Nginx Proxy Manager admin UI URLs are: + - `http://100.95.58.48:81` over Tailscale + - `http://135.181.153.108:81` publicly if firewall allows it + +Nginx Proxy Manager Compose file: + +- Path: `/home/dockeruser/docker/npm/docker-compose.yml` +- Service: + - `container_name: npm` + - `image: jc21/nginx-proxy-manager:latest` + - `restart: unless-stopped` + - `network_mode: host` + - `TZ: Europe/Warsaw` + - Volumes: + - `./data:/data` + - `./letsencrypt:/etc/letsencrypt` + +## Unknown / needs clarification + +- Whether this Hetzner VPS is part of the homelab, a separate public edge, or both. +- Operating system version. +- Firewall rules. +- Whether port `81` is intentionally reachable on public IPv4. +- Whether ports `80` and `443` are publicly reachable from the internet. +- Whether any services other than `npm` are running outside Docker. +- Backup configuration. +- Monitoring and alerting configuration. diff --git a/docs/joplin-server.md b/docs/joplin-server.md new file mode 100644 index 0000000..95477a4 --- /dev/null +++ b/docs/joplin-server.md @@ -0,0 +1,132 @@ +# Joplin Server + +## Description + +This page documents the current Joplin Server state received from the Hetzner VPS Codex handoff. + +Joplin Server has been created on disk but is not running yet. + +## Current configuration + +- Compose path: `/home/dockeruser/docker/joplin-server` +- Files: + - `/home/dockeruser/docker/joplin-server/docker-compose.yml` + - `/home/dockeruser/docker/joplin-server/.env` + - `/home/dockeruser/docker/joplin-server/README.md` +- Current runtime state: not running +- `docker compose ps` in `/home/dockeruser/docker/joplin-server` shows no running services. +- Intended public URL: `https://joplin.okit.pl` + +Current DNS issue: + +- `joplin.okit.pl` did not resolve from user test. +- DNS needs to be created or fixed before public HTTPS works. + +## Known facts + +Joplin Compose design: + +- `app` + - `image: joplin/server:latest` + - `container_name: joplin-server` + - `restart: unless-stopped` + - `env_file: .env` + - Binds only to localhost: + - `127.0.0.1:22300:22300` + - Depends on `db` with condition `service_healthy` + - Network: `joplin-net` +- `db` + - `image: postgres:18` + - `container_name: joplin-db` + - `restart: unless-stopped` + - No exposed ports + - Network: `joplin-net` + - Volume: + - `postgres_data:/var/lib/postgresql/data` + - Healthcheck: + - `pg_isready` using `POSTGRES_USER` and `POSTGRES_DB` +- Named volume: + - `joplin_postgres_data` +- Named network: + - `joplin-net` + +Joplin `.env`: + +```env +POSTGRES_PASSWORD=CHANGE_ME_STRONG_PASSWORD +POSTGRES_USER=joplin +POSTGRES_DB=joplin +APP_PORT=22300 +APP_BASE_URL=https://joplin.okit.pl +DB_CLIENT=pg +POSTGRES_HOST=db +POSTGRES_PORT=5432 +``` + +Important notes from handoff: + +- `POSTGRES_PASSWORD` must be changed before first production start. +- Joplin is intentionally localhost-only. +- External access must go through Nginx Proxy Manager. +- Because Nginx Proxy Manager uses host networking, Nginx Proxy Manager should forward to `127.0.0.1:22300`. +- PostgreSQL is internal-only and should not be exposed publicly. + +Required Nginx Proxy Manager proxy host for Joplin: + +- Domain Names: `joplin.okit.pl` +- Scheme: `http` +- Forward Hostname / IP: `127.0.0.1` +- Forward Port: `22300` +- Websockets Support: enabled +- Block Common Exploits: enabled +- SSL: + - Request Let's Encrypt certificate + - Force SSL enabled + - HTTP/2 enabled + +DNS plan from handoff: + +- Create A record: + - `joplin.okit.pl -> 135.181.153.108` +- Optional AAAA record: + - `joplin.okit.pl -> 2a01:4f9:c014:98f0::1` +- For normal Let's Encrypt through Nginx Proxy Manager, ports `80` and `443` must reach this VPS publicly. +- Public DNS should not point to the Tailscale IP if using standard Let's Encrypt HTTP validation. + +Commands provided in handoff to start Joplin: + +```sh +cd /home/dockeruser/docker/joplin-server +nano .env +# replace POSTGRES_PASSWORD +docker compose up -d +docker compose ps +docker compose logs -f app +``` + +Local tests on VPS after Joplin start: + +```sh +curl -I http://127.0.0.1:22300 +curl -I http://127.0.0.1:81 +curl -I http://127.0.0.1:80 +``` + +Public tests after DNS and Nginx Proxy Manager config: + +```sh +dig joplin.okit.pl +curl -I https://joplin.okit.pl +``` + +## Unknown / needs clarification + +- Whether `POSTGRES_PASSWORD` has been changed from `CHANGE_ME_STRONG_PASSWORD`. +- Whether `docker compose up -d` has been run for Joplin. +- Whether `joplin_postgres_data` has been created. +- Whether `joplin-net` has been created. +- Whether `joplin.okit.pl` DNS has been created or fixed. +- Whether the optional AAAA record is intended. +- Whether the Nginx Proxy Manager proxy host for `joplin.okit.pl` has been created. +- Whether Let's Encrypt certificate issuance has succeeded. +- Whether ports `80` and `443` reach the Hetzner VPS publicly. diff --git a/docs/questions.md b/docs/questions.md index 7cc1ff6..d1e5226 100644 --- a/docs/questions.md +++ b/docs/questions.md @@ -15,6 +15,13 @@ The currently documented configuration is limited to: - `443` to `4443` - Public access through Nginx Proxy Manager with Let's Encrypt HTTPS. - Private access through Tailscale. +- Hetzner VPS handoff: + - Hostname: `ubuntu-4gb-hel1-1` + - Tailscale IP: `100.95.58.48` + - Public IPv4: `135.181.153.108` + - Public IPv6: `2a01:4f9:c014:98f0::1` + - Running container: `npm` + - Joplin files created but not running. ## Known facts @@ -48,3 +55,11 @@ The currently documented configuration is limited to: 23. Is Tailscale SSH enabled? 24. What backup system exists, if any? 25. What monitoring or alerting exists, if any? +26. Is the Hetzner VPS part of the homelab documentation scope, a separate system, or both? +27. What is the operating system version on `ubuntu-4gb-hel1-1`? +28. Is public Nginx Proxy Manager admin access on port `81` intentionally reachable on `135.181.153.108`? +29. Has DNS record `joplin.okit.pl -> 135.181.153.108` been created? +30. Has optional AAAA record `joplin.okit.pl -> 2a01:4f9:c014:98f0::1` been created? +31. Has `POSTGRES_PASSWORD=CHANGE_ME_STRONG_PASSWORD` been changed before first Joplin production start? +32. Has the Nginx Proxy Manager proxy host for `joplin.okit.pl` been created? +33. Are ports `80` and `443` publicly reachable on the Hetzner VPS for Let's Encrypt HTTP validation? diff --git a/docs/services.md b/docs/services.md index 1c7ac09..522190b 100644 --- a/docs/services.md +++ b/docs/services.md @@ -6,11 +6,19 @@ This page documents the currently known services in the homelab. ## Current configuration -Known services: +Known Raspberry Pi 5 services: - Portainer - Nginx Proxy Manager +Known Hetzner VPS services: + +- Nginx Proxy Manager + +Known Hetzner VPS service files: + +- Joplin Server + Known supporting platform: - Docker @@ -21,10 +29,12 @@ Known supporting platform: - Nginx Proxy Manager is present in the homelab. - Public services are exposed through Nginx Proxy Manager using HTTPS. - Private access is available through Tailscale. +- On the Hetzner VPS, Nginx Proxy Manager is running as container `npm`. +- On the Hetzner VPS, Joplin Server files have been created but the service is not running yet. ## Unknown / needs clarification -- Full list of running services and containers. +- Full list of running services and containers on the Raspberry Pi 5. - Service names. - Service purposes. - Public or private exposure for each service. @@ -38,3 +48,4 @@ Known supporting platform: - Health checks. - Backup coverage for each service. - Restore process for each service. +- Whether Joplin Server should be documented as part of the current homelab, as a VPS service, or both.