From 2ef0918b772dfa41de8e31ea1dc179f9d3ba22c6 Mon Sep 17 00:00:00 2001 From: XShine555 Date: Mon, 21 Sep 2026 19:45:46 +0200 Subject: [PATCH] Rewrite README in English Turn the root README into a proper project overview: what the app does today, the stack, how to run it locally and the current status, instead of the short Spanish setup notes it had before. Replace the generic SvelteKit scaffold README in frontend/ with a short one that actually describes this client. --- README.md | 80 ++++++++++++++++++++++++++++++++-------------- frontend/README.md | 39 ++++++---------------- 2 files changed, 65 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index fdac19b..6db2543 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,72 @@ # Docker Manager -WebApp centralizada para gestionar instancias Docker (Musify, bot de Discord, etc.) desde un único sitio: recursos, logs, consola. Ver [Plan-DockerManager-WebApp.md](../Plan-DockerManager-WebApp.md) para la arquitectura completa y el roadmap. +A web app for keeping track of Docker containers running on a home server +from a single dashboard, instead of jumping between SSH sessions and `docker +ps`. Built for personal infrastructure: a handful of self-hosted services and +side projects running on one box. + +## What it does right now + +- Lists every container on the local Docker host, running or stopped, with + its image, state and status. +- A small health check endpoint so the API itself can be monitored. + +This is early: a single host, read-only, no login yet. The plan is to grow +it into something that can watch several hosts, show logs and a live +console, and act on containers (start, stop, restart) behind proper +authentication. ## Stack -- **Backend:** Go (`chi`, SDK oficial de Docker, `pgx`, `zitadel/oidc`, `coder/websocket`) -- **Frontend:** SvelteKit + Tailwind CSS v4 -- **Auth:** Zitadel (patrón BFF) -- **DB:** PostgreSQL -- **Archivos:** SeaweedFS (S3) +**Backend**: Go, using `chi` for routing, the official Docker SDK to talk to +the engine, `pgx` for Postgres and `zitadel/oidc` and `coder/websocket` for +what's coming next (auth and live log streaming). -## Arrancar en desarrollo +**Frontend**: SvelteKit with Tailwind CSS v4. + +**Auth** (planned): Zitadel, with the backend-for-frontend pattern so tokens +never reach the browser. + +**Database**: PostgreSQL, for hosts, tracked services and an audit log. + +**File storage** (planned): SeaweedFS, S3 compatible. + +Everything ships as Docker Compose for local development: Postgres, Zitadel +and SeaweedFS run as infrastructure while the Go API and the SvelteKit app +run directly on the host for fast iteration. + +## Project layout + +``` +backend/ Go API: HTTP router, config, the Docker connector, SQL migrations +frontend/ SvelteKit app +deploy/ docker-compose.dev.yml and Postgres init scripts +``` + +## Running it locally ```bash -# 1. Infraestructura (Postgres + Zitadel + SeaweedFS) make dev-infra - -# 2. Backend (puerto 8090 — el 8080 puede estar ocupado por otros servicios) cp backend/.env.example backend/.env make backend - -# 3. Frontend (puerto 5173) make frontend ``` -Backend: http://localhost:8090/healthz · http://localhost:8090/api/containers -Frontend: http://localhost:5173 +That brings up Postgres, Zitadel and SeaweedFS, then starts the API on +`http://localhost:8090` and the frontend on `http://localhost:5173`. The API +port is 8090 instead of the usual 8080 because that one is often already +taken by something else on the same machine. -## Estado (Fase 1) +Useful endpoints while developing: `/healthz` and `/api/containers`. -- [x] Estructura del monorepo (`backend/`, `frontend/`, `deploy/`) -- [x] Backend Go: router `chi`, config por env vars, healthcheck -- [x] `HostConnector` / `LocalConnector`: listado de contenedores del host vía SDK oficial de Docker -- [x] Frontend SvelteKit + Tailwind consumiendo `/api/containers` -- [x] `docker-compose.dev.yml` con Postgres + Zitadel + SeaweedFS -- [x] Migraciones iniciales (`hosts`, `services`, `audit_log`) -- [ ] Auth OIDC contra Zitadel (patrón BFF) — siguiente paso -- [ ] Persistencia de hosts/services en Postgres vía backend -- [ ] Acciones sobre contenedores (start/stop/restart) + logs en vivo +## Status + +- [x] Monorepo layout (`backend/`, `frontend/`, `deploy/`) +- [x] Go backend: `chi` router, env based config, health check +- [x] `HostConnector` / `LocalConnector`: container listing via the Docker SDK +- [x] Frontend consuming `/api/containers` +- [x] Dev infrastructure with Postgres, Zitadel and SeaweedFS +- [x] Initial schema (`hosts`, `services`, `audit_log`) +- [ ] OIDC login against Zitadel (BFF pattern) +- [ ] Persisting hosts and services through the backend +- [ ] Container actions (start/stop/restart) and live logs diff --git a/frontend/README.md b/frontend/README.md index 41cbfdf..af62599 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,42 +1,21 @@ -# sv +# frontend -Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli). +The Docker Manager web client: SvelteKit, Svelte 5 runes, TypeScript and +Tailwind CSS v4. Talks to the Go API at `$lib/api.ts`. -## Creating a project - -If you're seeing this, you've probably already done this step. Congrats! +## Development ```sh -# create a new project -npx sv create my-app +npm install +npm run dev # :5173 ``` -To recreate this project with the same configuration: - -```sh -# recreate this project -npx sv@0.17.0 create --template minimal --types ts --install npm frontend -``` - -## Developing - -Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server: - -```sh -npm run dev - -# or start the server and open the app in a new browser tab -npm run dev -- --open -``` +The backend needs to be running for the container list to load, see the +root [README](../README.md) for how to start it. ## Building -To create a production version of your app: - ```sh npm run build +npm run preview ``` - -You can preview the production build with `npm run preview`. - -> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.