Skip to content

Commit 22e48cc

Browse files
codeGlazecodeGlaze
authored
docs: getting started guide, env var docs, dev SIGNATURE default
Add docs/GETTING-STARTED.md with full clone-to-running walkthrough for devcontainer, local machine, and REPL workflows. Add dev SIGNATURE to :dev profile :env in project.clj so lein repl works with auth out of the box. README quick start rewritten as compact stubs pointing to the full guide. ENVIRONMENT.md updated with .lein-env sourcing notes and SIGNATURE marked as required.
1 parent f46b956 commit 22e48cc

5 files changed

Lines changed: 270 additions & 22 deletions

File tree

‎.env.example‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,17 @@ DATOMIC_PASSWORD=change-me-datomic
2121
DATOMIC_URL=datomic:dev://datomic:4334/orcpub?password=change-me-datomic
2222

2323
# --- Security ---
24-
# Secret used to sign JWT tokens (20+ characters recommended)
24+
# REQUIRED: JWT signing secret. Authentication will fail without this.
25+
# 20+ random characters recommended (e.g., openssl rand -hex 16)
2526
SIGNATURE=change-me-to-something-unique-and-long
2627

2728
# Content Security Policy (strict|permissive|none)
2829
CSP_POLICY=strict
2930

31+
# Dev mode: CSP violations are logged (Report-Only) instead of blocked,
32+
# allowing Figwheel hot-reload scripts to execute.
33+
DEV_MODE=true
34+
3035
# --- Logs ---
3136
# Defaults to project logs/ if unset
3237
LOG_DIR=

‎README.md‎

Lines changed: 39 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,38 @@ Dungeon Master's Vault is a full-stack Clojure/ClojureScript web application for
4242

4343
## Quick Start
4444

45-
### Using Docker (self-hosting)
45+
### Development (devcontainer)
4646

