Prepare infrastructure and install Codesphere

This guide describes how to prepare infrastructure for Codesphere without depending on a specific cloud provider.

Choose the POC or production topology below, then increase capacity for the expected users, workspaces, storage consumption, and failure tolerance.

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       -> cs.<base-domain> and *.cs.<base-domain>
    +-- workspace gateway IP      -> <dc-id>.<base-domain> and *.<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 or an existing Kubernetes cluster can also be described in the install configuration, but those alternatives are outside the topology covered by this guide.

Collect the required inputs​

Decide on the following before provisioning anything:

• A base domain whose DNS zone you can change.
• A datacenter ID, name, city, and country code.
• Stable private IP addresses for every machine.
• A public IP address for the jumpbox. This is separate from the service addresses and should accept SSH only from trusted administrator networks.
• Three stable, externally reachable service IP addresses: platform gateway, workspace gateway, and workspace SSH proxy.
• GitHub Container Registry credentials supplied by Codesphere. Codesphere nodes currently pull images directly from ghcr.io, and customers must request the required username and token from Codesphere.
• Access to the Codesphere package portal.
• An initial cluster administrator email, if desired.
• OAuth credentials for each Git provider or OIDC provider that users will use.
• An SSH key with administrative access to all hosts.

Git provider credentials must be supplied as complete sets. For example, a GitHub App needs its app name, client ID, and client secret; an OIDC provider needs its issuer URL, client ID, and client secret.

Provision the machines​

Provision x86-64 machines and choose a topology based on the purpose of the installation.

Minimum supported versions​

Codesphere requires:

• Ubuntu 22.04 LTS or a newer supported version
• Kubernetes 1.31 or newer
• Ceph 18.2 or newer

The Kubernetes and Ceph minimums also apply when those components are installed or managed outside OMS.

POC topology​

Use this compact topology for proofs of concept, evaluation, and other non-production environments:

All three k0s nodes participate in the control plane and also provide workload capacity. This topology keeps the machine count low, but it does not provide the same maintenance and failure headroom as the production topology. Do not use it for production workloads.

Production baseline​

Use separate control-plane and worker pools in production. Start with:

Three control-plane nodes provide control-plane quorum and high availability. Start the separate worker pool with at least three 16-vCPU, 64-GiB machines, then scale it for workload CPU, memory, scheduling headroom, and the number of simultaneous node failures the platform must tolerate. Scale Ceph beyond four nodes and add data disks based on usable-capacity targets, replication overhead, recovery headroom, and growth.

Use 250 GiB Ceph data disks as the POC minimum and 500 GiB data disks as the production minimum. Present Ceph DB/WAL and data disks as distinct, unused block devices; do not format or mount them. For production, validate disk performance and size the DB/WAL device for the selected data devices and workload.

Use dedicated PostgreSQL storage and a replica when database availability is required. The POC topology keeps PostgreSQL on its root disk and has no replica.

Record the hostname and private IP of every host. Hostnames must be unique and resolvable consistently, either through internal DNS or /etc/hosts.

Configure the private network​

Place all machines on one private routed network. For example, use 10.10.0.0/20. Any non-overlapping private CIDR is suitable if the same CIDR is recorded as ceph.nodesSubnet in the install configuration.

Provide unrestricted communication between Codesphere hosts on the private network. Kubernetes, Ceph, PostgreSQL, container registry, and SSH traffic all cross this network. If internal firewalls must be restrictive, derive and test an explicit port matrix for the selected Kubernetes and Ceph versions before installation.

Hosts without public addresses need outbound access through NAT or an HTTP proxy. They must be able to reach package repositories, the selected container registry, certificate endpoints, and any source URLs referenced by the installer.

Avoid CIDR overlap between the host network, Kubernetes pod network, Kubernetes service network, connected corporate networks, and VPNs.

Configure external access and firewalls​

Reserve three stable external addresses and connect them to Kubernetes LoadBalancer services using the infrastructure's load-balancer implementation:

1. The platform gateway serves HTTP and HTTPS.
2. The public workspace gateway serves workspace HTTP and HTTPS traffic.
3. The workspace SSH proxy serves SSH traffic for workspaces.

