From 1de797492119b1a7b2f7653e9b052e8a9b213ed1 Mon Sep 17 00:00:00 2001
From: "Adrian A. Baumann" <ade@adebaumann.com>
Date: Sat, 28 Feb 2026 21:20:24 +0100
Subject: [PATCH] docs: add README with quickstart and deployment instructions

---
 README.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 171 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..45f7492
--- /dev/null
+++ b/README.md
@@ -0,0 +1,171 @@
+# Shorefront
+
+A production-ready web application for managing [Shorewall](http://shorewall.net/) firewall configurations.
+
+## Stack
+
+- **Backend:** Python 3.12, FastAPI, SQLAlchemy 2, Alembic, PostgreSQL 15
+- **Frontend:** React 18, TypeScript, Vite, MUI v5, React Router v6, Axios
+- **Infra:** Docker Compose (local dev), Helm + Kubernetes + Traefik (production)
+
+---
+
+## Quick Start (Docker Compose)
+
+```bash
+# 1. Clone and enter the repo
+git clone <repo-url> shorefront && cd shorefront
+
+# 2. Start everything (postgres + backend + frontend)
+docker compose up --build
+
+# 3. Open http://localhost
+```
+
+Default credentials: **admin** / **admin** — change on first login.
+
+---
+
+## Development (without Docker)
+
+**Backend:**
+```bash
+cd backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+# Set environment variables
+export DATABASE_URL=postgresql://shorefront:changeme@localhost:5432/shorefront
+export JWT_SECRET_KEY=dev-secret
+
+# Run migrations (creates schema + seed data)
+alembic upgrade head
+
+# Start the API server
+uvicorn app.main:app --reload
+# API available at http://localhost:8000
+# Interactive docs at http://localhost:8000/docs
+```
+
+**Frontend:**
+```bash
+cd frontend
+npm install
+npm run dev
+# Vite dev server at http://localhost:5173
+# Proxies /api/* → http://localhost:8000
+```
+
+---
+
+## First Steps After Login
+
+1. Log in at `/login` with **admin** / **admin**.
+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`
+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.
+
+---
+
+## Generating Shorewall Files
+
+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/`.
+
+---
+
+## API Documentation
+
+FastAPI generates interactive docs automatically:
+
+- **Swagger UI:** `http://localhost:8000/docs`
+- **ReDoc:** `http://localhost:8000/redoc`
+
+---
+
+## Kubernetes Deployment (Helm)
+
+### Prerequisites
+
+- 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
+
+### Build and Push Images
+
+```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
+```
+
+### 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>
+```
+
+### Verify Rollout
+
+```bash
+kubectl rollout status deployment/backend -n shorefront
+kubectl rollout status deployment/frontend -n shorefront
+kubectl get ingress -n shorefront
+```
+
+### Storage
+
+PostgreSQL data is persisted to `192.168.17.199:/mnt/user/kubernetesdata/shorefront` via a static NFS PersistentVolume. Ensure the NFS export is accessible from all cluster nodes before deploying.
+
+### Uninstall
+
+```bash
+helm uninstall shorefront -n shorefront
+# Note: PersistentVolume (Retain policy) and namespace are NOT deleted automatically.
+kubectl delete namespace shorefront
+kubectl delete pv shorefront-postgres-pv
+```
+
+---
+
+## Project Structure
+
+```
+shorefront/
+├── backend/
+│   ├── Dockerfile
+│   ├── requirements.txt
+│   ├── alembic/              # DB migrations
+│   └── app/
+│       ├── main.py           # FastAPI app
+│       ├── models.py         # SQLAlchemy ORM models
+│       ├── schemas.py        # Pydantic schemas
+│       ├── auth.py           # JWT auth
+│       ├── shorewall_generator.py
+│       └── api/              # Route handlers
+├── frontend/
+│   ├── Dockerfile
+│   ├── nginx.conf
+│   └── src/
+│       ├── api.ts            # Axios API client
+│       ├── store/auth.ts     # Auth state
+│       ├── routes/           # Page components
+│       └── components/       # Shared UI components
+├── helm/shorefront/          # Kubernetes Helm chart
+├── docker-compose.yml
+└── README.md
+```