System Admin Guide

Deployment

KUKAN supports two deployment methods.

AWS Deployment

Deploy with AWS CDK using an ECS Fargate + ALB architecture.

cd infra
npx cdk deploy --all

Key AWS resources:

• ECS Fargate — Web application + Pipeline Worker
• ALB — Load balancer
• Aurora Serverless v2 — PostgreSQL database
• S3 — File storage
• SQS — Pipeline queue
• OpenSearch — Full-text search engine

Docker Compose (On-Premises)

Deploy on-premises or in isolated networks using Docker Compose.

cp .env.prod.example .env.prod
# Edit .env.prod
docker compose --env-file .env --env-file .env.prod --profile prod up -d --build

On-premises deployments use the following alternative services:

AWS Service	On-Premises Alternative
S3	MinIO
SQS	ElasticMQ
OpenSearch	PostgreSQL full-text search

Initial setup

After deployment, you must create the first sysadmin user via CLI. Without a sysadmin, no system administration operations are possible.

pnpm db:create-user --email admin@example.com --name admin --password <password> --role sysadmin

Option	Description	Required
--email	Email address	Yes
--name	Username (lowercase alphanumeric, hyphens, underscores, periods)	Yes
--password	Password (8+ characters)	Yes
--role	user or sysadmin (default: user)	No

When REGISTRATION_ENABLED=false (self-registration disabled), use this command to create regular users as well.

pnpm db:create-user --email user@example.com --name taro --password <password>

User management

System administrators (sysadmin) can manage users from the admin dashboard.

User list & editing

• Change user display name and role (user / sysadmin)
• Cannot demote your own role (lockout prevention)

Deleting users

• Soft-delete (sets state to deleted)
• All sessions and API tokens are immediately revoked
• Audit logs and activity history are preserved

Self-registration control

Control new user self-registration via the REGISTRATION_ENABLED environment variable (default: enabled).

Health checks

KUKAN automatically monitors the health of external URL resources.

• Periodic automated checks via scheduler
• View health check results from the admin dashboard
• Identify and address failing resources

Environment variables

Key environment variables are listed below. See .env.example for the full list.

Variable	Description	Default
POSTGRES_HOST	PostgreSQL host	localhost
POSTGRES_PORT	PostgreSQL port	5432
POSTGRES_DB	Database name	kukan
POSTGRES_USER	Database user	kukan
POSTGRES_PASSWORD	Database password	kukan
S3_BUCKET	S3 bucket name	kukan-dev
S3_ENDPOINT	S3 endpoint (MinIO: http://localhost:9000, AWS: omit)	-
SEARCH_TYPE	Search engine (opensearch / postgres)	opensearch
OPENSEARCH_URL	OpenSearch endpoint	http://localhost:9200
SQS_QUEUE_URL	SQS queue URL	-
SQS_ENDPOINT	SQS endpoint (ElasticMQ: http://localhost:9324, AWS: omit)	-
BETTER_AUTH_SECRET	Auth session secret (32+ characters)	-
BETTER_AUTH_URL	Public URL	http://localhost:3000
REGISTRATION_ENABLED	Enable/disable user self-registration	true
LOG_LEVEL	Log level (trace–fatal)	info