shorefront/README.md

# 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/`.

---

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

### Finding your token

Open a config in the UI. The **Download Token** field is shown above the tabs. Click the copy icon to copy it.

### Downloading via curl

```bash
curl -X POST "https://<host>/api/configs/<config-id>/generate?format=zip" \
  -H 'Content-Type: application/json' \
  -d '{"token": "<your-download-token>"}' \
  -o shorewall.zip
```

Replace `<config-id>` with the numeric ID visible in the URL when you open a config (e.g. `/configs/1`).

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

---

## 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
```