On a public cloud, install and configure that provider's Kubernetes cloud controller or load-balancer integration. On bare metal or other infrastructure without a native implementation, configure MetalLB with an address pool containing the reserved addresses. The addresses must remain stable across service and node restarts. If the integration can be completed only after Kubernetes is running, finish it in Complete the infrastructure integration.

Apply these boundary firewall rules:

Do not expose SSH or PostgreSQL to 0.0.0.0/0. PostgreSQL TCP 5432 normally needs to be reachable only from Codesphere hosts and approved administration or monitoring networks.

Establish administrative SSH access​

Configure the jumpbox as the only public SSH entry point. The jumpbox must be able to connect as an administrative user to every private host, and the hosts must be able to connect to one another where required by Ceph and k0s installation.

The installation workflow uses direct root SSH and SSH agent forwarding. If organizational policy forbids root SSH, provide an equivalent privileged automation path and verify it with the installer before proceeding. Protect the private key, restrict ingress to trusted source ranges, and use host-key verification in a production workflow.

From the jumpbox, verify every host:

ssh root@<postgres-private-ip> hostname
ssh root@<ceph-private-ip> hostname
ssh root@<k0s-private-ip> hostname

Tune every installation host​

Apply and persist the following kernel settings on the PostgreSQL, Ceph, and k0s hosts:

cat >/etc/sysctl.d/99-codesphere.conf <<'EOF'
fs.inotify.max_user_watches=1048576
fs.inotify.max_user_instances=8192
vm.max_map_count=262144
EOF

sysctl --system

Verify the active values:

sysctl fs.inotify.max_user_watches
sysctl fs.inotify.max_user_instances
sysctl vm.max_map_count

Keep time synchronized on every host. Confirm that hostnames, private addresses, attached disks, DNS resolution, outbound connectivity, and SSH access survive a reboot before installing Codesphere.

Prepare the jumpbox​

Install OMS on the jumpbox together with sops and age. Pin and verify approved versions so the environment is repeatable.

The jumpbox must have enough free space for the installer package and extracted installation dependencies. Create a root-only secrets directory:

install -d -m 0700 /etc/codesphere/secrets

Installer packages are always browsed and downloaded from the Codesphere package portal. Set the portal API key in the environment of the user that will run OMS on the jumpbox:

export OMS_PORTAL_API_KEY='<portal-api-key>'

The API key must remain set for subsequent OMS portal operations. Supply it through an approved secret manager or protected session setup, and do not commit it to a shell profile, image, or source repository.

Prepare access to GitHub Container Registry​

Codesphere images are pulled directly from GitHub Container Registry. Every k0s node must have outbound HTTPS access to ghcr.io and the related GitHub package endpoints.

Request the GHCR username and token from Codesphere before generating the install configuration. Customer-created GitHub personal access tokens do not automatically have access to the private Codesphere packages.

Registry authentication is currently in a transitional stage. For now, Codesphere provides separate GHCR credentials, and the token must be supplied to the install-configuration workflow as the registry password. A future version will use OMS portal authentication for registry access, removing the need to request and configure a separate GHCR token.

Keep the token ready for the configuration-generation step, but do not write it into shell history or config.yaml. Store it only in prod.vault.yaml as registryPassword, as shown below. Unauthenticated pulls or a token without package access will cause the platform installation to fail.

Generate the install configuration and secrets​

The OMS command for configuration generation is oms init install-config. It creates both inputs required by the installer:

• config.yaml describes the infrastructure, network, storage, registry, domains, authentication providers, plans, and enabled features.
• prod.vault.yaml contains generated passwords, private keys, certificates, and provider credentials. It is plaintext when generated and must be encrypted before it is stored or copied through an untrusted system.

Run the interactive generator from a trusted workstation or the jumpbox:

oms init install-config \
  --profile production \
  --config config.yaml \
  --vault prod.vault.yaml \
  --with-comments

Choose an install configuration profile​

The profile controls the default Codesphere software footprint, allowing the installation to fit differently sized infrastructure. It does not provision machines or automatically decide how many PostgreSQL, Ceph, control-plane, or worker nodes to use. The wizard or command flags must still describe the actual topology and IP addresses.

The profiles currently behave as follows:

