Skip to content

Cloud-Native Overview

KanjiIQ is designed following cloud-native principles, making it portable across any Kubernetes-conformant platform. The application uses standard Kubernetes APIs with no proprietary cloud provider extensions.

12-Factor App Alignment

Factor KanjiIQ Implementation
I. Codebase Single Git repository (Forgejo) tracked with version control
II. Dependencies Explicitly declared in pubspec.yaml (Dart) and requirements-docs.txt (Python)
III. Config Environment variables injected via Kubernetes Secrets and ConfigMaps
IV. Backing Services PostgreSQL accessed via DATABASE_URL — swappable without code changes
V. Build, Release, Run Multi-stage Docker builds → tagged images → Kubernetes rolling updates
VI. Processes Stateless application containers; state lives in PostgreSQL
VII. Port Binding Services self-contained: frontend on :80, backend on :8080
VIII. Concurrency Horizontal scaling via Kubernetes replicas
IX. Disposability Fast startup, graceful shutdown, health probes
X. Dev/Prod Parity Staging namespace mirrors production manifests
XI. Logs Stdout/stderr (Kubernetes captures to node filesystem)
XII. Admin Processes Database migrations run as one-off commands

What Makes KanjiIQ Cloud-Native?

Standard Kubernetes APIs Only

All resources use standard apps/v1, v1, and networking.k8s.io/v1 API groups:

  • Deployment (not cloud-specific managed services)
  • Service (ClusterIP — works everywhere)
  • Ingress (standard networking API)
  • PersistentVolumeClaim (cloud-agnostic storage request)
  • Secret (standard config management)

The only non-standard CRDs are Traefik Middlewares — which can be replaced by equivalent ingress controller features on any platform.

Containerized Everything

Every component has a production-ready Dockerfile:

Component Dockerfile Base Image
Frontend Dockerfile.frontend nginx:alpine
Backend Dockerfile.backend dart:stable
Documentation Dockerfile.docs nginx:alpine

All images:

  • Use multi-stage builds (small production images)
  • Run as non-root (UID 1000)
  • Include health checks
  • Are pushed to a container registry (portable to any registry)

Infrastructure as Code

100% of the infrastructure is defined in version-controlled YAML:

k8s/
├── 00-namespace.yaml
├── 01-secrets.yaml (template)
├── 02-postgres-pvc.yaml
├── 03-postgres-deployment.yaml
├── 05-deployment.yaml
├── 06-service.yaml
├── 07-ingress.yaml
├── 08-security-middlewares.yaml
└── ...

Recreating the entire environment from scratch requires only:

kubectl apply -f k8s/

Portability Assessment

Component Portability Notes
Application Deployments Fully portable Standard k8s manifests
Services Fully portable ClusterIP works everywhere
Ingress Mostly portable May need ingress class change
PVC Fully portable Cloud providers auto-provision storage
Secrets Fully portable Same API across all clouds
Traefik Middlewares Requires adaptation Replace with cloud-native alternatives
Container Images Fully portable Push to any OCI registry
CI/CD Requires adaptation Forgejo Actions → GitHub Actions / Cloud Build

See Portability for detailed migration guides to AWS and GCP.