Skip to content

docs(readme): document Docker dev workflow and make shortcuts #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WhiteMuush merged 1 commit into from
Jun 26, 2026
Merged

docs(readme): document Docker dev workflow and make shortcuts #98

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 25 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,23 +47,31 @@ Early development. Things move fast and not everything listed below is finished.

## Getting started

Prerequisites: Node.js 22 (pinned via `.nvmrc` and `engines`; run `nvm use`),
and Docker (for the local database) or your own PostgreSQL instance.
The quickest path needs only Docker, no Node on the host. It builds the app,
starts PostgreSQL, applies migrations and seeds demo data in one command.

```bash
# 1. Install dependencies
npm install
make env # create .env.local with generated secrets
docker compose up # app on http://localhost:3000, database seeded
```

# 2. Configure the environment
cp .env.example .env.local # then edit AUTH_SECRET (npx auth secret)
### Running on the host

# 3. Start the database, apply migrations and seed demo data
npm run db:init
Prerequisites: Node.js 22 (pinned via `.nvmrc` and `engines`) and Docker for the
local database, or your own PostgreSQL instance. The `make` targets select the
pinned Node version automatically via nvm, so they work even when your shell's
default Node differs.

# 4. Run the development server
npm run dev
```bash
make setup # install deps, create .env.local, start DB, migrate, seed
make run # start the dev server
```

`make doctor` diagnoses the setup (toolchain, env, Docker, DB, Prisma) and can
auto-fix common issues, including creating `.env.local` and switching to Node 22.
The underlying npm steps (`npm install`, `npm run db:init`, `npm run dev`) still
work if you prefer them.

Open http://localhost:3000 and sign in with the seeded admin account:

```
Expand All @@ -72,10 +80,13 @@ admin@datashield.local / ChangeMe123!

### Switching machines / after `git pull`

The Prisma client is regenerated automatically on `npm install` (`postinstall`).
The database is **not** migrated automatically: `npm run dev` only *warns* if
migrations are pending (it never applies them on boot). After pulling changes
that add a migration, apply it explicitly before running the app:
With `docker compose up`, migrations and the demo seed run on every start, so a
fresh machine is ready right after `git pull`.

On the host, the Prisma client is regenerated automatically on `npm install`
(`postinstall`). The database is **not** migrated automatically: `npm run dev`
only *warns* if migrations are pending (it never applies them on boot). After
pulling changes that add a migration, apply it explicitly before running the app:

```bash
npm run db:migrate # prisma migrate deploy, applies pending migrations
Expand Down