62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
# Beach
|
|
|
|
A one-page control panel for a homelab. One binary, one SQLite file, and everything is done in the web UI.
|
|
|
|
| Section | Source |
|
|
|---|---|
|
|
| **Containers** | Docker Engine API: state, ports, health, start / stop / restart, last 200 log lines |
|
|
| **Pools, disks, SMART** | TrueNAS REST API (`/api/v2.0`: pools, scrub state, disks, temperatures, alerts), and/or local `smartctl` |
|
|
| **Host** | CPU, memory, swap, load, uptime and mounted filesystems from `/proc` (Linux) |
|
|
| **Tunnels & sites** | [Hammerhead](../hammerhead)'s `GET /api/orgs/{org}/state`: site agents online/offline, port mappings up/down, target health |
|
|
|
|
A section appears only when it is configured, and one failing source never takes down the page: it shows its own error.
|
|
|
|
It is built in the same style as Hammerhead, Blacktip, Bamboo and Sandbar, but has no dependency on Reef.
|
|
|
|
## Quick start
|
|
|
|
```
|
|
go build -o bin/ ./cmd/beach
|
|
bin/beach -listen :8095 -data beach.db
|
|
```
|
|
|
|
Open `http://localhost:8095`, create the administrator account, then open **Settings**:
|
|
|
|
- **Docker**: the socket path (default `/var/run/docker.sock`) or `tcp://host:2375`. Beach must be able to read the socket.
|
|
- **TrueNAS**: the URL and an API key (Credentials → API Keys). Tick "self-signed certificate" if needed.
|
|
- **smartctl**: reads SMART from the machine Beach runs on (needs `smartmontools` and permission to open the devices). Results are merged with TrueNAS by serial number.
|
|
- **Hammerhead**: the URL, your organization ID and an API key for that organization. Read access is enough.
|
|
|
|
There are two flags only: `-listen` and `-data`. There is no config file or environment variable.
|
|
|
|
## Running in Docker
|
|
|
|
Mount the Docker socket (this gives the container control of Docker, which is what the start/stop buttons need) and, for host metrics, run it with the host's `/proc` visible:
|
|
|
|
```
|
|
docker run -d --name beach -p 127.0.0.1:8095:8095 -v beach:/data \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
beach -data /data/beach.db
|
|
```
|
|
|
|
(There is no published image yet: build one from `go build` output in a `scratch`/`distroless` image.)
|
|
|
|
## Security notes
|
|
|
|
- Sign-in is a name and password (bcrypt), with a 30-day session cookie (`HttpOnly`, `SameSite=Strict`, `Secure` behind HTTPS) and a lockout after 8 failed attempts per address in 5 minutes. Every write needs an `X-Beach` header.
|
|
- Anyone who can sign in can start, stop and restart every container and read its logs. Put Beach behind Hammerhead/Blacktip or bind it to `127.0.0.1`; do not expose it plainly.
|
|
- API keys for TrueNAS and Hammerhead are stored in the SQLite file as plain text (they are never sent back to the browser). Protect the file like the keys themselves.
|
|
- Beach only reads from TrueNAS and Hammerhead.
|
|
|
|
## Development
|
|
|
|
```
|
|
go test ./...
|
|
```
|
|
|
|
The collectors parse recorded API shapes and `/proc` text, so the tests run anywhere. Host collection itself is Linux only (`host_linux.go`); other platforms report just the CPU count.
|
|
|
|
## License
|
|
|
|
MIT, see [LICENSE](LICENSE).
|