The noRequests resource profile used by dev and minimal removes CPU and memory requests from Codesphere services and supporting charts. It also reduces several supporting components to one replica, including ingress controllers, Loki components, RGW load balancer, and managed-service backends. Selected core Codesphere services retain two replicas, but their resource requests are set to zero. This makes the Kubernetes scheduler accept a smaller cluster, but it removes resource guarantees and reduces failure tolerance. Do not interpret successful scheduling with this profile as proof that the hosts have enough real CPU or memory under load.

All profiles start with the same common infrastructure defaults, including Codesphere-managed Kubernetes, installed PostgreSQL, Ceph, LoadBalancer gateways, disabled MetalLB, and placeholder localhost addresses. They also start with the standard workspace and hosting plan defaults. Replace all placeholder topology, domain, registry, and secrets values during the wizard or configuration review.

Use minimal for the POC topology described in section 2 and production for the production baseline. Use dev only when disabling the bundled monitoring components is appropriate.

Optional Ansible inventory: Users who already maintain host topology in an Ansible inventory can import it with --ansible-inventory inventory.yaml. OMS reads the optional k8s-cp, k8s-workers, and ceph groups; each host needs a private_ip. For example:

k8s-cp:
  hosts:
    cp-1:
      private_ip: 10.10.0.11
k8s-workers:
  hosts:
    worker-1:
      private_ip: 10.10.0.21
ceph:
  hosts:
    ceph-1:
      private_ip: 10.10.0.31

Interactive mode is enabled by default. In that mode, the profile seeds the wizard, while individual non-interactive configuration flags are not applied. For automation, pass --interactive=false and provide every required value through flags and the profile. Treat a non-interactive validation failure as a missing or inconsistent input rather than bypassing it.

After generation, set the registry section in config.yaml to:

registry:
  server: ghcr.io
  replaceImagesInBom: false
  loadContainerImages: false

As part of install-config generation, set the existing registry entries in prod.vault.yaml to the GHCR username and token supplied by Codesphere. The token is the registry password:

secrets:
  - name: registryUsername
    fields:
      password: <codesphere-provided-ghcr-username>
  - name: registryPassword
    fields:
      password: <codesphere-provided-ghcr-token>

The username is intentionally stored in the password field used by the installer secret format. Keep both values in the vault and never place the token directly in config.yaml.

Review the generated files and ensure they describe the actual infrastructure:

• dataCenter contains the intended ID, name, city, and country code.

• secrets.baseDir is /etc/codesphere/secrets when following this layout.

• postgres.primary contains the PostgreSQL hostname and private IP, or postgres.mode describes the external database.

• ceph.nodesSubnet matches the private host network.

• ceph.hosts lists three hosts for a POC or at least four hosts for production, with exactly one initial master.

• ceph.csiKubeletDir is /var/lib/k0s/kubelet when Codesphere manages k0s.

• Each Ceph OSD definition selects only the intended, empty data and DB/WAL devices.

• kubernetes.apiServerHost is the first control-plane node's private IP, or a stable load-balancer address or DNS name when using multiple control-plane nodes.

• kubernetes.controlPlanes and kubernetes.workers assign every k0s node to its intended role. The production baseline uses three dedicated control-plane nodes and a separate worker pool:

  kubernetes:
    managedByCodesphere: true
    apiServerHost: 10.10.0.11
    controlPlanes:
      - ipAddress: 10.10.0.11
      - ipAddress: 10.10.0.12
      - ipAddress: 10.10.0.13
    workers:
      - ipAddress: 10.10.0.14
      - ipAddress: 10.10.0.15
      - ipAddress: 10.10.0.16
  

  Always list at least three addresses under controlPlanes for a highly available control plane. Dedicated worker addresses go under workers; increase that list for the expected workload CPU, memory, and failure tolerance.

  The interactive oms init install-config wizard asks separately for the comma-separated control-plane and worker IPs.

  k0s supports combined control-plane/worker nodes. However, the current OMS k0sctl configuration generator treats an IP present in both lists as control-plane-only and ignores the duplicate worker entry. Until combined-role generation is supported by OMS, use dedicated control-plane and worker entries in this workflow.

• The platform and public gateways use LoadBalancer, or ExternalIP where that is the chosen integration.

• codesphere.domain is cs.<base-domain>.

• codesphere.workspaceHostingBaseDomain and the custom-domain CNAME base are <dc-id>.<base-domain>.

• The workspace SSH proxy application is enabled and assigned its reserved address.

• ACME or another certificate issuer is configured for the selected DNS and load-balancer design.

