Deployment

Deploying the ecosystem may initially appear to be a complex task due to its design for scalability from the outset. This entails the integration of several scalable components within a distributed deployment architecture. To streamline the installation process, we have established this repository to offer comprehensive guidance. Our objective is to incorporate as much automation as possible within this repository, thereby ensuring that the installation process is straightforward and user-friendly. At the same time, we remain committed to delivering a scalable and highly available video surveillance system.

Edit in Draw · Diagram source

The ecosystem offers flexible installation options, supporting deployment in hybrid environments, fully in the cloud, or entirely at the edge. This deployment guide covers installing its components. For detailed component documentation, please refer to the links below.

• Agent
• Factory
• Vault
• Hub

Continuous deployment

These badges show the latest status of each GitHub Actions workflow on main. Select a badge to view its runs and platform-specific results. The deployment workflows continuously test the ecosystem across kind, k3d, and MicroK8s; the Kustomize workflow validates the Kustomize, Garage, and Factory setup.

Kubernetes examples and CI now use Garage S3 for local object storage. See the Garage setup guide for generated credentials, Vault configuration, persistence tests and existing MinIO compatibility. This is a single-node example, not a replicated production storage deployment. The MinIO manifests remain available; no existing data is migrated or removed automatically. The Docker guide retains its separate storage setup.

Slack notifications are optional. If SLACK_WEBHOOK_URL is unavailable (for example on fork PRs), CI emits a warning and skips delivery without masking deployment failures. Configured webhook delivery errors still fail the step. Failed deployment jobs collect pod events and bounded logs for diagnosis.

Security

We harden our container images and check our solutions for known CVEs. See the Secure repository for our security work.

Agent HTTP port compatibility

The forthcoming Agent hardening update moves its internal HTTP listener from 80 to 8080. Published Agent releases still use 80; do not change a running deployment's target port until its selected image supports 8080. Pin a verified image tag or digest rather than assuming kerberos/agent:latest has this change. See the Docker port mappings.

For Kubernetes, update the image and containerPort together in base/agent/kerberos-agent-deployment.yaml. If enabling its commented Service example, change targetPort to 8080 as well; the external Service port: 80 can stay unchanged. That example's selector.app must also match the Deployment's app: agent1 label. There are no Agent HTTP health probes in this base manifest; any probes or direct pod port-forwards added locally must target the selected image's listener. The Vault URL ending in :80/api is a separate Service and must not be changed.

Factory also selects kerberos/agent:latest through KERBEROS_AGENT_IMAGE. Before choosing a hardened Agent image, verify that Factory's generated Agent Deployments, Services and probes support port 8080; changing the image setting alone does not establish compatibility. See the Factory Agent-image guidance. These deployment defaults remain unchanged until a compatible image and controller are verified.

Architecture

As previously indicated, several integral components, including object storage, databases, and message brokers, are deployed and configured to support the ecosystem. The architecture diagrams below provide a visual representation of these components and how they interact in self-hosted and managed cloud deployments.

It is important to note that the ease of installation may vary depending on the chosen Kubernetes distribution and platform. For instance, distributions like Microk8s, which offer an addons feature, may simplify the installation process significantly. Managed Kubernetes services on platforms such as AWS, Azure, GCP, and others offer a range of supplementary services. These include, but are not limited to, cloud-based object storage, load balancers, persistent volumes, and additional resources that enhance the deployment experience. On the other hand running a self-hosted vanilla Kubernetes deployment will come with additinal work as it misses the out-of-the-box components from a managed deployment or the self-hosted Microk8s add-ons feature.

Given these differences, we have created specific architectural frameworks for self-hosted and cloud-based deployments. This approach ensures that each deployment is optimized for its environment, using the unique benefits and services of each platform. In the next section we discuss the different deployment strategies and installation processes.

Edge (self-hosted) deployment

Edge (self-hosted) deployments are typically used for camera processing and edge storage. In this setup, Agents are deployed and connected to cameras, with recordings stored in the Vault. Additionally, you may want to create integrations, such as data filtering, to ensure only relevant recordings are retained, or set up custom notifications to your first or third-party platforms. In this edge scenario, hardware is being deployed in the local network to handle the workloads; for example AMD64 or ARM64 processors.

Edit in Draw · Diagram source

Factory is optional and manages Agents when using Kubernetes. Event publishing and custom integrations are optional; recordings can stay entirely within the private edge network.

