Skip to main content
Version: Weekly Build

Configuring a Landscape

A Landscape defines how your services are deployed and connected. You can add Compute Runtimes (Reactives, Managed Containers, Cloud Native Deployments) and Managed Services, configure their resources, networking, and environment. For a deeper technical overview, see Landscapes & Workspaces.

All configuration starts from the Landscape Config Editor:

  1. In your Workspace, open the Landscape Config Editor from the sidebar.
  2. Ensure the correct CI Profile is selected (e.g., default or dev). If you need to create one, see Using CI Profiles.
  3. Click the + Add New Service button on the right side of the Landscape Deployment section and select the service type you want to add.

From here you can configure your Landscape using the visual editor or by editing the ci.yml file directly.

Saving service configurations

The landscape config UI behaves as one large form that configures your ci.yml file. You can only save the configuration in the top level of the form.

Codesphere Reactives​

Codesphere Reactives are Codesphere's flagship runtime, best described as stateful serverless. They combine persistent filesystem access with automatic resource deallocation during idle periods and near-instant startup (milliseconds). For a detailed overview, see Runtimes.

To add a Reactive, select Reactive Service from the service type picker, then configure it using the sections below.

Runtime Config​

Landscape Config Editor showing runtime configuration fields for a Reactive service, including execution steps, base image selection, and mounting paths.

Execution Steps​

Execution steps define the commands that run when your service starts. These commands execute sequentially and should start your application process.

To add execution steps:

  1. Click + Add Execution Step
  2. Enter a name for the step (e.g., "Start Server")
  3. Enter the command to execute (e.g., npm start or node server.js)
  4. Repeat if additional steps are needed

Service Execution

The final step should typically be a long-running process (like a web server). If all commands exit, the service will be marked as unhealthy: The service is running, but its pipeline is no longer executing.

Base Image Configuration​

Reactives use a shared, Codesphere-maintained Ubuntu base image by default (Codesphere Defaults). This image is pre-warmed and pooled for near-instant startup (milliseconds). You can customize the runtime environment by installing dependencies via Nix. There is also a Custom Base Image option available for advanced use cases, which acts as the basis for Managed Containers.

Mounting Paths​

By default, all Reactive services mount the entire /home/user/app directory from the shared network filesystem. You can restrict a service to only mount a specific subdirectory using the Mounting Paths setting.

Use cases for mount sub paths:​

  • Isolate file access between services to prevent accidental overwrites
  • Improve security by limiting each service's filesystem scope
  • Organize multi-service architectures with dedicated directories

warning

Only files written in /home/user/app are persisted to the network file system and shared across all services. Files written elsewhere exist only on the local disk of that specific pod and will not be available to other services or replicas. These local files are also lost across Workspace restarts which may happen due to scaling or Codesphere updates.

Resources​

Landscape Config Editor resources section showing plan selection, availability mode options, replica controls, and estimated monthly cost summary.

Each service has a resource plan that determines the vCPUs, memory, and storage allocated to it. The available plans and their pricing are configured by your cluster administrator and may vary between installations.

To configure resources:

  1. Select a Plan from the list (each plan shows its vCPU, memory, and storage allocation)
  2. Set the Availability mode:
    • Always on: The service runs continuously, ideal for production workloads
    • Off when unused: The service automatically stops after a period of inactivity and restarts when the domain or workspace is accessed, great for preview deployments or development environments
  3. Set the Default Replicas count for horizontal scaling using the − / + controls

info

The screenshot shows a cost summary at the bottom with per-resource and total monthly cost estimates. Note that this may not be visible on all installations.

For details on how plans are defined and customized, see the Plans Configuration article.

Scaling strategies:​

TypeDescriptionBest For
Vertical ScalingIncrease vCPUs/memory by selecting a higher planCompute-intensive or memory-intensive workloads
Horizontal ScalingAdd multiple replicas of the same serviceHandling increased request volume

Ports & Routes​

Landscape Config Editor ports and routes section showing health check settings, exposed service ports, and workspace router path mappings.

Health Check​

By default, the Landscape Router pings your Reactive services on port 3000 to check their health. You can configure a custom health endpoint, e.g. http://localhost:8080/health, if your application uses a different port or path for health checks. Furthermore, the request is executed from within the service container, so the application must be accessible at localhost. If it is bound to a different interface, specify the appropriate IP address or hostname instead.

