Skip to main content
Version: Weekly Build

Installation Guide

This page is the sequence map for installing Codesphere on your own infrastructure. Each section below summarizes one step and links to the full page for that step. If you arrived here from a link to a specific step (for example #configure-dns), the summary for that step links directly to the detailed page.

What the installation builds​

The installation uses a jumpbox as the single entry point into a private network. From there, OMS installs and configures PostgreSQL, Ceph, k0s, and the Codesphere platform.

administrator
    |
    | SSH
    v
jumpbox
    |
    +-- PostgreSQL node
    +-- 3 or more Ceph nodes
    `-- 3 or more k0s nodes

Internet
    |
    +-- platform gateway IP       -> <base-domain> and <dc-id>.<base-domain>
    +-- workspace gateway IP      -> *.<dc-id>.<base-domain>
    `-- workspace SSH proxy IP    -> <dc-id>.ssh.<base-domain>

The installer can manage PostgreSQL, Ceph, and Kubernetes on these machines. An external PostgreSQL database can also be described in the install configuration, but that alternative is outside the topology covered by this guide. An existing Kubernetes cluster can be used instead of the Codesphere-managed k0s cluster; see Use an existing Kubernetes cluster. See Architecture for the components this installs in more detail, and Installation options for the decisions to make before provisioning anything.

Provision the machines​

Before provisioning anything, decide on the domain, datacenter identity, IP addresses, registry credentials, and access details — see Requirements and sizing — and choose a topology (minimum versions and the POC/production sizing tables are also in Requirements and sizing).

Then, for every host:

  • Place it on one private routed network, with no CIDR overlap against the Kubernetes pod/service networks; reserve the three external addresses and apply the boundary firewall rules — see Networking, firewalls, and DNS.
  • Give the jumpbox administrative SSH access to it.
  • Apply the required kernel tuning.

See Provision the hosts for the concrete steps.

Prepare the jumpbox​

Install OMS, sops, and age on the jumpbox and create the secrets directory. See Prepare the jumpbox and generate the configuration.

Prepare access to GitHub Container Registry​

Request GHCR credentials from Codesphere before generating the install configuration. See Prepare the jumpbox and generate the configuration.

Generate the install configuration and secrets​

Run oms init install-config to produce config.yaml and prod.vault.yaml, choose a profile, and optionally point at an existing Kubernetes cluster. See Prepare the jumpbox and generate the configuration.

Choose an install configuration profile​

See Prepare the jumpbox and generate the configuration and Install steps and profiles.

Use an existing Kubernetes cluster​

See Prepare the jumpbox and generate the configuration.

Encrypt and place the secrets​

Encrypt prod.vault.yaml with SOPS and age before it leaves your workstation. See Encrypt the secrets and configure DNS.

Configure DNS​

Create the platform gateway, workspace gateway, and workspace SSH proxy DNS records. See Encrypt the secrets and configure DNS.

Install Codesphere​

Download the installer package from the Codesphere package portal, then run oms install codesphere from the jumpbox. Individual steps can be skipped with --skip-steps; see Install steps and profiles for the full reference. See Run the installer for the concrete steps.

Verify the installation​

Confirm the platform gateway, workspace gateway, and workspace SSH proxy services received their reserved addresses, then confirm nodes, Ceph, the certificate, and a workspace all work end to end. See Run the installer and Verify the installation.

Where to go from here​

For day-2 operations, see Upgrades and maintenance and Cluster monitoring. For per-installation configuration such as certificates, gateways, and Git providers, see Configure the platform. For the config schema, vault secrets, and install steps, see Reference.