A key aspect of this deployment is the scaling of Agents. Each camera is assigned a dedicated Agent container, which is linked to a central Vault. Vault stores metadata in MongoDB, recordings in Garage (or another S3-compatible object storage), and can generate events in a message broker like RabbitMQ. This approach enables you to develop custom applications or logic that can respond to new recordings.

Based on your technology experience and preferences, you can choose from the following deployment guides:

• [Easy] Install the ecosystem with Docker
• [Medium] Install the ecosystem with Microk8s
• [Advanced] Install the ecosystem with Kubernetes

Managed deployment

Managed deployments are typically executed on cloud platforms such as Azure, Google Cloud Platform (GCP), Amazon Web Services (AWS), among others. The advantage of a managed deployment is that many foundational components are pre-configured and readily available, which is not the case for a self-hosted deployment. For example:

• Object storage: AWS has S3, GCP has Cloud Storage, Azure has Blob Storage.
• Load Balancers: Automatic traffic distribution for high availability.
• Encryption: Built-in data encryption at rest and in transit.
• High availability and scaling: can allocate new compute and storage on the fly.
• etc.

As previously discussed, a managed deployment enhances resilience and high availability by leveraging the cloud provider's existing services as the backbone for your Kubernetes cluster. For example, when deploying a Kubernetes cluster on:

• AWS provides EKS (Elastic Kubernetes Service) which integrates with services like S3 for object storage, EC2 for compute instances, IAM for access management, CloudWatch for monitoring, and RDS for managed databases.
• GCP provides GKE (Google Kubernetes Engine) which utilizes Google Cloud Storage for object storage, Compute Engine for virtual machines, IAM for access control, Stackdriver for monitoring and logging, and Cloud SQL for managed databases.
• Azure provides AKS (Azure Kubernetes Service) which works with Azure Blob Storage for object storage, Virtual Machines for compute resources, Azure Active Directory for identity management, Azure Monitor for monitoring and diagnostics, and Azure SQL Database for managed relational databases.

Purpose of a Managed Deployment

The primary objective of maintaining a managed, public-facing deployment is to centralize multiple edge deployments through a unified interface. Typically, edge deployments are distributed across various environments such as hospitals, retail stores, and factories. These edge deployments are inherently secure and non-public facing, preventing direct internet access to these environments. To address this challenge, we operate a managed, public-facing environment that consolidates all recordings, live camera views, and permissions into a single, cohesive platform.

Edit in Draw · Diagram source

This example shows Agents uploading directly to cloud Vault, without exposing the camera networks to inbound internet traffic. Hybrid deployments can retain an edge Vault and forward selected recordings to cloud Vault instead. The backing services can be self-hosted or compatible managed services; their logical roles stay the same.

Based on your technology experience and preferences, you can choose from the following deployment guides:

• [Medium] Install the ecosystem with Kubernetes (AWS, GCP, Azure, etc.)

Or provision the infrastructure yourself with infrastructure as code:

• [AWS] Terraform: EKS cluster + Amazon DocumentDB
• [Azure] Terraform: Event Hub with 10 partitions

Updating architecture diagrams

These diagrams use the same editable groups, nodes, and connections JSON format as the Learn diagrams and Draw. GitHub cannot run Learn's interactive renderer, so the README uses self-contained SVG exports from Draw, with an Edit in Draw link carrying the source in a base64-encoded UTF-8 URL fragment.

1. Update the corresponding JSON in assets/diagrams. Keep the product colours, labelled zones, cards and orthogonal connectors consistent with Learn; the overview follows Learn's solution stack.
2. Run node scripts/update-diagram-links.mjs (Node.js 20+) to refresh the README's Draw links. Open the updated Edit in Draw link, or paste the JSON into Draw's Templates import.
3. Use Draw's Export board action to download an SVG in light mode and replace the matching file in assets/images. Export the whole diagram, not a screenshot of the editor. Draw embeds its image assets so GitHub does not need external icons or scripts.
4. Run node scripts/update-diagram-links.mjs --check and preview the README. The check validates source bounds/connections, SVG presence and link freshness; also check the exported diagram visually.

Edits on a Draw board do not automatically update this repository. Mirror any board changes into the JSON source before refreshing the links and SVG. Commit the source, preview and README links together; do not hand-edit the generated links below.