oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Document Hetzner VPS handoff

Browse source
This commit is contained in:
Oskar Kapala 2026-04-15 17:46:42 +02:00
parent a1a74f30ba
commit 03281b989a
5 changed files with 249 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
README.md
View file

@ -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.

79
docs/hetzner-vps.md Normal file
View file

@ -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.

132
docs/joplin-server.md Normal file
View file

@ -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.

15
docs/questions.md
View file

@ -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?

15
docs/services.md
View file

@ -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.