47-
For running your own instance from pre-built images:
47+
The fastest path. Requires [VS Code](https://code.visualstudio.com/) with [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), or [GitHub Codespaces](https://github.com/features/codespaces).
48+
49+
```bash
50+
git clone https://github.com/orcpub/orcpub.git
51+
cd orcpub && code .
52+
# Click "Reopen in Container" when prompted, then:
53+
./scripts/dev-setup.sh # Install deps, init DB, create test user
54+
./menu # Interactive service launcher
55+
```
56+
57+
### Development (local machine)
58+
59+
Requires Java 21, Leiningen 2.9+, and Datomic Pro (free, Apache 2.0).
60+
61+
```bash
62+
git clone https://github.com/orcpub/orcpub.git
63+
cd orcpub
64+
cp .env.example .env # Dev defaults work out of the box
65+
./scripts/dev-setup.sh # Install deps, start Datomic, init DB, create test user
66+
./menu start server # Backend on port 8890
67+
./menu start figwheel # Frontend hot-reload on port 3449
68+
```
69+
70+
Log in at `http://localhost:8890` with **test@test.com** / **testpass**.
71+
72+
For the full walkthrough (including manual setup without scripts), see **[docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)**.
73+
74+
### Self-hosting (Docker)
75+
76+
For running your own production instance from pre-built images:
4877

4978
1. Clone the repository
5079
2. Copy `.env.example` to `.env` and edit the values (see [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md))
@@ -54,21 +83,6 @@ For running your own instance from pre-built images:
5483

5584
See the [Docker deployment section](#docker-deployment) for full details.
5685

57-
### Using the Devcontainer (development)
58-
59-
The fastest way to start developing. Requires [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), or [GitHub Codespaces](https://github.com/features/codespaces).
60-
61-
1. Open the repository in VS Code
62-
2. When prompted, click **Reopen in Container** (or run the command manually)
63-
3. The container builds automatically, installing Java 21, Leiningen, and Datomic Pro
64-
4. Once built, use the interactive menu:
65-
66-
```bash
67-
./menu
68-
```
69-
70-
The menu gives you one-keystroke access to start Datomic, initialize the database, launch the backend, and start Figwheel for frontend hot-reload.
71-
7286
---
7387

7488
## Development
@@ -257,13 +271,19 @@ Key variables:
257271
| Variable | Purpose | Default |
258272
|----------|---------|---------|
259273
| `DATOMIC_URL` | Database connection string | `datomic:dev://localhost:4334/orcpub` |
260-
| `SIGNATURE` | JWT signing secret | (must set) |
274+
| `SIGNATURE` | JWT signing secret (**required**) | dev default in `.lein-env` |
261275
| `PORT` | Web server port | `8890` |
262276
| `EMAIL_SERVER_URL` | SMTP server | (optional) |
263277
| `CSP_POLICY` | Content Security Policy mode | `strict` |
264278
| `DEV_MODE` | Enable dev features | `true` in dev |
265279

266-
See [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) for the full list.
280+
**How env vars are loaded:**
281+
282+
- **`./menu` and `./scripts/start.sh`** source `.env` automatically — recommended for most workflows.
283+
- **`lein repl` / `lein run`** read dev defaults from `.lein-env` (generated by `lein-environ` from the `:dev` profile). This includes a dev-only `SIGNATURE` so auth works out of the box.
284+
- **`.env` values** (via scripts) and **real env vars** override `.lein-env` defaults.
285+
286+
See [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) for the full list and precedence rules.
267287

268288
---
269289

‎docs/ENVIRONMENT.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,15 @@ All configuration is managed via a `.env` file at the repository root. Copy `.en
88
2. `containerEnv` in `.devcontainer/devcontainer.json` (fallback defaults)
99
3. System environment variables
1010

11+
> **Note:** `./menu` and `./scripts/start.sh` source `.env` automatically (via `scripts/common.sh`).
12+
> Running `lein` commands directly (e.g., `lein repl`, `lein run`) reads dev defaults
13+
> from `.lein-env` (generated by `lein-environ` from the `:dev` profile in `project.clj`).
14+
> This includes `SIGNATURE` so auth works out of the box for local development.
15+
> To use your `.env` values with `lein` directly:
16+
> ```bash
17+
> source .env && lein repl
18+
> ```
19+
1120
## Variables
1221
1322
### Datomic
@@ -24,7 +33,7 @@ All configuration is managed via a `.env` file at the repository root. Copy `.en
2433
| Variable | Default | Description |
2534
|----------|---------|-------------|
2635
| `PORT` | `8080` | Production web server port (dev uses 8890) |
27-
| `SIGNATURE` | — | JWT signing secret for authentication |
36+
| `SIGNATURE` | — | **Required.** JWT signing secret for authentication. All login and API calls fail without it. |
2837
| `ADMIN_PASSWORD` | — | Admin password |
2938
3039
### Security

‎docs/GETTING-STARTED.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Getting Started
2+
3+
This guide takes you from a fresh clone to a running dev server. Two paths are covered:
4+
5+
1. **Devcontainer** (recommended) - everything installs automatically
6+
2. **Local machine** - you install Java, Leiningen, and Datomic yourself
7+
8+
Both paths end at the same place: Datomic running, backend serving on port 8890, and Figwheel hot-reloading the frontend.
9+
10+
---
11+
12+
## Path 1: Devcontainer
13+
14+
Requires [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), or [GitHub Codespaces](https://github.com/features/codespaces).
15+
16+
### 1. Open in container
17+
18+
```bash
19+
git clone https://github.com/orcpub/orcpub.git
20+
cd orcpub
21+
code .
22+
```
23+
24+
When VS Code prompts **"Reopen in Container"**, click it. The container installs Java 21, Leiningen, and Datomic Pro automatically.
25+
26+
### 2. Run first-time setup
27+
28+
Once the container is built, open a terminal inside VS Code:
29+
30+
```bash
31+
./scripts/dev-setup.sh
32+
```
33+
34+
This will:
35+
- Download project dependencies (`lein deps`)
36+
- Start the Datomic transactor
37+
- Initialize the database schema
38+
- Create a test user: **test** / **test@test.com** / **testpass**
39+
40+
### 3. Start services
41+
42+
```bash
43+
./menu
44+
```
45+
46+
The interactive menu shows service status and lets you start/stop with single keystrokes. Or start individually:
47+
48+
```bash
49+
./menu start server # Backend on port 8890
50+
./menu start figwheel # Frontend hot-reload on port 3449
51+
```
52+
53+
### 4. Open the app
54+
55+
Navigate to `http://localhost:8890` (or the Codespaces forwarded URL). Log in with **test@test.com** / **testpass**.
56+
57+
---
58+
59+
## Path 2: Local Machine
60+
61+
### 1. Prerequisites
62+
63+
| Tool | Version | Install |
64+
|------|---------|---------|
65+
| Java | 21+ (OpenJDK) | [Adoptium](https://adoptium.net/) |
66+
| Leiningen | 2.9+ | [leiningen.org](https://leiningen.org/#install) |
67+
| Datomic Pro | 1.0.7482 | See below |
68+
69+
**Datomic Pro** is free (Apache 2.0 license). The devcontainer installer handles this automatically, but on a local machine you need to install it manually:
70+
71+
```bash
72+
# The install script downloads and extracts Datomic Pro
73+
./.devcontainer/post-create.sh
74+
```
75+
76+
Or follow the manual steps in [docs/migration/datomic-pro.md](migration/datomic-pro.md). Datomic should end up at `lib/com/datomic/datomic-pro/1.0.7482/`.
77+
78+
### 2. Configure environment
79+
80+
```bash
81+
cp .env.example .env
82+
```
83+
84+
Edit `.env` if needed. The defaults work for local development. The most important variable is `SIGNATURE` (JWT secret) -a dev default is provided automatically via `.lein-env`, so this step is optional for local dev.
85+
86+
See [ENVIRONMENT.md](ENVIRONMENT.md) for the full variable list.
87+
88+
### 3. Download dependencies
89+
90+
```bash
91+
lein deps
92+
```
93+
94+
### 4. Start Datomic
95+
96+
```bash
97+
./scripts/start.sh datomic
98+
```
99+
100+
Wait for "Datomic is ready" before continuing. The transactor listens on port 4334.
101+
102+
### 5. Initialize the database
103+
104+
First time only -creates the schema and applies seed data:
105+
106+
```bash
107+
./scripts/start.sh init-db
108+
```
109+
110+
### 6. Create a test user
111+
112+
```bash
113+
./menu add test testpass
114+
```
115+
116+
This creates **test@test.com** with password **testpass**, already verified.
117+
118+
### 7. Start the backend
119+
120+
```bash
121+
./scripts/start.sh server
122+
```
123+
124+
The server starts on port 8890 with an nREPL port for editor connections.
125+
126+
### 8. Start Figwheel (frontend hot-reload)
127+
128+
In a separate terminal:
129+
130+
```bash
131+
./scripts/start.sh figwheel
132+
```
133+
134+
Figwheel compiles ClojureScript and serves it on port 3449. Changes to `.cljs` files are pushed to the browser automatically.
135+
136+
### 9. Open the app
137+
138+
Navigate to `http://localhost:8890`. Log in with **test@test.com** / **testpass**.
139+
140+
---
141+
142+
## Using the REPL directly
143+
144+
If you prefer `lein repl` over the shell scripts:
145+
146+
```bash
147+
lein repl
148+
```
149+
150+
The `user` namespace loads automatically with helpers:
151+
152+
```clojure
153+
(start-server) ; Start web server on port 8890
154+
(stop-server) ; Stop web server
155+
(init-database) ; Initialize DB schema (first time)
156+
(fig-start) ; Start Figwheel from the REPL
157+
(cljs-repl) ; Connect to ClojureScript REPL (after fig-start)
158+
```
159+
160+
The `:dev` profile provides a dev `SIGNATURE` via `.lein-env`, so auth works without extra setup. If you need to override with your `.env` values:
161+
162+
```bash
163+
source .env && lein repl
164+
```
165+
166+
---
167+
168+
## Verification
169+
170+
After starting services, confirm everything is working:
171+
172+
| Check | Expected |
173+
|-------|----------|
174+
| `http://localhost:8890` loads | Splash page appears |
175+
| Log in with test@test.com / testpass | Character list page |
176+
| Create a new character | Builder loads with race/class options |
177+
| Edit and wait 7.5 seconds | Autosave (check Network tab for POST) |
178+
| Upload a `.orcbrew` file (My Content page) | Homebrew options appear in builder |
179+
180+
---
181+
182+
## Troubleshooting
183+
184+
**Server returns 500 on login or API calls**
185+
186+
The `SIGNATURE` env var is missing. If using `./menu` or `./scripts/start.sh`, check that `.env` exists and has `SIGNATURE` set. If using `lein repl`, the dev profile provides a default -but if you've overridden it with an empty value, auth will fail.
187+
188+
**Datomic won't start**
189+
190+
- Check that port 4334 isn't already in use: `lsof -i :4334`
191+
- Verify Datomic is installed: `ls lib/com/datomic/datomic-pro/1.0.7482/bin/transactor`
192+
- Check logs: `cat logs/datomic.log`
193+
194+
**Figwheel compilation errors**
195+
196+
- Run `lein fig:build` for a one-shot compile to see all errors
197+
- First compilation can be slow (1-2 minutes) as it downloads ClojureScript dependencies
198+
199+
**Port already in use**
200+
201+
```bash
202+
./scripts/stop.sh # Stop all services
203+
./scripts/stop.sh server # Stop just the server
204+
```
205+
206+
---
207+
208+
## What's next
209+
210+
- [Architecture overview](../README.md#architecture) -how entities, templates, and modifiers work
211+
- [Dev tooling guide](migration/dev-tooling.md) -Leiningen profiles, REPL helpers, build commands
212+
- [Environment variables](ENVIRONMENT.md) -full config reference
213+
- [Stack migration context](MIGRATION-INDEX.md) -why Java 21, Datomic Pro, React 18, etc.

‎project.clj‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,8 @@
212212
[cider/piggieback "0.5.3"]
213213
[day8.re-frame/re-frame-10x "1.11.0" :exclusions [zprint rewrite-clj]]
214214
]
215-
:env {:dev-mode "true"}
215+
:env {:dev-mode "true"
216+
:signature "dev-secret-do-not-use-in-production"}
216217
;; need to add dev source path here to get user.clj loaded
217218
:source-paths ["web/cljs" "src/clj" "src/cljc" "src/cljs" "dev"]
218219
:cljsbuild {:builds {:dev {:compiler {:closure-defines {"re_frame.trace.trace_enabled_QMARK_" true

0 commit comments

Comments
 (0)