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) - [Networking](docs/networking.md)
- [Access](docs/access.md) - [Access](docs/access.md)
- [Services](docs/services.md) - [Services](docs/services.md)
- [Hetzner VPS](docs/hetzner-vps.md)
- [Joplin Server](docs/joplin-server.md)
- [Unknowns and clarification questions](docs/questions.md) - [Unknowns and clarification questions](docs/questions.md)
## Known facts ## Known facts
@ -38,6 +40,12 @@ The documentation is based only on stated facts. Missing details are recorded as
- The homelab is behind NAT. - The homelab is behind NAT.
- Public services are exposed through Nginx Proxy Manager with HTTPS certificates from Let's Encrypt. - Public services are exposed through Nginx Proxy Manager with HTTPS certificates from Let's Encrypt.
- Private access is provided through Tailscale. - 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 ## 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. - Storage layout and attached disks.
- Network interface configuration. - Network interface configuration.
- LAN IP addresses. - LAN IP addresses.
- Public domain names. - Public domain names for the Raspberry Pi 5 services.
- List of all running containers. - List of all running containers.
- Exact Nginx Proxy Manager proxy host configuration. - Exact Nginx Proxy Manager proxy host configuration.
- Tailscale tailnet, device name, and subnet/exit-node configuration if any. - Tailscale tailnet, device name, and subnet/exit-node configuration if any.
- Backup configuration. - Backup configuration.
- Monitoring and alerting 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` - `443` to `4443`
- Public access through Nginx Proxy Manager with Let's Encrypt HTTPS. - Public access through Nginx Proxy Manager with Let's Encrypt HTTPS.
- Private access through Tailscale. - 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 ## Known facts
@ -48,3 +55,11 @@ The currently documented configuration is limited to:
23. Is Tailscale SSH enabled? 23. Is Tailscale SSH enabled?
24. What backup system exists, if any? 24. What backup system exists, if any?
25. What monitoring or alerting 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 ## Current configuration
Known services: Known Raspberry Pi 5 services:
- Portainer - Portainer
- Nginx Proxy Manager - Nginx Proxy Manager
Known Hetzner VPS services:
- Nginx Proxy Manager
Known Hetzner VPS service files:
- Joplin Server
Known supporting platform: Known supporting platform:
- Docker - Docker
@ -21,10 +29,12 @@ Known supporting platform:
- Nginx Proxy Manager is present in the homelab. - Nginx Proxy Manager is present in the homelab.
- Public services are exposed through Nginx Proxy Manager using HTTPS. - Public services are exposed through Nginx Proxy Manager using HTTPS.
- Private access is available through Tailscale. - 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 ## 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 names.
- Service purposes. - Service purposes.
- Public or private exposure for each service. - Public or private exposure for each service.
@ -38,3 +48,4 @@ Known supporting platform:
- Health checks. - Health checks.
- Backup coverage for each service. - Backup coverage for each service.
- Restore process 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.