Skip to main content

Requirements

This page lists every prerequisite for running Platform-Kernel in self-hosted mode. All versions are pinned to values verified in docker/versions.env and go.work (April 2026). Do not use older versions — several components rely on behaviors introduced in specific releases.

Software Prerequisites​

Runtime Stack​

ComponentMin versionPinned in projectNotes
Go1.26.01.26.1 (go.work)Required: range-over-func, toolchain directive
Node.js24.0.0≥ 24.0.0 (package.json)LTS 2026 — required by pnpm 10
pnpm10.0.0≥ 10.0.0 (package.json)Workspace protocol v2
Docker Engine29.0.029.4.1 (April 2026 GA)Compose Specification v3
Docker Compose5.0.0Plugin v5.xdocker compose (no hyphen)

Infrastructure Services​

All versions below are pulled from docker/versions.env — the single source of truth for the entire deployment:

ServiceImageVersionRole
PostgreSQLpostgres:17-alpine17Primary OLTP database
ClickHouseclickhouse/clickhouse-server:25.3-alpine25.3OLAP / analytics
Apache Kafkaapache/kafka:3.9.03.9.0Domain events (KRaft, no ZooKeeper)
RabbitMQrabbitmq:4.1-management-alpine4.1Transactional queues, DLQ
Valkeyvalkey/valkey:8.1-alpine8.1Redis-compatible cache
HashiCorp Vaulthashicorp/vault:1.191.19 (project pin)Secrets, JWT signing keys
SeaweedFSchrislusf/seaweedfs:3.843.84S3-compatible file storage
Envoyenvoyproxy/envoy:v1.33-latest1.33API Gateway (xDS)
GoFeatureFlaggofeatureflag/flagd:v1.42.0v1.42.0Feature flags
ClamAVclamav/clamav:1.41.4Antivirus scanning (files service)

Vault version note: The project pins Vault 1.19 in docker/versions.env. Vault 2.0.0 was released April 2026 and introduces breaking changes in the Agent and SPIFFE integrations. Migration guide will be provided before upgrading pinned version.

Kubernetes (production)​

ComponentMinimumRecommended
Kubernetes1.301.36 (April 2026 GA)
Helm CLI4.0.04.1.4 (April 2026 GA)
Istio1.251.29.2 (April 2026 GA)
cert-manager1.161.17+

Hardware Sizing​

Memory requirements are derived from deploy.resources.limits in docker/docker-compose.yml.

Development (single host, Docker Compose)​

ResourceMinimumRecommended
CPU4 cores8 cores
RAM16 GB32 GB
Disk (OS + images)40 GB SSD80 GB NVMe
Disk (data volumes)50 GB200 GB
Network100 Mbps1 Gbps

The full stack requires approximately 9 GB RAM at steady state (all 24 containers). Key consumers:

ContainerRAM limit
platform-clickhouse2 GB
platform-kafka512 MB
platform-postgres512 MB
platform-sonarqube2 GB (CI-only, optional)
platform-files512 MB (bimg/libvips headroom)
platform-rabbitmq256 MB
platform-valkey256 MB
All 12 Go services~128 MB each

Production (Kubernetes, multi-node)​

Minimum 3-node cluster for high availability:

Node rolevCPURAMStorage
Control plane48 GB80 GB SSD
Worker (stateless services)832 GB100 GB NVMe
Worker (stateful: PG, CH)1664 GB1 TB NVMe

Recommended minimum cluster for production traffic:

  • 3 control-plane nodes
  • 3+ stateless worker nodes (Go services, Gateway, Envoy)
  • 2+ stateful nodes (PostgreSQL primary + replica, ClickHouse)

Network Requirements​

Required Open Ports​

All inter-service communication uses the platform-network Docker bridge (172.20.0.0/16). The following ports must be reachable from the host or load balancer:

PortProtocolServiceDirection
8080HTTPAPI Gateway (HTTP health + REST)Inbound (public)
50051gRPCAPI Gateway (gRPC)Internal only
50050gRPCIAM ServiceInternal only
50052gRPCData LayerInternal only
50053gRPCEvent BusInternal only
50054gRPCNotify ServiceInternal only
50055gRPCBilling ServiceInternal only
50056gRPCIntegration HubInternal only
50057gRPCFile StorageInternal only
50058gRPCMoney ServiceInternal only
50059gRPCAudit ServiceInternal only
50060gRPCModule RegistryInternal only
50061gRPCDomain ResolverInternal only
5432TCPPostgreSQLInternal only
9092TCPKafka (KRaft)Internal only
5672 / 15672TCPRabbitMQ / Management UIInternal / ops
8123 / 9000HTTP / TCPClickHouse HTTP + nativeInternal only
6379TCPValkeyInternal only
8200HTTPHashiCorp VaultInternal + ops
8333 / 8888 / 9333HTTPSeaweedFS S3/filer/masterInternal only
1031HTTPGoFeatureFlagInternal only
3310TCPClamAVInternal only

TLS / mTLS​

All gRPC channels between Go services use mutual TLS (mTLS) enforced by the services/shared/mtls package. Certificates are issued and rotated by HashiCorp Vault PKI secrets engine. In development, Vault runs in dev mode with self-signed certificates.

In production (Kubernetes + Istio 1.29), mTLS is additionally enforced at the sidecar proxy level. Envoy terminates external TLS (Let's Encrypt via Certbot v4.0.0).

DNS Requirements​

  • Wildcard DNS record for custom domains: *.your-domain.com → Load Balancer IP
  • Internal service discovery: Kubernetes DNS / Docker Compose service names (e.g., iam:50050, kafka:9092)

Operating System​

OSSupport level
Ubuntu 24.04 LTS✅ Primary (CI-verified)
Debian 12✅ Supported
RHEL 9 / Rocky Linux 9✅ Supported
macOS 15 (Sequoia)✅ Development only
Windows❌ Not supported (Go workspace requires POSIX)

Pre-flight Checklist​

Before running docker compose up, verify:

# Go workspace version
go version
# → go version go1.26.1 darwin/arm64 (or linux/amd64)

# Node version (must be ≥ 24)
node --version
# → v24.x.x

# pnpm version (must be ≥ 10)
pnpm --version
# → 10.x.x

# Docker Engine
docker version --format '{{.Server.Version}}'
# → 29.x.x

# Docker Compose plugin
docker compose version
# → Docker Compose version v5.x.x

# Available RAM (Linux)
free -h | awk '/^Mem/{print $2}'
# Must be ≥ 16G for dev stack

See Also​