# Gentian OS > Gentian OS turns a Kubernetes cluster into a cloud operating system: tenants, identity, routing, storage, mail and an app catalog, installed and upgraded as one. ## Overview - [Gentian OS — Platform Architecture](https://github.com/gentian-org/gentian-os/blob/develop/docs/overview/architecture.md): Gentian OS is a cloud-native operating system for open-source business applications. - [FAQ](https://github.com/gentian-org/gentian-os/blob/develop/docs/overview/faq.md): A Kubernetes cluster, version 1.33 or newer: your own servers or any provider. - [Gentian OS in plain terms](https://github.com/gentian-org/gentian-os/blob/develop/docs/overview/introduction.md): For readers who know software and servers but not Kubernetes. - [Why a Cloud OS](https://github.com/gentian-org/gentian-os/blob/develop/docs/overview/why-a-cloud-os.md): Open-source business software is excellent — Nextcloud, OpenProject, Element/Matrix, OX App Suite, XWiki, Jitsi each rival or surpass their proprietary competitors in their own domain. ## Guides - [App Customization Framework — the Gentian Customization Ladder](https://github.com/gentian-org/gentian-os/blob/develop/docs/guides/app-customization.md): Gentian has customization mechanisms — `extraValues`, `Tenant.spec.apps[].config`, profile annotations, `composition.yaml`, the `gentian-sidecar-git-modules` addon sync, the `ocb` Odoo fork — and… - [Custom catalogs](https://github.com/gentian-org/gentian-os/blob/develop/docs/guides/custom-catalogs.md): How to publish your own apps to a Gentian OS cluster: what a catalog is, how to build one from an empty git repository, how to add it to a cluster or to one tenant, and what the platform checks. - [Deployment Environments and Promotion](https://github.com/gentian-org/gentian-os/blob/develop/docs/guides/deployment.md): This guide describes how Gentian OS clusters are configured, how a new cluster gets bootstrapped, and how releases promote from development to production. - [Identity brokering: people of one realm signing in to another](https://github.com/gentian-org/gentian-os/blob/develop/docs/guides/identity-brokering.md): People who already have an account in one realm — another tenant of this cluster, or a tenant of another cluster — sign in to a second realm with that account, and get rights there according to… - [Migrating a cluster to a new node flavor](https://github.com/gentian-org/gentian-os/blob/develop/docs/guides/node-pool-migration.md): Moving a running cluster onto different worker nodes — usually to a larger or memory-heavier flavor. - [Recovery Playbook](https://github.com/gentian-org/gentian-os/blob/develop/docs/guides/recovery.md): What to do when something is gone. - [Backing Up and Recovering Your Workspace](https://github.com/gentian-org/gentian-os/blob/develop/docs/guides/tenant-backup.md): A backup captures your whole workspace — your apps' databases, the files they store, and your member accounts — into a single encrypted bundle. ## Reference - [kubectl gentian synopsis](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/commands-synopsis.md): The synopsis of every `kubectl gentian` command, as the plugin's own header states it; the full description of each command is in commands.md. - [Gentian OS Commands](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/commands.md): This document lists key cluster-admin commands for Gentian OS operations. - [Custom resource definitions](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/crds.md): The custom resource definitions of the `gentianos.io` API group, with every field of their `spec` and `status`. - [Install flags and steps](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/install-steps.md): The options `install.sh` accepts, in the order it parses them, with the help `install.sh --help` prints for each. - [Install reference](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/install.md): Everything about installing that is not the first-install walkthrough. - [Namespace layout](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/namespaces.md): The cluster's namespace layout by tier, as `kernel/namespaces.yaml` declares it: the one list the installer creates from, the operator selects on and the lints check against. - [The store API](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/store-api/store-api.md): What a store serves, written for whoever builds one. - [Component versions](https://github.com/gentian-org/gentian-os/blob/develop/docs/reference/versions.md): Every external component the installer pulls, pinned once for the release, with each value exactly as `versions.yaml` writes it; `scripts/lib/versions.sh` reads the same file for the installer. ## Concepts - [Administration console — design](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/admin-console.md): Every tenant needs a place to govern who belongs to it and which apps each person may use. - [Agentic AI Layer](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/agentic-ai.md): The kernel carries what every participant needs and nobody should rebuild: the protocol apps expose their operations through (MCP), a gateway to language models, and an assistant a person can ask… - [App authorization](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/app-authorization.md): How an app gets an authorization store of its own. - [App Catalog, Profiles and Integrations](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/app-catalog.md): Four kinds matter for an app. - [Authorization](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/authorization.md): One vocabulary for the platform's rights: the rules the model follows, the tuples something writes, and what each enforcement point asks. - [Branding](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/branding.md): Every page the platform serves shows one brand: the concierge, the identity provider's screens, the desktops, the consoles and the edge's access-denied page. - [The control plane: which program does what](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/control-plane.md): The programs that run the Gentian OS control plane, what each one holds, what each refuses, and what a break-in at each would cost. - [The life of a tenant's and an app's data](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/data-lifecycle.md): The platform keeps one list of the kinds of things an app and a tenant own. - [The tenant's data is the tenant's](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/data-ownership.md): Gentian OS is open source, and what that gives a tenant is this: at any moment a tenant can take all of their data with them, and at any moment they can have all of it destroyed, without asking the… - [Identity and Access Management (IAM)](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/iam.md): This document describes identity, roles, and access control in Gentian OS. - [The Kernel and the Default Install](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/kernel.md): A traditional OS kernel mediates between hardware and applications by providing a small, stable set of services every app needs. - [LLM Serving Integration Design](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/llms.md): This document details the architecture for integrating Large Language Model (LLM) serving capabilities into Gentian OS. - [Mail Kernel Extension](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/mail.md): Three layers are easy to conflate: - [Multi-Tenancy, Domains and Security](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/multi-tenancy.md): A tenant is an organization. - [Networking](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/networking.md): How traffic is admitted inside the cluster: the network plugin, the NetworkPolicy tiers of a tenant namespace, the kernel's rules, egress, and the edge that real-time media takes. - [Operations: Backup, DR, Observability, Image Updates](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/operations.md): Backup is per tenant. - [Partners: identity across clusters](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/partners.md): A person who has an account in a realm on one cluster and an account in a realm on another links the two once. - [Resource plans and usage — design](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/resource-plans.md): A tenant runs under a ceiling: how much CPU, memory and storage its apps may claim between them. - [Routing and the Edge](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/routing.md): Gentian OS exposes all HTTP(S) entry points through Gateway API backed by Envoy Gateway. - [The App Store contract](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/store-contract.md): A store is a service outside the cluster, run by a vendor, on infrastructure the cluster does not trust. - [Versioning and updates](https://github.com/gentian-org/gentian-os/blob/develop/docs/concepts/versioning.md): How Gentian OS and the apps on it move from one version to the next. ## Decisions - [AD-1 The security principles are normative](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-01-security-principles-normative.md): The nine rules in security/principles.md bind every change; one that breaks a rule needs a written reason. - [AD-2 The director is the only writer to the deployment repository](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-02-director-only-writer.md): Every write is authenticated by Keycloak and authorized by OpenFGA; commits are signed, and Argo CD (`AppProject.spec.sourceIntegrity`) syncs only commits signed by the director or the break-glass… - [AD-3 The store's data lives outside the cluster; its interface is an app on it](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-03-store-outside-cluster.md): The store, a service run by a vendor, holds and serves what is known about apps and what a tenant acquired; it never calls the cluster and decides nothing for it. - [AD-4 One catalog kind, `ComponentProfile`, with classes](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-04-one-catalog-kind.md): One kind describes system services, apps and agents. - [AD-5 Requirements and integrations are separate fields](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-05-requirements-and-integrations.md): A requirement is owed by the platform, gates admission, and its absence is the platform's fault; an integration is a peer relationship, bound continuously, absent peers normal. - [AD-6 Exposure carries a mandatory `authMode` and a `surface`](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-06-exposure-authmode-surface.md): `authMode` has no default; `surface` is `gateway` or `perimeter`. - [AD-7 Namespaces are named by tier](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-07-namespaces-by-tier.md): `kernel-`, `system-`, `system--dmz`, `shared-`, `tenant-`, `tenant--dmz`. - [AD-8 Kernel trust domains are separate namespaces](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-08-kernel-trust-domains.md): `kernel-authentication` (Keycloak, public route) apart from `kernel-authorization` (OpenFGA, enforcement points only); `kernel-seal` apart from `kernel-secrets`, because the seal's unseal key is an… - [AD-9 System services have no public route](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-09-no-public-route-for-system-services.md): HTTP access from outside goes through a tenant's DMZ with that tenant's credential. - [AD-10 The desktop is the desktop, for everyone; the consoles are apps](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-10-desktop-and-consoles.md): The desktop runs per tenant in `tenant-` with that tenant's credentials only, and the platform is a tenant with a desktop like every other. - [AD-11 The layout applies to fresh installs](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-11-layout-fresh-installs.md): Stateful kernel components (OpenBao, Keycloak, CNPG clusters) are never renamed in place; an existing cluster rebuilds from its recovery kit or keeps its names and adopts the labels (kernel.md… - [AD-12 The authorization store is a projection; Keycloak's events are the only source of membership](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-12-authorization-store-projection.md): Group membership is stored in OpenFGA as `group#member` tuples written by the operator from the signed statements Keycloak's event listener sends it, never edited in place; nothing re-reads them… - [AD-13 The edge is the only session authority](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-13-edge-session-authority.md): One confidential OIDC client per tenant zone, on the `authenticated` Gateway, mints the one edge cookie. - [AD-14 Without a store, apps are installed by command only](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-14-install-by-command-without-store.md): `kubectl gentian apps install` asks the director on the same route and under the same question as every other install (AD-3). - [AD-15 The OS is multi-lingual](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-15-multi-lingual.md): Every word a person reads is translatable, and a language is added by adding a message catalog, never by changing a component. - [AD-16 Every cluster role but `admin` and `breakGlass` is held by a person named in git](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-16-cluster-roles-named-in-git.md): `admin` and `breakGlass` are held by a group of the kernel realm (`spec.platformRoles`). - [AD-17 Identity crosses clusters only as a partner link, by standards](https://github.com/gentian-org/gentian-os/blob/develop/docs/decisions/ad-17-identity-crosses-as-partner-link.md): A tenant's realm declares partners, bounded by the Cluster claim's `allowedIssuers`. ## Security - [Audit events, log forwarding and monitoring — design](https://github.com/gentian-org/gentian-os/blob/develop/docs/security/audit-events.md): Principle 7 says audit is three logs joined by one request id: the issuer's events, the decision log, the change log. - [Control catalog](https://github.com/gentian-org/gentian-os/blob/develop/docs/security/controls.md): One row per control objective: the principle it serves (security/principles.md), the mechanism that implements it, and the query that produces its evidence. - [Gentian Cloud OS — Security Architecture](https://github.com/gentian-org/gentian-os/blob/develop/docs/security/design.md): Architecture reference. - [Security principles](https://github.com/gentian-org/gentian-os/blob/develop/docs/security/principles.md): Nine rules that keep authentication, authorization and traffic one framework as tenants, users and apps multiply. ## Releases - [Gentian OS v0.4](https://github.com/gentian-org/gentian-os/blob/develop/docs/releases/v0.4.md): v0.3 finished the app story: apps installed, authenticated and, with the AI line, talked to a model. ## Contributing - [How the documentation is written](https://github.com/gentian-org/gentian-os/blob/develop/docs/contributing/documentation.md): The rules every page under `docs/` follows. - [Repository Folder Structure](https://github.com/gentian-org/gentian-os/blob/develop/docs/contributing/folder-structure.md): What lives where in `gentian-os`, and why each directory exists.