Getting Started (Developer)

Guide for setting up a local development environment.

TIP

For end-user login instructions, see User Guides › Getting Started.

Prerequisites

• Node.js 22+
• pnpm 10+
• Docker & Docker Compose

Quick Setup

make setup    # Install deps + start DB + run migrations + seed data
make dev      # Start all development servers

Manual Setup

# 1. Install dependencies
pnpm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your credentials

# 3. Start infrastructure
make db-start    # PostgreSQL + Redis + pgAdmin

# 4. Build packages
pnpm build

# 5. Run migrations and seed data
make db-migrate
make db-seed
# Optional: seed demo hospital data for sales demos
make db-seed-demo

# 6. Start development
pnpm dev

Development Services

Service	URL
API Server	http://localhost:3000/trpc
HR System	http://localhost:4000
Admin Panel	http://localhost:4001
Employee App	http://localhost:4002
Nurse Scheduler	http://localhost:4003
Internal Approval	http://localhost:4004
General Affairs	http://localhost:4005
Management Dashboard	http://localhost:4006
Inventory	http://localhost:4007
Module Manager	http://localhost:4010
System Admin API	http://localhost:4100
System Admin UI	http://localhost:4101
PostgreSQL	localhost:5432
pgAdmin	http://localhost:5050 (admin@hereby.platform / admin123)
Redis	localhost:6379

Test Credentials

After make db-seed:

Role	Email	Password
Admin	admin@hereby.com	admin123
Developer	dev.lee@hereby.com	dev123
HR Manager	hr.kim@hereby.com	hr123
Sales	sales.park@hereby.com	sales123

After make db-seed-demo:

Demo hospital organization DEMO_HOSP with nurses, PTs, admin — all passwords demo1234!.

Common Commands

# Development
pnpm dev                              # All servers
pnpm --filter @hereby/api dev         # API only
pnpm --filter @hereby/hr-system dev   # HR system only

# Build
pnpm build                            # All packages + apps

# Code Quality
pnpm lint:check                       # Check lint
pnpm lint:fix                         # Auto-fix lint issues
pnpm format                           # Format with Biome

# Testing
pnpm test                             # All tests
pnpm test:integration                 # Integration tests

# Database
make db-start / db-stop / db-restart
make db-migrate / db-seed / db-seed-demo / db-shell
make db-generate name=MigrationName    # generate a migration from the entity diff (wrapper)

# Migrations via raw TypeORM CLI (note the -d data-source flag)
pnpm --filter @hereby/database typeorm migration:create -- src/migrations/<Name>       # hand-written (empty) migration
pnpm --filter @hereby/database typeorm migration:show   -d src/config/data-source.ts   # list migrations ([ ] = pending)
pnpm --filter @hereby/database typeorm migration:revert -d src/config/data-source.ts   # undo the last migration

# Documentation
make docs-dev                         # Start docs dev server
make docs-build                       # Build docs site

Environment Variables

Key variables (see .env.example for full list):

# Database
DB_HOST=localhost          DB_PORT=5432
DB_NAME=hereby_platform    DB_USERNAME=hereby_admin
DB_PASSWORD=<secure>
DB_SSL=false               # Enable for production

# Redis
REDIS_HOST=localhost       REDIS_PORT=6379

# JWT
JWT_SECRET=<long-secure>   JWT_EXPIRES_IN=24h

# API
API_PORT=3000

# Timezone
TZ=Asia/Seoul

# Notifications (optional)
FCM_SERVICE_ACCOUNT_KEY=<path>
WEB_PUSH_PUBLIC_KEY=<vapid-public>
WEB_PUSH_PRIVATE_KEY=<vapid-private>

# System Admin Tool — login uses an operator account (platformRole=OPERATOR)
# on the target endpoint; there is no env-based console account.
SYSADMIN_PORT=4100
SYSADMIN_JWT_SECRET=<secure>          # Signs console session tokens; required in prod
SYSADMIN_ALLOWED_IPS=                 # Comma-separated exact IPs (no CIDR); empty = localhost only

Running a Specific App

# Web apps (standard)
pnpm --filter @hereby/hr-system dev
pnpm --filter @hereby/admin dev
pnpm --filter @hereby/employee-app dev

# Importer (CLI)
pnpm --filter @hereby/importer import --sheet=employees
pnpm --filter @hereby/importer import --sheet=payroll

# System Admin Tool (server + UI concurrently)
pnpm --filter @hereby/system-admin dev

# Employee App — Capacitor native builds
pnpm --filter @hereby/employee-app cap:sync
pnpm --filter @hereby/employee-app cap:ios
pnpm --filter @hereby/employee-app cap:android

Troubleshooting

Database connection fails

docker-compose ps           # Check containers are running
make db-logs               # View PostgreSQL logs
make db-restart            # Restart everything

Build cache issues

pnpm clean && pnpm install && pnpm build

Docs site warnings about missing deps

pnpm --filter @hereby/docs install