Skip to content

Commit 9d23482

Browse files
chrishaciachrishacia
committed
docs: add onboarding and developer guides
1 parent 1b2fa60 commit 9d23482

4 files changed

Lines changed: 347 additions & 69 deletions

File tree

‎GITHUB_SECRETS.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# GitHub Secrets Setup Guide
22

3-
Quick reference for setting up GitHub Actions secrets for automated deployment.
3+
This is the exact repository secret contract used by `.github/workflows/ci.yml` for production deploys.
44

55
## Navigate to Secrets
66

@@ -45,6 +45,11 @@ Quick reference for setting up GitHub Actions secrets for automated deployment.
4545
| `ADMIN_EMAIL` | Initial admin email | Your admin email |
4646
| `ADMIN_PASSWORD` | Initial admin password | Create a strong password |
4747

48+
Important:
49+
50+
- The workflow injects `NEXTAUTH_SECRET` into both `NEXTAUTH_SECRET` and `AUTH_SECRET` in production.
51+
- You do not need to create a separate `AUTH_SECRET` repository secret for the current deploy workflow.
52+
4853
---
4954

5055
## Generate Values
@@ -116,12 +121,12 @@ ADMIN_PASSWORD=MySecureP@ssw0rd!2024
116121

117122
These are optional and have sensible defaults:
118123

119-
| Name | Description | Default |
120-
| -------------------- | ------------------------------ | -------------- |
121-
| `APP_PORT` | Host port for the application | `3000` |
122-
| `CSRF_SECRET` | CSRF protection secret | Auto-generated |
123-
| `DOCKERHUB_USERNAME` | For Docker Hub instead of GHCR | Uses GHCR |
124-
| `DOCKERHUB_TOKEN` | Docker Hub access token | Uses GHCR |
124+
| Name | Description | Default |
125+
| -------------------- | ------------------------------ | -------------------------------------- |
126+
| `APP_PORT` | Host port for the application | `3000` |
127+
| `CSRF_SECRET` | CSRF protection secret | Not currently wired into deploy output |
128+
| `DOCKERHUB_USERNAME` | For Docker Hub instead of GHCR | Uses GHCR |
129+
| `DOCKERHUB_TOKEN` | Docker Hub access token | Uses GHCR |
125130

126131
---
127132

@@ -138,6 +143,13 @@ After adding all secrets, you can verify by:
138143

139144
## Troubleshooting
140145

146+
### Missing secret names or mismatched values
147+
148+
- Copy the names exactly as they appear above.
149+
- `SITE_URL` must include `https://`.
150+
- `DEPLOY_PATH` must already exist on the server.
151+
- `APP_PORT` must match your nginx upstream port.
152+
141153
### "Permission denied" SSH error
142154

143155
- Ensure the public key is in server's `~/.ssh/authorized_keys`

‎README.md‎

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,18 @@ See [docs/architecture.md](docs/architecture.md) for the full picture.
3636
```bash
3737
pnpm install
3838
cp .env.example .env # fill in DB + auth secrets
39-
pnpm db:migrate
39+
pnpm db:setup
4040
pnpm seed:admin
4141
pnpm dev
4242
```
4343

44-
See [docs/getting-started.md](docs/getting-started.md) for the complete guide.
44+
Optional demo content:
45+
46+
```bash
47+
pnpm db:seed:demo
48+
```
49+
50+
See [docs/getting-started.md](docs/getting-started.md) for the full quick start and [docs/developer-guide.md](docs/developer-guide.md) for the framework workflow.
4551

4652
---
4753

@@ -52,10 +58,10 @@ Edit `devholm.config.ts` and the files in `src/user/`:
5258
```typescript
5359
// devholm.config.ts
5460
const config: DevHolmConfig = {
55-
content: { about, home, now }, // Your narrative content
56-
slots: { 'home.hero.below': MyBanner }, // Inject components into views
57-
views: { 'about': () => import('./src/user/views/about/AboutView') }, // Eject & override
58-
extensions: { admin: myExtensions }, // Add admin sidebar items
61+
content: { about, home, now }, // Your narrative content
62+
slots: { 'home.hero.below': MyBanner }, // Inject components into views
63+
views: { about: () => import('./src/user/views/about/AboutView') }, // Eject & override
64+
extensions: { admin: myExtensions }, // Add admin sidebar items
5965
};
6066
```
6167

