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 (Vite dev server)

Guides

Core Operations

• Deployment & Server Management — Installation, updates, Docker
• Database Operations — Migrations, backup, recovery
• System Admin Control-Plane Bootstrap — Initialize and seed the independent admin database
• System Admin Authorized Reads — Provision endpoint identity and signed organization reads
• 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

Inspect Organizations from a Configured Backend

open http://localhost:4101
# Login with the independent local SUPER_ADMIN account
# → select a configured endpoint → read its authorized organizations

Organization provisioning and mutation routes are intentionally outside the authorized-read milestone. Use the separately reviewed provisioning workflow when that write path is enabled.

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_DB_*	Yes	Independent control-plane database used by the System Admin server
SYSADMIN_ENCRYPTION_KEY	Yes	Secret used to encrypt authenticator/TOTP material outside the database
SYSADMIN_ENDPOINTS	Yes for Sysadmin	Infra-owned JSON registry of backend IDs, internal origins, display names, environments, and optional CS prefixes; [] is valid when intentionally empty
SYSADMIN_ENDPOINT_ID	For each business backend	Matching Infra-owned backend identity used by signed Sysadmin requests; not a database UUID
SYSADMIN_SERVICE_*	For backend reads	Short-lived service-token signing and the shared issuer/public-key trust; endpoint origins and membership come from SYSADMIN_ENDPOINTS
SYSADMIN_ALLOWED_IPS	Recommended	Comma-separated exact IPs — no CIDR support; empty falls back to localhost only
NODE_ENV	Yes for Sysadmin	development, test, staging, or production; production requires HTTPS for App backend, Native update, and Bundle download URLs, while the other modes allow HTTP or HTTPS
SYSADMIN_APP_DISCOVERY_ORIGINS	For public App APIs	Exact comma-separated browser/WebView origins used by backend discovery and version check; keep empty until deployed App origins are reviewed. See the discovery runbook.
SYSADMIN_APP_VERSION_UPDATE_HOSTS	Legacy App version route only	Exact public update-link host allowlists keyed by platform (ios, android, web). Remove after the reviewed client cutover. See the version-management runbook.
FCM_SERVICE_ACCOUNT_KEY	Optional	For mobile push
WEB_PUSH_PUBLIC_KEY + WEB_PUSH_PRIVATE_KEY	Optional	For browser push