• Git provider and OIDC redirect URLs use the final https://cs.<base-domain> address.

• The registry server is ghcr.io, replaceImagesInBom and loadContainerImages are false, and the vault contains valid registryUsername and registryPassword entries.

Use only annotations supported by the selected load-balancer implementation, or omit annotations when the implementation honors loadBalancerIP directly.

Encrypt and place the secrets​

Generate an age identity on the jumpbox and make it readable only by root:

age-keygen -o /etc/codesphere/secrets/age_key.txt
chmod 0600 /etc/codesphere/secrets/age_key.txt

Copy the generated files to the jumpbox, then encrypt the vault there:

install -m 0600 config.yaml /etc/codesphere/config.yaml
install -m 0600 prod.vault.yaml /etc/codesphere/secrets/prod.vault.yaml

sops --encrypt --in-place \
  --age "$(age-keygen -y /etc/codesphere/secrets/age_key.txt)" \
  /etc/codesphere/secrets/prod.vault.yaml

Back up config.yaml, the encrypted vault, and the age identity to an approved secret store. The age identity is required to recover or update the installation. Never commit the plaintext vault or age identity to source control.

Configure DNS​

Create these records after the three stable addresses are allocated:

Use a short TTL such as 300 seconds during initial setup. Depending on the DNS provider and network design, the records may be A/AAAA, alias, or load-balancer records. Ensure the certificate solver can update DNS when using DNS-01, or that TCP 80 reaches the platform gateway when using HTTP-01.

Some cloud-controller and load-balancer integrations assign external IP addresses only after Kubernetes and the provider integration are running. If the three addresses are not known yet, defer creating and verifying these records until Complete the infrastructure integration, then return to this table with the assigned addresses. Otherwise, verify every record from outside the private network before continuing.

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

Skip installation steps​

Skip steps make the installer resumable and allow it to work with prerequisites that are already installed or managed outside OMS. They are also useful when rerunning only a later phase after changing configuration. A skipped step is not validated or replaced by OMS, so skip it only when its result is already present or intentionally unnecessary; skipping a required prerequisite can make a later step fail.

Use --skip-steps for a single invocation, with multiple names separated by commas. To persist skips across future runs, add them to config.yaml:

operations:
  skip:
    - load-container-images

The supported skip names are:

The full installer package is deprecated. Current installations should use installer-lite.tar.gz and skip load-container-images. The step remains available only for compatibility with legacy full packages.

For the installation in this guide, only load-container-images is skipped because installer-lite.tar.gz contains no platform images. 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.

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://cs.<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

Appendix​

Codesphere Plans Configuration​

Plans define the resources available for developer workspaces. Configure this under the codesphere.plans section in your config.yaml.

• hostingPlans: Defines raw resource allocations. IDs must be numbers.
  • cpuTenth: CPU cores in tenths (e.g., 10 = 1 core, 25 = 2.5 cores).
  • gpuParts: GPU allocation (specific to your GPU setup).
  • memoryMb: Memory in Megabytes.
  • storageMb: Persistent storage for the workspace in Megabytes.
  • tempStorageMb: Ephemeral storage in Megabytes.
  • pooledInstances: Number of pre-warmed instances of this plan to keep ready.
• workspacePlans: Defines user-selectable plans, mapping to hostingPlans. IDs must be numbers.
  • name: Display name of the plan.
  • hostingPlanId: Links to an ID in hostingPlans.
  • maxReplicas: Maximum number of concurrent instances for a single workspace on this plan.
  • onDemand: true if users can start/stop these workspaces, false for always-on.

Example: (Already included in the main config.yaml example)

codesphere:
  # ... other codesphere settings ...
  plans:
    hostingPlans:
      1:
        cpuTenth: 10
        gpuParts: 0
        memoryMb: 2048
        storageMb: 20480
        tempStorageMb: 1024
      2:
        cpuTenth: 20
        memoryMb: 4096
        storageMb: 51200
        tempStorageMb: 2048
    workspacePlans:
      1:
        name: "Basic"
        hostingPlanId: 1
        maxReplicas: 1
        onDemand: true
      2:
        name: "Pro"
        hostingPlanId: 2
        maxReplicas: 3
        onDemand: true

Git Provider Configuration​