@@ -77,18 +83,20 @@ See [docs/cli.md](docs/cli.md).
7783

7884
## Documentation
7985

80-
| Doc | Description |
81-
|---|---|
82-
| [Getting Started](docs/getting-started.md) | Installation and first setup |
83-
| [Architecture](docs/architecture.md) | Layer model, directory structure, aliases |
84-
| [Configuration](docs/configuration.md) | Full `devholm.config.ts` reference |
85-
| [Extensions](docs/extensions.md) | Slots, admin extensions, view overrides, migrations |
86-
| [CLI](docs/cli.md) | All CLI commands |
87-
| [Upgrading](docs/upgrading.md) | How to update DevHolm safely |
86+
| Doc | Description |
87+
| ------------------------------------------ | ------------------------------------------------------ |
88+
| [Getting Started](docs/getting-started.md) | Installation and first setup |
89+
| [Developer Guide](docs/developer-guide.md) | Local workflow, boundaries, seeds, and extension rules |
90+
| [Architecture](docs/architecture.md) | Layer model, directory structure, aliases |
91+
| [Configuration](docs/configuration.md) | Full `devholm.config.ts` reference |
92+
| [Extensions](docs/extensions.md) | Slots, admin extensions, view overrides, migrations |
93+
| [CLI](docs/cli.md) | All CLI commands |
94+
| [Upgrading](docs/upgrading.md) | How to update DevHolm safely |
95+
| [Deployment](DEPLOYMENT.md) | Server setup and production deployment |
96+
| [GitHub Secrets](GITHUB_SECRETS.md) | Required repository secrets for CI/CD deploys |
8897

8998
---
9099

91-
92100
- **Blog System** — Markdown support, tags, series, reading time, RSS feed
93101
- **Projects Portfolio** — Showcase your work with images and links
94102
- **Resume/CV** — Display your professional experience

