Update readme

2025-11-06 16:05:33 +00:00
parent f1dc375c5f
commit 28815d3b25
4 changed files with 174 additions and 10 deletions
@@ -0,0 +1,144 @@
+# Crussell
+
+Crussell is a **full‑stack application** that powers a nail‑bar / salon booking service.  The repository is split into a **Go** backend and a **SvelteKit** front‑end, both of which are containerised with Docker.  A lightweight **SabreDAV** instance is also exposed so that the salon can offer WebDAV access to clients.
+
+## 📦 Project Structure
+
+```
+Crussell/
+├─ backend/            # Go 1.22 + chi router API
+├─ frontend/           # SvelteKit SPA
+├─ sabredav/           # PHP + Composer for DAV
+├─ nginx/              # Nginx reverse‑proxy for HTTP & HTTPS
+├─ init-scripts/       # PostgreSQL init SQL
+├─ compose.yml         # Docker‑Compose definition
+├─ local-dev.sh        # Development helper using tmux
+└─ README.md
+```
+
+## ⚙️ Prerequisites
+
+| Tool | Version |
+|------|---------|
+| Docker & Docker‑Compose | ≥ 20.10 |
+| Go | ≥ 1.22 |
+| Node ≥ 18 | `npm` |
+| tmux | ≥ 3.0 |
+
+> **Tip**: If you already have Docker Desktop or Docker Engine installed, you are good to go.
+
+## 📥 Getting Started
+
+```bash
+# Clone the repository
+git clone http://git.popertots.com/popertots/Crussell.git
+cd Crussell
+
+# Copy the example environment file and edit it
+cp .env.example .env
+# Open .env and provide values for POSTGRES_*, JWT_SECRET_KEY, etc.
+```
+
+### Docker‑Compose
+
+The simplest way to bring the whole stack up is with Docker‑Compose.
+
+```bash
+docker compose up --build -d
+```
+
+> `postgres` – PostgreSQL 17
+> `backend` – Go API (exposed on `:8080`)
+> `sabredav` – PHP‑based WebDAV (served by Nginx)
+> `nginx` – Reverse‑proxy (HTTP on `:80` and HTTPS on `:443`)
+
+After the containers are running, the front‑end is reachable at `http://localhost`.  The API is available at `http://localhost/api`.  SabreDAV can be accessed via `http://localhost/dav`.
+
+### Development with `local-dev.sh`
+
+For a more interactive dev experience the repository ships a small helper script that launches Docker, starts a tmux session with three panes (PostgreSQL console, Go dev server, Svelte dev server) and seeds the database with an admin and a regular user plus a handful of sample services.
+
+```bash
+chmod +x local-dev.sh
+./local-dev.sh
+```
+
+The script performs the following steps:
+
+1. **Docker checks** – starts Docker if it isn’t already running.
+2. **PostgreSQL reset** – removes the old volume and starts a fresh container.
+3. **tmux session** – creates `crussell-dev` with panes:
+   * `psql` console
+   * Go server (`go run -tags dev ./main.go`)
+   * Svelte dev server (`npm run dev -- --host`)
+4. **Seeding** – creates an admin (`admin@example.com`) and a regular user (`user@example.com`), updates the admin role, and registers six example services.
+
+> **Note**: The script uses a temporary shell script to perform the HTTP calls, so no external tooling like `jq` is required.
+
+## 🔧 Building & Testing
+
+### Backend
+
+```bash
+cd backend
+# Build the binary
+go build -o bin/backend ./main.go
+```
+
+The binary is then copied into the Docker image via the `Dockerfile`.
+
+### Frontend
+
+```bash
+cd frontend
+npm ci
+npm run build   # Production build
+npm run dev     # Development server
+```
+
+### SabreDAV
+
+SabreDAV is bundled with PHP‑FPM and Composer.  The Docker image installs dependencies automatically during the container start‑up.
+
+## 📂 Environment Variables
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `POSTGRES_USER` | DB username | `myuser` |
+| `POSTGRES_PASSWORD` | DB password | `mysecret` |
+| `POSTGRES_DB` | DB name | `mydb` |
+| `JWT_SECRET_KEY` | HMAC key for JWT | `supersecret` |
+| `SABRE_DAV_*` | Optional SabreDAV overrides | – |
+
+Create a `.env` file in the project root based on the provided `.env.example`.
+
+## 📊 Seeding Data
+
+The `local-dev.sh` script automatically seeds:
+
+* Admin user (`admin@example.com` / `password`)
+* Regular user (`user@example.com` / `password`)
+* Six example nail‑bar services
+
+If you want to seed manually, use the provided `init-scripts/init-script.sql` and your favourite Postgres client.
+
+## 📌 Useful Commands
+
+```bash
+# Show Docker containers
+docker ps
+
+# Rebuild the Go binary and restart containers
+make build-backend
+docker compose up -d backend
+
+# Tail logs
+docker compose logs -f
+
+# Open a shell inside the backend container
+docker compose exec backend sh
+```
+
+---
+
+**Happy coding!**