Configure Git provider integrations under codesphere.gitProviders in config.yaml. For each enabled provider, you'll also need to add corresponding clientId and clientSecret to your prod.vault.yaml secrets file (see Section 3.2).

General Structure for each provider:

# providerName e.g., github, gitlab
# providerName:
#   enabled: true # or false
#   url: "Base URL of the provider"
#   api:
#     baseUrl: "API base URL"
#   oauth:
#     issuer: "OAuth issuer URL"
#     authorizationEndpoint: "OAuth authorization URL"
#     tokenEndpoint: "OAuth token URL"
#     # Other provider-specific OAuth settings like scope, clientAuthMethod

Generating Credentials (Examples):​

• GitLab:

  1. Go to your GitLab Group (or User Settings for a user-level app) > Settings > Applications.
  2. Create a new application (e.g., "Codesphere Git Integration").
  3. Redirect URI / Callback URL: https://<codesphere.domain>/ide/auth/gitlab/callback (replace <codesphere.domain> with your Codesphere domain).
  4. Scopes: Select api, read_repository, write_repository. (Ensure openid, profile, email are also available/selected if needed for user profile info).
  5. Save the application. You'll get an "Application ID" (gitlabAppClientId) and a "Secret" (gitlabAppClientSecret).

• GitHub:

  1. Go to your GitHub organization settings > Developer settings > GitHub Apps > New GitHub App.
  2. Application name: e.g., "Codesphere Git Integration"
  3. Homepage URL: https://<your-codesphere.domain>
  4. Authorization callback URL: https://<your-codesphere.domain>/ide/auth/github/callback
  5. You'll get a "Client ID" (githubAppsClientId) and generate a "Client Secret" (githubAppsClientSecret).
  6. Optionally upload an image as a logo.

• Bitbucket (Server/Data Center - typically Application Links for OAuth 1.0a or OAuth 2.0 if supported):

  1. Admin Settings > System > Application Links.
  2. Create a new link. Choose "External Application", "Incoming".
  3. Redirect URL: https://<codesphere.domain>/ide/auth/bitbucket/callback
  4. Permissions: Repository read/write.
  5. You'll get a "Consumer Key" (bitbucketAppsClientId) and "Consumer Secret" (bitbucketAppsClientSecret) or similar, depending on OAuth version.

• Azure DevOps:

  1. Register an application in Azure Active Directory.
  2. Redirect URI: https://<codesphere.domain>/ide/auth/azureDevOps/callback (ensure it's added as a Web redirect URI).
  3. Note the "Application (client) ID" (azureDevOpsAppClientId).
  4. Go to "Certificates & secrets" -> "New client secret" to generate azureDevOpsAppClientSecret. Set a reminder to rotate this secret as it has an expiry.
  5. API Permissions: Add permissions for "Azure DevOps" -> user_impersonation and ensure vso.code_full is included in the scope in config.yaml.

Remember to add these Client IDs and Secrets to your prod.vault.yaml file and encrypt it. Example secrets names:

• githubAppsClientId, githubAppsClientSecret
• gitlabAppClientId, gitlabAppClientSecret
• bitbucketAppsClientId, bitbucketAppsClientSecret
• azureDevOpsAppClientId, azureDevOpsAppClientSecret

Managed Service Configuration​

Every Service offered through the Managed Services section is configured as a individual Managed Service Provider in the codesphere.managedServices array in config.yaml. The configuration follows a specific schema.

Managed Service Providers could be external to Codesphere, i.e. an external API is called, but there are also built-in Managed Services, where the Provider is running within Codesphere. With the current release there is 1 such Provider for PostgreSQL.

Codesphere comes with a set of preconfigured providers. If you want to enable any of those providers simply specify name and version:

  managedServices:
    - name: postgres
      schemaVersion: v1
    - name: babelfish
      schemaVersion: v1
    - name: s3
      schemaVersion: v1
    - name: virtualK8sV1
      schemaVersion: v1

If you are using any of those providers, please ensure to enable the respective backend in the managedServiceBackends section as well.

