From 956f0c2cf5bea7b767010433b520eeaad787ec0b Mon Sep 17 00:00:00 2001 From: "Adrian A. Baumann" Date: Sat, 7 Mar 2026 12:36:11 +0100 Subject: [PATCH] docs: update README to reflect OIDC auth, secrets management, and CI/CD MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace admin/admin credentials with Keycloak OIDC flow, fix Kubernetes deploy section to use create-secrets.sh instead of --set secrets.*, add CI/CD section, and update domain model references (masq→snat, new hosts/params). --- README.md | 77 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 08c6f27..4a15de6 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ A production-ready web application for managing [Shorewall](http://shorewall.net - **Backend:** Python 3.12, FastAPI, SQLAlchemy 2, Alembic, PostgreSQL 15 - **Frontend:** React 18, TypeScript, Vite, MUI v5, React Router v6, Axios +- **Auth:** Keycloak (OIDC), JWT session cookie - **Infra:** Docker Compose (local dev), Helm + Kubernetes + Traefik (production) --- @@ -22,7 +23,7 @@ docker compose up --build # 3. Open http://localhost ``` -Default credentials: **admin** / **admin** — change on first login. +Authentication is handled via Keycloak OIDC. You will be redirected to your Keycloak instance to log in. Your Keycloak user must be a member of the **firewall admins** group. --- @@ -37,6 +38,11 @@ pip install -r requirements.txt # Set environment variables export DATABASE_URL=postgresql://shorefront:changeme@localhost:5432/shorefront export JWT_SECRET_KEY=dev-secret +export KEYCLOAK_URL=https://sso.example.com +export KEYCLOAK_REALM=myrealm +export KEYCLOAK_CLIENT_ID=shorefront +export KEYCLOAK_CLIENT_SECRET= +export KEYCLOAK_REDIRECT_URI=http://localhost:8000/auth/oidc/callback # Run migrations (creates schema + seed data) alembic upgrade head @@ -60,12 +66,12 @@ npm run dev ## First Steps After Login -1. Log in at `/login` with **admin** / **admin**. +1. Log in — you will be redirected to Keycloak. Your account must be in the **firewall admins** group. 2. A sample **homelab** config is pre-loaded with: - Zones: `fw` (firewall), `net` (ipv4), `loc` (ipv4) - Interface: `eth0` → zone `net` - Policies: loc→net ACCEPT, net→fw DROP, etc. - - Masq: `192.168.1.0/24` via `eth0` + - SNAT: `192.168.1.0/24` via `eth0` 3. Click **homelab** to open the Config Detail page. 4. Click **Generate Config** to preview or download the Shorewall files. 5. Create your own configs from the **Configurations** page. @@ -76,14 +82,14 @@ npm run dev On the Config Detail page, click **Generate Config**: -- **Preview:** File contents appear in a tabbed modal (zones / interfaces / policy / rules / masq) with copy-to-clipboard buttons. -- **Download ZIP:** Downloads `-shorewall.zip` with all five files ready to copy to `/etc/shorewall/`. +- **Preview:** File contents appear in a tabbed modal (zones / interfaces / policy / rules / snat) with copy-to-clipboard buttons. +- **Download ZIP:** Downloads `-shorewall.zip` with all files ready to copy to `/etc/shorewall/`. --- ## Command-Line Download -Each config has a **Download Token** — a secret string that allows downloading the generated ZIP without an OIDC session. This is useful for automation scripts and CI pipelines. +Each config has a **Download Token** — a secret string that allows downloading the generated ZIP without an active session. Useful for automation scripts and CI pipelines. ### Finding your token @@ -102,7 +108,7 @@ Replace `` with the numeric ID visible in the URL when you open a con ### Rotating the token -Click the **Regenerate** button (⟳) next to the token field. The old token is immediately invalidated. You will need to update any scripts that use it. +Click the **Regenerate** button (⟳) next to the token field. The old token is immediately invalidated. Update any scripts that use it. --- @@ -121,30 +127,34 @@ FastAPI generates interactive docs automatically: - Kubernetes cluster with Traefik as the ingress controller - NFS share accessible at `192.168.17.199:/mnt/user/kubernetesdata/shorefront` -- Images pushed to a container registry +- Keycloak instance with a `shorefront` client configured +- Images available in the container registry (see CI/CD below) -### Build and Push Images +### 1. Create Secrets + +Helm does **not** manage the Kubernetes secret. Run this once before the first deploy (and whenever credentials change): ```bash -docker build -t /shorefront-backend:latest ./backend -docker build -t /shorefront-frontend:latest ./frontend -docker push /shorefront-backend:latest -docker push /shorefront-frontend:latest +export POSTGRES_PASSWORD= +export JWT_SECRET_KEY= +export KEYCLOAK_CLIENT_SECRET= + +bash scripts/create-secrets.sh ``` -### Deploy +This creates/updates the `shorefront-secret` Secret in the `shorefront` namespace. + +### 2. Deploy ```bash helm upgrade --install shorefront ./helm/shorefront \ - --values ./helm/shorefront/values-prod.yaml \ - --set backend.image=/shorefront-backend \ - --set frontend.image=/shorefront-frontend \ - --set ingress.host=shorefront.yourdomain.com \ - --set secrets.postgresPassword= \ - --set secrets.jwtSecretKey= + --namespace shorefront \ + --create-namespace ``` -### Verify Rollout +Override values as needed (e.g. ingress host, Keycloak URL) via `--set` or a custom values file. + +### 3. Verify Rollout ```bash kubectl rollout status deployment/backend -n shorefront @@ -167,6 +177,18 @@ kubectl delete pv shorefront-postgres-pv --- +## CI/CD + +A Gitea Actions workflow (`.gitea/workflows/build-containers-on-demand.yml`) automatically builds and pushes images when `helm/shorefront/values.yaml`, `frontend/Dockerfile`, or `backend/Dockerfile` change. + +- Image tag is read from `containers.version` in `values.yaml` +- Images are pushed to `git.baumann.gr/adebaumann/shorefront-{frontend,backend}:` +- Requires a `REGISTRY_TOKEN` secret configured in Gitea + +**To release a new version:** bump `containers.version` in `values.yaml` and push. The workflow builds and pushes both images. Then run `helm upgrade` to deploy. + +--- + ## Project Structure ``` @@ -179,9 +201,18 @@ shorefront/ │ ├── main.py # FastAPI app │ ├── models.py # SQLAlchemy ORM models │ ├── schemas.py # Pydantic schemas -│ ├── auth.py # JWT auth +│ ├── auth.py # JWT + OIDC auth │ ├── shorewall_generator.py │ └── api/ # Route handlers +│ ├── auth.py # OIDC login/callback/logout +│ ├── configs.py # Config CRUD + generate +│ ├── zones.py +│ ├── interfaces.py +│ ├── policies.py +│ ├── rules.py +│ ├── snat.py +│ ├── hosts.py +│ └── params.py ├── frontend/ │ ├── Dockerfile │ ├── nginx.conf @@ -191,6 +222,8 @@ shorefront/ │ ├── routes/ # Page components │ └── components/ # Shared UI components ├── helm/shorefront/ # Kubernetes Helm chart +├── scripts/ +│ └── create-secrets.sh # Creates k8s Secret before deploy ├── docker-compose.yml └── README.md ```