docs: update README to reflect OIDC auth, secrets management, and CI/CD
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).
This commit is contained in:
77
README.md
77
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=<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 `<config-name>-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 `<config-name>-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 `<config-id>` 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 <registry>/shorefront-backend:latest ./backend
|
||||
docker build -t <registry>/shorefront-frontend:latest ./frontend
|
||||
docker push <registry>/shorefront-backend:latest
|
||||
docker push <registry>/shorefront-frontend:latest
|
||||
export POSTGRES_PASSWORD=<strong-password>
|
||||
export JWT_SECRET_KEY=<strong-jwt-secret>
|
||||
export KEYCLOAK_CLIENT_SECRET=<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=<registry>/shorefront-backend \
|
||||
--set frontend.image=<registry>/shorefront-frontend \
|
||||
--set ingress.host=shorefront.yourdomain.com \
|
||||
--set secrets.postgresPassword=<strong-password> \
|
||||
--set secrets.jwtSecretKey=<strong-jwt-secret>
|
||||
--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}:<version>`
|
||||
- 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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user