It is possible to override properties of the preconfigured providers, or even implement and add your own providers (see Create your own REST Backend). The following snippet shows an exemplary full configuration of the Postgres Managed Service Provider.

  managedServices:
    - name: postgres
      schemaVersion: v1
      backend:
        api:
          endpoint: "http://ms-backend-postgres.postgres-operator:3000/api/v1/postgres"
      author: Codesphere
      category: Database
      displayName: PostgreSQL
      iconUrl: /ide/assets/managed-services/postgresql.svg
      configSchema:
        type: object
        properties:
          version:
            type: string
            description: Version of the Postgres DB. Includes pre-installed extensions compatible with this version. Extension versions are managed and cannot be customized.
            enum:
              - '17.6'
              - '16.10'
            default: '17.6'
            readOnly: false
          userName:
            type: string
            default: app
            pattern: '^(?!postgres$)'
          databaseName:
            type: string
            default: app
        required: []
        additionalProperties: false
      detailsSchema:
        type: object
        properties:
          port:
            type: integer
          hostname:
            type: string
          dsn:
            type: string
          ready:
            type: boolean
        required:
          - port
          - hostname
          - dsn
          - ready
        additionalProperties: false
      secretsSchema:
        type: object
        properties:
          userPassword:
            type: string
            format: password
          superuserPassword:
            type: string
            format: password
        required:
          - userPassword
          - superuserPassword
        additionalProperties: false
      description: >-
        Open-source database system tailored for efficient data management and
        scalability. Deployed on Codesphere using the CNPG K8s Operator.
      plans:
        - id: 0
          description: 0.5 vCPU / 500 MB Memory
          name: Small
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                description: Storage (MB)
                type: integer
                default: 10000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                description: CPU Tenths
                type: number
                default: 5
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                description: Memory (MB)
                type: integer
                default: 500
                readOnly: true
        - id: 1
          description: 1 vCPU / 1 GB Memory
          name: Medium
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                description: Storage (MB)
                type: integer
                default: 25000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                description: CPU Tenths
                type: number
                default: 10
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                description: Memory (MB)
                type: integer
                default: 1000
                readOnly: true
        - id: 2
          description: 1 vCPU / 2 GB Memory
          name: Medium High-Mem
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                type: integer
                default: 25000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                type: number
                default: 10
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                type: integer
                default: 2000
                readOnly: true
        - id: 3
          description: 2 vCPU / 4 GB Memory
          name: Large
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                type: integer
                default: 50000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                type: number
                default: 20
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                type: integer
                default: 4000
                readOnly: true
        - id: 4
          description: 4 vCPU / 8 GB Memory
          name: Extra Large
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                type: integer
                default: 150000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                type: number
                default: 40
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                type: integer
                default: 8000
                readOnly: true

Create Custom Workspace Base Images​

The default base image for Workspaces already ships with many useful tools and libraries. However, you can create your own custom base images. One reason to customize base images are packages that are not avilable through Nix but need to be installed via apt.

The Codesphere OMS CLI provides a convenient way to start building your own custom base images.

Prerequisites:

1. On your host, install Docker and the Buildx plugin (if not already installed):
   sudo apt install docker.io docker-buildx
2. Install the OMS ClI as described at https://github.com/codesphere-cloud/oms
3. Use the extend baseimage command in OMS CLI, see
   oms-cli beta extend baseimage -h
4. This command extracts the default base image from the Codesphere installer bundle, loads it into your local Docker image cache, and generates a Dockerfile that you can extend.
5. Confirm with docker image ls that the base image (ghcr.io/codesphere-cloud/codesphere-monorepo/workspace-agent-VERSION) is available locally.
6. Edit the generated Dockerfile to add your custom dependencies.
7. As a best practise, place the Dockerfile into a subdirectory, e.g. ./docker. This ensures that in the following docker build command, only the necessary files are sent to the Docker daemon.
8. Retrieve the base image tag from the Dockerfile, e.g. codesphere-1-67-1-4dd9b346cc and use the same tag for your custom image.
9. Build the custom image with the following command:
   docker buildx build -f ./docker/custom.Dockerfile -t workspace-agent-24.04-mycorp:<TAG_TO_USE> --load ./docker
10. Tag and Push the image to your own registry with the same tag as the original image:
    docker tag workspace-agent-24.04-mycorp:<TAG_TO_USE> <YOUR_REGISTRY_URL>/workspace-agent-24.04-mycorp:<TAG_TO_USE>
docker login <YOUR_REGISTRY_URL> # if not already logged in
docker push <YOUR_REGISTRY_URL>/workspace-agent-24.04-mycorp:<TAG_TO_USE>