Skip to content
SENS Platform Docs

Deployment Model

Purpose

Section titled “Purpose”

This document defines the initial deployment approach.

The platform must run on Kubernetes and be deployed through Helm.

Initial Environment

Section titled “Initial Environment”

The first deployment target is a dedicated server with Kubernetes installed.

This is acceptable for early test and controlled production-like usage, but the architecture must not depend on single-server assumptions.

Environments

Section titled “Environments”

The platform should support:

  • local
  • test
  • staging
  • production

Test, staging, and production must use the same application code and Helm charts. Differences must be represented through Helm values, environment variables, secrets, topology, and operational configuration.

Deployment Units

Section titled “Deployment Units”

Initial deployables:

  • web-console
  • docs
  • platform-api
  • mqtt-ingestion-worker
  • telemetry-worker
  • PostgreSQL/TimescaleDB
  • NATS JetStream

Container Registry

Section titled “Container Registry”

Initial registry: GitHub Container Registry unless replaced by an explicit decision.

CI/CD

Section titled “CI/CD”

Initial CI/CD system: GitHub Actions.

The first CI workflow is named ci and runs for pull requests and pushes to the main branch. The same command set must stay runnable locally and in CI:

  1. Install dependencies.
  2. Run linting.
  3. Run type checks.
  4. Run tests.
  5. Build applications and documentation.
  6. Run the documentation check.

When branch protection is enabled, ci should become a required pull request check.

Later deployment pipelines will add:

  1. Build container images.
  2. Push images to registry.
  3. Deploy to test environment.
  4. Promote to staging.
  5. Promote to production after validation.

Helm

Section titled “Helm”

Helm charts must configure:

  • Image repository and tag.
  • Replicas.
  • Environment variables.
  • Secrets references.
  • Service ports.
  • Ingress.
  • Resource requests and limits.
  • Persistence.
  • Health and readiness probes.
  • Metrics configuration where relevant.

No cloud-specific assumptions are allowed.

Phase 4.5 Test and Controlled Production Deployment

Section titled “Phase 4.5 Test and Controlled Production Deployment”

Phase 4.5 introduces an early Kubernetes test slice and a controlled production slice before production business behavior is implemented.

The first cluster is the dedicated server at 91.99.127.138. It currently runs k3s with Traefik, cert-manager, and the local-path storage class. This is an acceptable early target, but it is not a high-availability production design.

The Phase 4.5 release model is GitOps-based:

  • the product repository contains application code, Dockerfiles, and the Helm chart under infra/helm/sens-platform,
  • the private sens-platform-infra repository contains cluster and environment desired state,
  • Argo CD runs inside the k3s cluster first and may later move to a separate management cluster,
  • environments deploy immutable image tags and chart revisions,
  • runtime deployments use SemVer image tags only,
  • every published backend image records the Git SHA through image metadata and release metadata for auditability,
  • test uses alpha pre-release tags such as 0.5.0-alpha.1,
  • future staging should use rc pre-release tags such as 0.5.0-rc.1,
  • production uses stable SemVer tags such as 0.5.0,
  • the production promotion workflow derives the stable production tag from the current validated test alpha tag, and the stable tag must already be published before the manual production sync,
  • branch names may be recorded for human context, but runtime deployment must resolve to immutable revisions.

Initial public hostnames are:

  • argo.iot-sens.schlossers.at for Argo CD,
  • docs.dev.iot-sens.schlossers.at for the test documentation site,
  • docs.iot-sens.schlossers.at for the production documentation site,
  • api.dev.iot-sens.schlossers.at for the test platform-api operation endpoints,
  • api.iot-sens.schlossers.at for the production platform-api operation endpoints.

Test runs in sens-test and automatically follows successful main builds through generated alpha SemVer tags, for example 0.5.0-alpha.123.1. Production runs in sens-production, has no automated Argo CD sync policy, and is synchronized manually only by the local Argo CD user sebastian or the break-glass admin user.

Only platform-api is publicly exposed for smoke checks. Workers, TimescaleDB, NATS JetStream, and the mock MQTT broker remain cluster-internal. The mock MQTT broker is enabled for test and disabled for production.

The Helm chart includes embedded single-instance StatefulSets for TimescaleDB and NATS. These components are acceptable for the controlled start but must not be treated as production-ready database or broker infrastructure for real customer data. Before customer-critical operation, backup, restore, monitoring, and migration procedures must be completed and tested.

Single-Server Warning

Section titled “Single-Server Warning”

Running Kubernetes, database, broker, and applications on a single server creates availability and data-loss risks.

This is acceptable for early stages only if backups and restore procedures are documented and tested.

Before customer-critical operation, backup, monitoring, and restore processes must be validated.