docs: add README with quickstart and deployment instructions
This commit is contained in:
171
README.md
Normal file
171
README.md
Normal file
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user