Admin: Add Navbox deployment template before Related (via update-page on MediaWiki MCP Server)

2026-07-06T04:01:31Z

Add Navbox deployment template before Related (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:31, 6 July 2026
Line 173:		Line 173:
	* ☐ An S3-compatible bucket and credentials exist for backups.		* ☐ An S3-compatible bucket and credentials exist for backups.
	* ☐ DNS records and a TLS certificate (e.g. a Let's Encrypt wildcard) are ready for your domains.		* ☐ DNS records and a TLS certificate (e.g. a Let's Encrypt wildcard) are ready for your domains.

			{{Navbox deployment}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T23:08:02Z

OHC identity seed

New page

{{Doc header
|type=guide
|domain=deployment
|title=Requirements
|order=2
}}

This page lists what an operator needs in place before deploying Care. The reference deployment is a small, self-hosted Kubernetes cluster provisioned with <code>kubeadm</code> and managed as infrastructure-as-code with [<nowiki/>https://opentofu.org/ OpenTofu]. Everything below is distilled from the deployment repository ([<nowiki/>https://github.com/ohcnetwork/deployment-k8 ohcnetwork/deployment-k8]); none of it requires a managed cloud platform, though the same shapes apply if you adapt them to one.

Read the [[Deployment/Kubernetes/Reference architecture|reference architecture]] first if you want the bigger picture of how these pieces fit together.

== Infrastructure ==

The reference is a '''two-node cluster on a shared network''' — one primary node and one secondary (failover) node — with replicated storage between them so the secondary can take over if the primary fails.

{| class="wikitable"
|-
! Requirement
! Reference value
! Notes
|-
| Nodes
| At least 2 Linux hosts
| One primary, one secondary/failover. Generalize the hostnames; the repo expects <code>primary_node_name</code> and <code>secondary_node_name</code> as inputs.
|-
| Network
| Shared L2/L3 network between nodes
| Each node also needs a routable IP (<code>primary_node_ip</code>, <code>secondary_node_ip</code>).
|-
| Kubernetes
| Provisioned with <code>kubeadm</code>
| The reference pins a specific <code>kubernetesVersion</code> in <code>kubeadm.yaml</code>; match the deployer's expected version rather than assuming "latest".
|-
| Pod / service networking
| Cilium CNI
| Pod and service subnets are set in the cluster config.
|-
| Storage
| Per-node volumes, replicated
| The reference separates fast (SSD) and bulk (HDD) data paths, e.g. <code>primary_ssd_data_path</code>, <code>primary_hdd_data_path</code>, <code>secondary_ssd_data_path</code>. Replication across nodes is what gives the failover node a usable copy of the data.
|-
| Swap
| Permitted (not disabled)
| The reference kubelet config runs with swap enabled in a limited mode rather than forcing it off.
|}

{{Note|1=The architecture notes describe storage replication as still evolving (RAID-with-replicas per volume is the target). Treat cross-node data replication as something you must design and verify for your environment, not as a turnkey feature.}}

== Workstation tooling ==

You drive the deployment from an operator workstation that can reach the cluster's Kubernetes API. Install the following before you begin:

* ☐ '''<code>kubectl</code>''' — to talk to the cluster.
* ☐ '''<code>kubeadm</code>''' — to bootstrap the control plane and join nodes.
* ☐ '''OpenTofu (<code>tofu</code>)''' — the infrastructure is defined as Tofu modules and applied per stack.
* ☐ '''Helm''' — several components are installed as Helm charts.
* ☐ '''Cilium CLI''' — to install and inspect the CNI.
* ☐ '''Python 3''' — the deployer (<code>deployer.py</code>, driven via <code>make</code>) is a Python program.
* ☐ '''The deployer's Python dependency''' — install it into your environment:

<syntaxhighlight lang="bash">pip install -r requirements.txt</syntaxhighlight>
This installs [<nowiki/>https://typer.tiangolo.com/ Typer] (<code>typer>=0.9.0</code>), which the <code>make</code> targets use to wrap Tofu and <code>kubectl</code> runs. For example, the repo exposes targets such as <code>make apply-tofu-<stack></code>, <code>make apply-k8-<stack></code>, and <code>make check-k8-cluster</code>.

{{Tip|1=Use a Python virtual environment for the deployer so its dependency does not collide with other tools on your workstation.}}

== External dependencies ==

These services are not part of the cluster bootstrap but the deployment expects them to exist (or be provisioned alongside it).

{| class="wikitable"
|-
! Dependency
! Purpose
! Reference choice
|-
| Container registry
| Hosts the images the cluster pulls, including the locally built Care frontend image
| The reference '''self-hosts''' a registry using [<nowiki/>https://zotregistry.dev/ zot]. Any OCI-compatible registry works.
|-
| S3-compatible object storage
| Off-site target for backups (Postgres, OpenSearch, object-store syncs)
| Any S3-compatible endpoint — for example [<nowiki/>https://min.io/ MinIO] or DigitalOcean Spaces. Keep the endpoint and credentials as your own secrets.
|-
| DNS
| Resolves the public and internal hostnames for each service (Care API, Care frontend, object store, Odoo, Metabase, monitoring)
| The repo takes both public and local domain names per service as inputs.
|-
| TLS certificates
| HTTPS termination at the ingress
| [<nowiki/>https://letsencrypt.org/ Let's Encrypt]; a pre-fetched wildcard certificate is the intended approach so the ingress can terminate TLS for every subdomain.
|}

{{Warning|1=Do not copy hardcoded node names, internal domains, object-storage endpoints, or any credentials out of the deployment repository. Those are one operator's environment. Substitute your own values — for example <code><primary-node></code>, <code>your-domain.example</code>, <code><s3-endpoint></code> — and keep secrets out of version control.}}

== What gets deployed ==

The cluster runs Care plus its data stores and a few adjacent applications. Use this table to size your nodes and storage. "Persistent" means the component needs a persistent volume that survives pod restarts and is included in backups; "non-persistent" means it can be recreated from scratch with no data loss.

{| class="wikitable"
|-
! Component
! Shape
! Storage
! Backups
|-
| Care backend
| Multiple web workers + Celery workers + a Celery scheduler
| None (stateless)
| N/A
|-
| Care frontend
| Served via nginx; image built locally and pushed to the registry
| None (stateless)
| N/A
|-
| PostgreSQL (Care)
| Production mode, single primary
| Persistent
| Daily/configurable, to disk and optionally to S3-compatible storage
|-
| Redis
| Cache/broker, non-persistent mode
| None
| None
|-
| OpenSearch
| Single node, minimal configuration
| Persistent
| Daily/configurable, to external media
|-
| Object store
| Self-hosted S3-compatible store for uploads, audit logs, and public data
| Persistent
| Incremental syncs to external storage
|-
| Odoo
| Web workers + Celery workers (with autoscaling)
| Via its database
| See Odoo Postgres
|-
| PostgreSQL (Odoo)
| Dedicated instance, same hardening as Care's Postgres
| Persistent
| Daily/configurable, to external media
|-
| Metabase
| Analytics app (with autoscaling)
| Via its database
| See Metabase Postgres
|-
| PostgreSQL (Metabase)
| Dedicated instance, same hardening as Care's Postgres
| Persistent
| Daily/configurable backups of its volume
|}

Alongside the application components, the cluster also provides:

* ☐ '''Load balancing''' — in front of the cluster, with separate load balancing for the object store and for Metabase where that isolation helps.
* ☐ '''WAF / firewall routing''' — at the ingress, so traffic is filtered before it reaches application pods.
* ☐ '''Central logging''' — file-based logging to a persistent volume, with the ability to pipe logs to external destinations.

{{Info|1=The deployment also targets '''auto-restore''': a fresh cluster should be rebuildable from the backups above. That capability depends on every persistent component having a working, tested backup. Confirm your backups restore before you rely on them — see [[Deployment/Kubernetes/Day-2 operations|day-2 operations]].}}

== Before you proceed ==

You are ready to start [[Deployment/Kubernetes/Provisioning the cluster|provisioning the cluster]] once you can check every box:

* ☐ Two (or more) Linux nodes are reachable on a shared network, with their IPs and data paths chosen.
* ☐ Your workstation has <code>kubectl</code>, <code>kubeadm</code>, <code>tofu</code>, <code>helm</code>, and the Cilium CLI installed.
* ☐ Python 3 is available and <code>pip install -r requirements.txt</code> has succeeded.
* ☐ A container registry is reachable (self-hosted or managed).
* ☐ An S3-compatible bucket and credentials exist for backups.
* ☐ DNS records and a TLS certificate (e.g. a Let's Encrypt wildcard) are ready for your domains.

{{Related}}

Deployment/Kubernetes/Requirements - Revision history

Admin: Add Navbox deployment template before Related (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed