# 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).