Installation Guide
Get Staffora running locally in minutes. Supports Docker (recommended) and manual setup.
Prerequisites
Ensure the following tools are installed before you begin.
Bun 1.1.38+
Package manager and runtime
PostgreSQL 16
Primary database
Redis 7
Cache and queues
Docker + Compose
Containers (recommended)
Quick Start (Docker -- Recommended)
The fastest way to get up and running. Docker Compose handles PostgreSQL, Redis, PgBouncer, API, and the frontend.
# Clone the repository
git clone https://github.com/staffora-hris/HRISystem.git
cd HRISystem
# Copy environment config
cp docker/.env.example docker/.env
# Start all services (PostgreSQL, Redis, PgBouncer, API, Web)
docker compose -f docker/docker-compose.yml up -d
# Run database migrations
bun run migrate
# Bootstrap root admin user
bun run --cwd packages/api src/scripts/bootstrap-root.cli.ts
# Access the application # Frontend: http://localhost:5173 # API: http://localhost:3000 # Swagger: http://localhost:3000/docs Manual Setup
Run each service manually if you prefer to manage PostgreSQL and Redis yourself.
# Install dependencies (from repo root)
bun install
# Configure environment
cp docker/.env.example .env
# Edit .env with your PostgreSQL and Redis connection details # Start PostgreSQL and Redis separately # (ensure PostgreSQL 16 and Redis 7 are running) # Run migrations
bun run migrate
# Bootstrap root admin
bun run --cwd packages/api src/scripts/bootstrap-root.cli.ts
# Start API server
bun run --cwd packages/api dev
# Start frontend (in another terminal)
bun run --cwd packages/web dev Environment Variables
Key configuration variables. Full reference available in docker/.env.example.
| Variable | Required | Description | Default |
|---|---|---|---|
DATABASE_URL | Yes | PostgreSQL superuser connection (migrations) | -- |
DATABASE_APP_URL | Yes | App-user connection via PgBouncer | -- |
REDIS_URL | Yes | Redis connection string | -- |
SESSION_SECRET | Yes | Session signing secret (min 32 chars) | -- |
CSRF_SECRET | Yes | CSRF token signing secret | -- |
BETTER_AUTH_SECRET | Yes | Better Auth secret | -- |
BETTER_AUTH_URL | Yes | API URL for auth callbacks | -- |
VITE_API_URL | Yes | API URL for frontend | -- |
CORS_ORIGIN | No | Allowed CORS origins | * |
RATE_LIMIT_MAX | No | Max requests per window | 100 |
RATE_LIMIT_WINDOW | No | Rate limit window (seconds) | 60 |
S3_BUCKET / S3_REGION | No | AWS S3 for file storage | -- |
SMTP_HOST / SMTP_PORT | No | Email configuration | -- |
CLAMAV_ENABLED | No | Enable virus scanning | false |
ENFORCE_ADMIN_MFA | No | Force MFA for admin roles | false (true in prod) |
OTEL_EXPORTER_OTLP_ENDPOINT | No | OpenTelemetry endpoint | -- |
Note: Full variable reference in docker/.env.example
Docker Compose Profiles
Multiple compose files for different deployment scenarios.
Default
PostgreSQL, Redis, PgBouncer, API, Web
docker-compose.yml Scale
Horizontal scaling with multiple API instances
docker-compose.scale.yml Monitoring
Prometheus + Grafana
docker-compose.monitoring.yml Logging
Loki + Promtail
docker-compose.logging.yml ClamAV
Optional virus scanning service
CLAMAV_ENABLED=true Development Commands
Common commands for day-to-day development.
# Run all tests
bun test # API + shared tests
bun run --cwd packages/web test # Frontend tests (vitest) # Run Storybook
bun run --cwd packages/web storybook
# Database migrations
bun run migrate # Run pending migrations # Linting
bun run lint # TypeScript check Note: Some setup steps inferred from project structure -- verify with README.md