info

Every service needs at least one route defined. Without a route, the Workspace Router does not pick up the service — it will not be considered healthy and will not be reachable from outside the Landscape.

Configure Ports​

This section defines the ports your service exposes. Internal communication between services should use internal port URLs, while ports can be made accessible through the Workspace Router below. Routing can also be customized further via custom domains.

Reactives within a Landscape communicate using internal URLs: http://ws-server-[WorkspaceId]-[serviceName].workspaces:[port]. You can copy a service's internal URL from the Copy button on the right-hand side.

To expose a new port:

  1. Click + Add New Port on the right side
  2. Enter the Port number your application listens on
  3. Optionally, you can expose a Public Port URL via the action menu (three-dot icon) on the port row. This directly exposes a public URL for the port, which can be copied via the context menu. This is less secure than using path routing and typically only needed in older legacy frameworks.

Workspace Router​

Routes map incoming HTTP requests to your services based on URL path prefixes. The router also supports a Strip Path option that removes the matched prefix before forwarding the request to your service.

To add a route:

  1. Click + Add New Route
  2. Enter the Path prefix (e.g., /, /api, /admin)
  3. Select the Port to route traffic to
  4. Optionally enable Strip Path to remove the prefix before forwarding

The Routing for Other Services section at the bottom shows routes defined by other services in the same Landscape, which is helpful for spotting conflicts or getting an overview of the full routing table.

Environment Variables​

Landscape Config Editor environment variables section showing key-value entries and selectable sources such as secrets, workspace values, and team identifiers.

Environment variables let you pass configuration to your services without hardcoding values. They are injected at runtime.

To add environment variables:

  1. Open the Environment Variables section in the service configuration
  2. Click + Add New Variable
  3. Enter the Key (variable name)
  4. Enter the Value, either as plain text or by selecting from the dropdown categories: User Inputs, Global Values, Secrets, Global Constants, Team ID, or Workspace ID

For more details, see Environment Variables.

Managed Containers​

Managed Containers are Reactives at their core, but let you bring your own Docker image instead of using the Codesphere-maintained base image. This means you get the same platform orchestration, networking, and monitoring while running a custom container. For a detailed overview, see Runtimes.

To add a Managed Container, select Managed Container from the service type picker.

Managed Container runtime configuration view showing image reference, startup arguments, mounting paths, and run-as user and group settings.

Corresponding accessible text description

Base Image Configuration:​

  • Enter the full image reference (e.g., nginx:1.25-alpine, node:20-slim)
  • For private registries, ensure appropriate credentials are configured
  • Set Startup Args to override the container’s default command if needed. The entrypoint remains the image’s default. If you want to override the entrypoint, you would need to use Codesphere Reactives instead and use your image as a custom base image.
  • Set Mounting Paths (volumeMounts) to control which directories or files from the workspace are mounted into the container and where.

Run As User/Group:​

  • Set User ID (runAsUser) to define which user account the service runs as inside the container.
  • Set Group ID (runAsGroup) to define which user group the service belongs to inside the container.
  • These control file access and process-level permissions and should match the ownership expectations of your application and mounted files.

The access level to the workspace filesystem depends on which User ID or Group ID you set here:

  • Using the User ID 1501, the container process will have the same read/write access to the workspace files.
  • Using a different User ID, the container process will have read access to all files and write access to the root of the mounted volume but not to subdirectories.
  • Regardless of your configured Group ID, Codesphere adds the GID 1010 directly for the Workspace FS. The defined GID affects the owner group of files created by your Services.
  • You can set write access to a specific subdirectory for the Group ID by running chmod g+w some-dir in the prepare stage.

Startup Performance

Managed Containers have startup times in the seconds range (vs milliseconds for Reactives) due to image pulling and initialization. Actual speed depends on image size and network performance to the registry.

All other configuration options (resources, ports, routes, environment variables) work the same as for Codesphere Reactives — see the sections above.

Cloud Native Deployments​

Cloud Native Deployments provide a virtual managed Kubernetes cluster with full kubectl access, designed for advanced orchestration scenarios. For a detailed overview, see Virtual Clusters.

Expert Runtime

This runtime is aimed at users with prior Kubernetes experience. If you're new to container orchestration, consider starting with Codesphere Reactives or Managed Containers.

