System Operations Guide

Operations manual for Hereby platform deployment, database management, monitoring, and integrations.

Target Users: System Administrators, Developers, DevOps Engineers

System Architecture

Service Port Map

Service	Port	Protocol
PostgreSQL	5432	TCP
pgAdmin	5050	HTTP
Redis	6379	TCP
API Server	3000	HTTP
HR System	4000	HTTP
Admin Panel	4001	HTTP
Employee App	4002	HTTP
Nurse Scheduler	4003	HTTP
Internal Approval	4004	HTTP
General Affairs	4005	HTTP
Management Dashboard	4006	HTTP
Inventory	4007	HTTP
Module Manager	4010	HTTP
System Admin API	4100	HTTP
System Admin UI	4101	HTTP

Guides

Core Operations

• Deployment & Server Management — Installation, updates, Docker
• Database Operations — Migrations, backup, recovery
• Monitoring & Logging — Logs, health checks, metrics
• Troubleshooting — Diagnosis and resolution

Multi-Tenancy

• Organization Management — Provision / delete hospitals, admin accounts

Integrations

• Secom Fingerprint Integration — Wire up 세콤 지문인식기 attendance sync

Common Tasks

Provision a New Hospital

# Via System Admin Tool UI (recommended)
open http://localhost:4101
# Login with an operator account (platformRole=OPERATOR) on the target endpoint
# → 조직 관리 → New Organization → fill wizard

# Or via API
curl -X POST http://localhost:4100/api/provision -H "..." -d '{...}'

Set Up Secom for an Organization

make provision-secom CLIENT=CLINIC01 PASSWORD='<secure>' SECOM_IP=192.168.20.101/32

Backup Database

make db-backup
# Creates timestamped dump in ./backups/

Update to a New Version

git pull
pnpm install
pnpm build
make db-migrate
# Restart services

Environment Variables

See .env.example for the complete list. Critical production variables:

Variable	Required?	Notes
DB_PASSWORD	Yes	Strong password
DB_SSL	Recommended	true in production
JWT_SECRET	Yes	Long random string
SYSADMIN_JWT_SECRET	Yes	Signs system-admin console session tokens; the console refuses to boot in production without it
SYSADMIN_ALLOWED_IPS	Recommended	Comma-separated exact IPs — no CIDR support; empty falls back to localhost only
FCM_SERVICE_ACCOUNT_KEY	Optional	For mobile push
WEB_PUSH_PUBLIC_KEY + WEB_PUSH_PRIVATE_KEY	Optional	For browser push