Skip to main content

Deployment

ArkOS is designed to run on Kubernetes. This guide covers the deployment workflow from local to production.

Prerequisites​

  • kubectl configured for your cluster
  • Helm 3 installed
  • Access to a container registry (GitHub Container Registry recommended)

Build Docker Images​

Each service has a Dockerfile. Build and push images:

# Build a specific service
docker build -t ghcr.io/arkos-plataform/product-service:latest ./services/product

# Push to registry
docker push ghcr.io/arkos-plataform/product-service:latest

CI/CD pipelines in .github/workflows/ automate this on every push to main.

Kubernetes Manifests​

Kubernetes manifests live in the infra/ repository:

infra/
├── services/
│   ├── product/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── configmap.yaml
│   └── ...
├── charts/          # Helm charts
└── overlays/        # Kustomize overlays per environment

Deploy a Service​

# Apply manifests for a service
kubectl apply -f infra/services/product/

# Check rollout status
kubectl rollout status deployment/product-service -n arkos

Helm Deployment​

For full platform deployment, use the Helm chart:

helm upgrade --install arkos ./infra/charts/arkos \
  --namespace arkos \
  --create-namespace \
  --values ./infra/charts/arkos/values.production.yaml

Environment-Specific Configuration​

Use Kustomize overlays for per-environment overrides:

infra/overlays/
├── development/
├── staging/
└── production/
# Deploy to staging
kubectl apply -k infra/overlays/staging/

# Deploy to production
kubectl apply -k infra/overlays/production/

Health Checks​

Every ArkOS service exposes:

  • GET /health — liveness probe
  • GET /ready — readiness probe

Kubernetes probes are pre-configured in the Helm chart.

Observability​

Production deployments ship with:

  • OpenTelemetry — distributed tracing
  • Prometheus metrics endpoint at /metrics
  • Structured JSON logs — compatible with Grafana Loki

Developer Portal Deployment​

The developer portal is a static site built with Docusaurus:

# Build static site
pnpm build:docs

# Output is in apps/developer-portal/build/
# Deploy to any static hosting (Cloudflare Pages, S3, etc.)

For Cloudflare Pages, the build command is pnpm build:docs and the output directory is apps/developer-portal/build.