Set up a Cloud Native Deployment​

  1. Provision the cluster: Add a virtual Kubernetes cluster from the Managed Services section of the UI or API. Note that each team can only have one virtual cluster at a time.
  2. Access the cluster: Once provisioned, retrieve the kubeconfig from the API to connect using kubectl.
  3. Deploy workloads: Use kubectl commands in the prepare or run steps, or interact directly via the terminal.

Platform Integration​

Deep lifecycle integration into the Codesphere ci.yml is currently a work in progress. Available features:

FeatureStatus
Virtual cluster provisioning✅ Available
kubectl access✅ Available
Helm deployments✅ Available
Monitoring integrationManual configuration required
Networking integrationManual configuration required

For full platform features (automatic monitoring, integrated networking, off-when-unused), use Reactives or Managed Containers.

Managed Services in Landscapes​

While you can create standalone Managed Services that persist indefinitely, for many use cases it is best practice to define Managed Services as part of your Landscape configuration. This ensures that your application environments are self-contained and reproducible.

For example, when you spin up a Development or Staging Landscape, Codesphere can automatically provision a dedicated PostgreSQL database for that specific environment, and tear it down when the Landscape is no longer needed.

Adding a Managed Service to a Landscape​

You can define Managed Services in your ci.yml (or specific CI Profile like ci.dev.yml) using the Landscape Config Editor or by editing the YAML file directly.

Landscape editor view for configuring a managed service entry in the ci.yml form.

  1. Select Type: Choose **Databases & More ** from the dropdown/modal.
  2. Choose Provider: Select the service you need (e.g., PostgreSQL, Redis, S3).
  3. Configure: Set the version, plan, and configuration parameters.
    • Name: Specify a name (e.g., primary-db). This name will be used to reference the service within your Landscape.
  4. Secrets: Define the secrets required by the service (e.g., passwords). You can reference project-level secrets or generate new ones.
  5. Save: The service is now added to your Landscape profile. It will be provisioned the next time you deploy this Landscape.

Connecting to the Service​

Once a Managed Service is provisioned, your application can connect to it. See the Managed Service Provider Reference for provider-specific connection details.

Service Discovery & Environment Variables​

Codesphere allows you to inject connection details into your application using Environment Variables.

  1. Secrets: You can pass the secrets defined in the Managed Service directly to your application's environment variables.
  2. Hostnames: To see concrete hostname construction examples for a specific service, check that provider's page in the provider reference.

Lifecycle Management​

  • Creation: The Managed Service is created when the specific Landscape Profile (e.g., dev) is deployed.
  • Updates: Changes to the ci.yml configuration (e.g., changing the plan or config) will update the service on the next deployment.
  • Pause: If the Landscape supports "Off when unused", the Managed Services may also be paused to save costs (depending on the service capabilities).
  • Deletion: When the Landscape is deleted, the associated Managed Services are automatically destroyed, preventing orphan resources and extra costs.

service renaming

Renaming a managed service in the ci.yml file requires the system to recreate it, which could lead to data loss.

Differences from Standalone Services​

FeatureLandscape Managed ServiceStandalone Managed Service
DefinitionDefined in ci.ymlCreated via UI / API manually
LifecycleTied to Landscape (created/deleted with it)Independent (persist until manually deleted)
Use CaseDev, Test, Review EnvironmentsProduction, Long-running Shared Databases
ConfigurationInfrastructure as Code (Git-tracked)Manual Configuration

Versioned ci.yml Schemas​

# Example fixture for the current schema after the managed-service provider schemaVersion rename.
# `schemaVersion` pins the fixture to the current pipeline schema.
schemaVersion: v0.4

# `prepare` runs setup before tests and deploys.
prepare:
  # `steps` lists sequential setup commands.
  steps:
    # `name` is a descriptive label only.
    - name: Install dependencies
      # `command` is the shell command to execute.
      command: yarn install

# `test` runs verification commands after setup.
test:
  # `steps` keeps the same stage shape as `prepare`.
  steps:
    # `name` documents the test step.
    - name: Run unit tests
      # `command` runs the example test suite.
      command: yarn test --run

