Skip to main content
Version: Weekly Build

Run the Installer

Before you start​

config.yaml and the encrypted prod.vault.yaml should be in place on the jumpbox, and DNS records should be created or explicitly deferred (see Encrypt the secrets and configure DNS).

Obtain the installer package​

Browse the available Codesphere packages and download the selected installer build on the jumpbox:

oms list packages
oms download package --version <version>

Install Codesphere​

Codesphere needs a secrets directory, but oms install codesphere does not have a separate --secrets-dir flag. Set the directory in /etc/codesphere/config.yaml:

secrets:
  baseDir: /etc/codesphere/secrets

The configured directory should match the directory containing the file passed through --vault. Before installing, confirm that the directory and required files are present and readable only by root:

install -d -m 0700 /etc/codesphere/secrets
chmod 0600 /etc/codesphere/secrets/age_key.txt
chmod 0600 /etc/codesphere/secrets/prod.vault.yaml
test -r /etc/codesphere/secrets/age_key.txt
test -r /etc/codesphere/secrets/prod.vault.yaml

Run the installation from the jumpbox. The lite package does not contain the platform container images, so skip load-container-images; the cluster pulls them directly from GHCR using the credentials in the vault:

oms install codesphere \
  --config /etc/codesphere/config.yaml \
  --priv-key /etc/codesphere/secrets/age_key.txt \
  --vault /etc/codesphere/secrets/prod.vault.yaml \
  --package <downloaded-installer-lite-package>.tar.gz \
  --skip-steps load-container-images

For the installation in this guide, only load-container-images is skipped because installer-lite.tar.gz contains no platform images. See Install steps and profiles for the full list of steps, what each --skip-steps name bypasses, and how to persist skips in config.yaml. Do not copy other skip steps into a rerun without checking which prerequisites already exist.

The combined command installs in this order:

  1. Copies and extracts dependencies.
  2. Skips loading bundled container images because the nodes pull them from GHCR.
  3. Installs SOPS and the container runtime dependencies.
  4. Installs or configures PostgreSQL.
  5. Installs and configures Ceph.
  6. Installs and configures k0s when Kubernetes is Codesphere-managed.
  7. Installs Argo CD, cluster dependencies, and managed-service backends.
  8. Installs the Codesphere platform.

The installation can also be run as the separate infra, dependencies, and platform phases when operational change control requires distinct checkpoints.

Complete the infrastructure integration​

If the selected infrastructure needs a Kubernetes cloud controller, install its supported provider integration and enable external cloud-provider mode on the k0s controller and workers. Use only manifests and service annotations intended for that infrastructure.

Confirm that the three services receive the reserved addresses:

alias kubectl='/etc/codesphere/deps/kubernetes/files/k0s kubectl'
kubectl get services -n codesphere -o wide | grep LoadBalancer

The gateway-controller, public-gateway-controller, and ssh-workspace-proxy services must retain their intended addresses. If the load-balancer implementation does not assign them from config.yaml, patch or annotate the services using that implementation's supported mechanism and then make the change persistent in the install configuration. See Gateway and load balancing.

If DNS configuration was deferred because these external addresses were not available earlier, create and verify the records described in Configure DNS now.

Verify the installation​

Complete these checks before handing over the environment:

  1. All k0s nodes are Ready.
  2. Ceph reports healthy and all expected OSDs are present on all three POC hosts or at least four production hosts.
  3. The three load-balancer services have the reserved external addresses.
  4. https://<base-domain> presents a trusted certificate and loads Codesphere.
  5. A workspace can be created, reached over HTTPS, and reached through the workspace SSH proxy.

Run the Codesphere smoke test when an API key for the environment is available:

oms smoketest codesphere --help

What you should have now​

  • Codesphere installed and all verification checks above passing.
  • The platform gateway, workspace gateway, and workspace SSH proxy reachable at their intended DNS names.

Next​

For ongoing operation, see Upgrades and maintenance and Cluster monitoring. To evaluate Codesphere on a single machine instead of this multi-host topology, see Single-node evaluation install.