From 28815d3b255f5994d9465fdb6bec8b54b7f84ecc Mon Sep 17 00:00:00 2001 From: Stephen Adamson Date: Thu, 6 Nov 2025 16:05:33 +0000 Subject: [PATCH] Update readme --- .env.example | 13 +++ .gitignore | 1 - README.md | 144 ++++++++++++++++++++++++++++++ obsidian/.obsidian/workspace.json | 26 ++++-- 4 files changed, 174 insertions(+), 10 deletions(-) create mode 100644 .env.example create mode 100644 README.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..4142bfa --- /dev/null +++ b/.env.example @@ -0,0 +1,13 @@ +# Database Credentials for all services + +# These are used by the 'postgres' service to initialize the database +# These are used by 'backend' (Go) and 'sabredav' (PHP) +POSTGRES_USER=myuser +POSTGRES_PASSWORD=mypassword +POSTGRES_DB=mydb + +# and to connect to the 'postgres' service on the Docker network +POSTGRES_HOST=postgres +POSTGRES_PORT=5432 + +JWT_SECRET_KEY="a-very-secret-key-that-should-be-in-env" diff --git a/.gitignore b/.gitignore index 8cc5910..519e784 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,6 @@ # Environment/Secrets files .env -.env.* .env_shared */.env */.env.* diff --git a/README.md b/README.md new file mode 100644 index 0000000..3586fe3 --- /dev/null +++ b/README.md @@ -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!** diff --git a/obsidian/.obsidian/workspace.json b/obsidian/.obsidian/workspace.json index 265d451..204fef5 100644 --- a/obsidian/.obsidian/workspace.json +++ b/obsidian/.obsidian/workspace.json @@ -4,17 +4,21 @@ "type": "split", "children": [ { - "id": "af94f814e06296f9", + "id": "f918f140cb277962", "type": "tabs", "children": [ { - "id": "7ac1561c78f61154", + "id": "7fe99991d0e457c6", "type": "leaf", "state": { - "type": "empty", - "state": {}, + "type": "markdown", + "state": { + "file": "Express.js Cheat Sheet.md", + "mode": "preview", + "source": false + }, "icon": "lucide-file", - "title": "New tab" + "title": "Express.js Cheat Sheet" } } ] @@ -74,7 +78,8 @@ } ], "direction": "horizontal", - "width": 300 + "width": 300, + "collapsed": true }, "right": { "id": "2750d7726f904ef3", @@ -90,7 +95,7 @@ "state": { "type": "backlink", "state": { - "file": "Crussell/Crussell Nails.md", + "file": "Express.js Cheat Sheet.md", "collapseAll": false, "extraContext": false, "sortOrder": "alphabetical", @@ -100,7 +105,7 @@ "unlinkedCollapsed": true }, "icon": "links-coming-in", - "title": "Backlinks for Crussell Nails" + "title": "Backlinks for Express.js Cheat Sheet" } }, { @@ -165,8 +170,11 @@ "bases:Create new base": false } }, - "active": "7ac1561c78f61154", + "active": "7fe99991d0e457c6", "lastOpenFiles": [ + "Untitled.base", + "Untitled.canvas", + "Express.js Cheat Sheet.md", "Crussell/Crussell Nails.md", "Crussell/Backend/bookings.md" ]