# `run` contains the named deploy targets for the workspace.
run:
  # Reactive runtime with the full set of supported server fields.
  reactive-app:
    # `steps` defines the lifecycle commands for a reactive runtime.
    steps:
      # Build the app before startup.
      - name: Build app
        # Produce deployable build output.
        command: yarn build
      # Start the application process.
      - name: Start app
        # Launch the runtime server.
        command: yarn start
    # `image` optionally customizes the reactive base image.
    image: ghcr.io/codesphere-cloud/example-reactive:latest
    # `healthEndpoint` is probed to determine readiness.
    healthEndpoint: http://127.0.0.1:3000/healthz/app
    # `plan` selects the workspace plan.
    plan: 20
    # `replicas` requests horizontal scaling.
    replicas: 2
    # `isPublic` is ignored when advanced `network` settings are present.
    isPublic: true
    # `network` defines exposed ports and routed paths.
    network:
      # `ports` exposes raw runtime ports.
      ports:
        # `port` is the runtime port number to expose.
        - port: 3000
          # `isPublic` makes the port reachable from outside the workspace.
          isPublic: true
        - port: 9229
          isPublic: false
      # `paths` maps HTTP prefixes onto runtime ports.
      paths:
        # Route the root path to port `3000`.
        - port: 3000
          path: /
          stripPath: false
        # Route `/api` to port `3000` and strip the prefix.
        - port: 3000
          path: /api
          stripPath: true
    # `env` injects runtime environment variables.
    env:
      # Example string env var.
      NODE_ENV: production
      # Example numeric env var.
      PORT: 3000
    # `runAsUser` sets the runtime UID.
    runAsUser: 1000
    # `runAsGroup` sets the runtime GID.
    runAsGroup: 1000
    # `volumeMounts` attaches workspace storage into the runtime.
    volumeMounts:
      # `name` selects the workspace volume.
      - name: _workspace
        # `mountPath` is the destination inside the runtime.
        mountPath: /home/user/app
        # `workspacePath` selects which subdirectory to mount.
        workspacePath: ""

  # Container runtime with the full set of supported server fields.
  container-app:
    # `image` is required for container runtimes.
    image: ghcr.io/codesphere-cloud/example-container:latest
    # `command` overrides the image entrypoint/command.
    command:
      # First argv entry.
      - node
      # Second argv entry.
      - server.js
    # The rest of the fields are shared with reactive runtimes.
    healthEndpoint: http://127.0.0.1:8080/healthz/app
    # `plan` selects the workspace plan.
    plan: 20
    # `replicas` requests horizontal scaling for this runtime.
    replicas: 1
    # `isPublic` allows the routed service to be reachable externally.
    isPublic: true
    # This simple network shape publishes one routed path.
    network:
      # `path` is the public prefix for this service.
      path: /container
      # `stripPath` controls whether the prefix is preserved upstream.
      stripPath: false
    env:
      # Example string env var.
      NODE_ENV: production
      # Example numeric env var.
      PORT: 8080
    # `runAsUser` sets the runtime UID.
    runAsUser: 1000
    # `runAsGroup` sets the runtime GID.
    runAsGroup: 1000
    # `volumeMounts` attaches workspace storage into the runtime.
    volumeMounts:
      # `name` selects the workspace volume.
      - name: _workspace
        # `mountPath` is the destination inside the runtime.
        mountPath: /home/user/app
        # `workspacePath` selects which subdirectory to mount.
        workspacePath: ""

  # Managed service runtime in v0.4:
  # - `provider.version` was renamed to `provider.schemaVersion`
  # This key names the managed service instance.
  postgres:
    # `provider` identifies the catalog entry to provision.
    provider:
      # `name` selects the managed service type.
      name: postgres
      # `schemaVersion` is the renamed provider version field in v0.4.
      schemaVersion: "14"
    # `plan` selects the service plan and sizing.
    plan:
      # `id` identifies the chosen catalog plan.
      id: 1
      # `parameters` contains provider-specific numeric options.
      parameters:
        # `storage` requests disk capacity.
        storage: 1024
        # `cpu` requests compute capacity.
        cpu: 1
        # `memory` requests RAM capacity.
        memory: 512
    # `config` contains non-secret provider configuration.
    config:
      # `database` is an example provider config key.
      database: app
      # `extensions` shows that lists are allowed in config payloads.
      extensions:
        - pgcrypto
    # `secrets` contains secret provider configuration.
    secrets:
      # `password` is an example secret key.
      password: secret