Deployment
The Kulpay API is designed for containerized deployment using Docker and Kubernetes.
Docker Deployment
The system uses a multi-stage Docker build to produce a minimal production image.
Docker Compose
The development stack includes:
| Service | Image | Ports |
|---|---|---|
| Kulpay API | Custom build | 8080 (REST), 50051 (gRPC) |
| PostgreSQL | postgres:15 | 5432 |
Environment Configuration
The Kulpay API supports environment-based configuration with the following hierarchy:
config/config.yaml- Base configurationconfig/config.development.yaml- Development overridesconfig/config.production.yaml- Production overrides- Environment variables - Runtime overrides (format:
${VAR:-default})
Key configuration sections:
| Section | Parameters |
|---|---|
| Server | gRPC port, HTTP port, TLS certificates |
| Database | Dialect, host, port, credentials, pool settings |
| Cache | Redis host, port, database number |
| CORS | Allowed origins, methods, headers |
| Authentication | API keys, JWT settings, OIDC provider |
| Webhooks | Endpoint URLs, retry configuration |
Kubernetes Deployment
Production deployment uses Kustomize for Kubernetes configuration management.
Available CLI Tools
| Command | Purpose |
|---|---|
kuloffice | Start the main API server |
kuloffice-migrate | Run database migrations |
kuloffice-license | Manage license keys |
kuloffice-bootstrap | Bootstrap initial system configuration |
Database Migrations
Migrations are handled automatically by GORM's AutoMigrate feature. To run migrations explicitly:
kuloffice-migrate up
Technical Decision: GORM's
AutoMigratewas chosen over manual migration scripts (e.g., golang-migrate) because the schema is still evolving rapidly. Auto-migration reduces the overhead of writing and maintaining migration files during the early stages. For production environments where schema changes need to be reviewed and versioned, thekuloffice-migrateCLI tool provides explicit control.
Health Checks
The system exposes health information through:
GET /v1/system/config/supported-docs- System configuration endpointGET /v1/version- Version information including build date and git commit