‎docs/developer-guide.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# DevHolm Developer Guide
2+
3+
This guide explains how to work inside DevHolm without breaking the upgrade model.
4+
5+
## The core rule
6+
7+
DevHolm is designed so framework updates land in the framework layer, while your site continues to live in site-owned paths.
8+
9+
Use this split:
10+
11+
- `src/core/` is framework-owned.
12+
- `src/user/` is site-owned.
13+
- `src/app/` should stay thin and routing-focused.
14+
- `devholm.config.ts` is the contract between framework and site.
15+
16+
If you need a new capability for a site, the first question should be: should DevHolm expose a new seam for this?
17+
18+
## Working model
19+
20+
### Framework-owned code
21+
22+
These are the files DevHolm can safely evolve upstream:
23+
24+
- `src/core/**`
25+
- most of `src/app/**`
26+
- framework scripts such as `scripts/devholm-cli.ts`
27+
- shared database and seed wiring such as `knexfile.js`
28+
29+
Avoid editing these directly for site-specific behavior.
30+
31+
### Site-owned code
32+
33+
These are the places a downstream site should customize:
34+
35+
- `devholm.config.ts`
36+
- `src/user/content/**`
37+
- `src/user/extensions/**`
38+
- `src/user/views/**`
39+
- `src/user/extensions/db/migrations/**`
40+
- `src/user/extensions/db/seeds/**`
41+
42+
If a site feature requires custom admin UI, custom API endpoints, custom migrations, or custom seeds, it should land here.
43+
44+
## Local development workflow
45+
46+
Typical daily loop:
47+
48+
```bash
49+
pnpm install
50+
pnpm db:setup
51+
pnpm seed:admin
52+
pnpm dev
53+
```
54+
55+
Useful validation commands:
56+
57+
```bash
58+
pnpm typecheck
59+
pnpm test
60+
pnpm build
61+
```
62+
63+
## Database model
64+
65+
DevHolm separates seeds into explicit buckets:
66+
67+
- `bootstrap` seeds: framework-required baseline records
68+
- `demo` seeds: optional sample content
69+
- `user` seeds: site-owned content or operational data
70+
71+
Relevant commands:
72+
73+
```bash
74+
pnpm db:migrate
75+
pnpm db:seed
76+
pnpm db:seed:bootstrap
77+
pnpm db:seed:demo
78+
pnpm db:seed:user
79+
pnpm db:setup
80+
```
81+
82+
Guidance:
83+
84+
- Put framework-required records in `src/core/db/seeds/bootstrap/`.
85+
- Put generic sample content in `src/core/db/seeds/demo/`.
86+
- Put real site data or operational site seeds in `src/user/extensions/db/seeds/`.
87+
88+
## Extension model
89+
90+
DevHolm supports several safe extension surfaces.
91+
92+
### Content changes
93+
94+
Use `src/user/content/` for About, Home, Now, and similar typed content.
95+
96+
### Slots
97+
98+
Use slots when you need to inject small UI pieces into core views without taking over the full page.
99+
100+
Start by finding available slots:
101+
102+
```bash
103+
pnpm devholm list:slots
104+
```
105+
106+
### View overrides
107+
108+
Use ejected views only when a slot is not enough.
109+
110+
```bash
111+
pnpm devholm eject about
112+
```
113+
114+
Once ejected, the view becomes site-owned and no longer auto-tracks upstream changes.
115+
116+
### Admin extensions
117+
118+
Put custom admin navigation and pages under `src/user/extensions/admin/`.
119+
120+
### API extensions
121+
122+
Put custom API handlers under `src/user/extensions/api/` and register them through the extension registry.
123+
124+
### Database extensions
125+
126+
Put site migrations and seeds under `src/user/extensions/db/`.
127+
128+
## CLI workflow
129+
130+
DevHolm ships with a CLI for common site tasks:
131+
132+
```bash
133+
pnpm devholm status
134+
pnpm devholm list:slots
135+
pnpm devholm eject <view>
136+
pnpm devholm new:extension <name>
137+
pnpm devholm new:migration <name>
138+
pnpm devholm new:seed <name>
139+
```
140+
141+
Use the CLI to stay inside the framework conventions instead of inventing custom file shapes.
142+
143+
## How to decide where code belongs
144+
145+
Use this test:
146+
147+
- If the behavior should exist for every DevHolm site, it belongs in DevHolm.
148+
- If the behavior is specific to one site, it belongs in `src/user/`.
149+
- If a site-specific feature currently requires patching framework files, DevHolm probably needs a new extension seam.
150+
151+
## Upgrade-safe rules
152+
153+
To keep downstream upgrades boring:
154+
155+
- do not put site business logic in `src/core/`
156+
- do not put site routing mechanics directly into `src/app/` when an extension seam should exist
157+
- do not store real site data in core demo seeds
158+
- prefer `src/user/` registrations over framework patches
159+
- keep `devholm.config.ts` as the place where site wiring happens
160+
161+
## Deployment model
162+
163+
The production workflow is GitHub Actions driven.
164+
165+
- GitHub Actions builds and publishes the Docker image.
166+
- The deploy job generates `docker-compose.override.yml` from repository secrets.
167+
- The server runs the app container and points it at the host PostgreSQL instance.
168+
169+
Read these before first deployment:
170+
171+
- [Quick Start](./getting-started.md)
172+
- [GitHub Secrets](../GITHUB_SECRETS.md)
173+
- [Deployment](../DEPLOYMENT.md)
174+
175+
## GitHub Actions secrets
176+
177+
The deploy workflow expects these repository secrets:
178+
179+
- `PROJECT_NAME`
180+
- `SITE_URL`
181+
- `SITE_NAME`
182+
- `DEPLOY_HOST`
183+
- `DEPLOY_USER`
184+
- `DEPLOY_KEY`
185+
- `DEPLOY_PATH`
186+
- `POSTGRES_USER`
187+
- `POSTGRES_PASSWORD`
188+
- `POSTGRES_DB`
189+
- `NEXTAUTH_SECRET`
190+
- `ADMIN_EMAIL`
191+
- `ADMIN_PASSWORD`
192+
193+
Optional:
194+
195+
- `APP_PORT`
196+
- `CSRF_SECRET`
197+
198+
Important note:
199+
200+
- The workflow uses `NEXTAUTH_SECRET` and also maps it into `AUTH_SECRET` inside the generated production compose override.
201+
202+
## Recommended onboarding order for contributors
203+
204+
1. Read [Quick Start](./getting-started.md).
205+
2. Read [Architecture](./architecture.md).
206+
3. Read [Configuration](./configuration.md).
207+
4. Read [Extensions](./extensions.md).
208+
5. Read [GitHub Secrets](../GITHUB_SECRETS.md) and [Deployment](../DEPLOYMENT.md) if you are touching CI/CD.

0 commit comments

Comments
 (0)
⚡