Shorefront

A production-ready web application for managing Shorewall 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)

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

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:

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

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

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

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

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