Landscapes & Workspaces

Landscapes and Workspaces are two core building blocks of Codesphere. A Landscape is a deployment configuration of your application and its architecture, defined by a single configuration file (ci.yml) in a declarative way. Each deployed instance of a Landscape is paired with a Workspace which provides the tools to configure, modify, deploy, and manage the Landscape.

What is a Landscape

A Landscape is a deployment configuration of your application and its architecture, fully defined by a single ci.yml file in your repository. This Infrastructure as Code (IaC) blueprint specifies your deployments, managed service dependencies, and how they connect through a secure private network. Because everything is version-controlled, you can deploy the same recipe to any Codesphere instance.

What is a Workspace

The Workspace is a dedicated cockpit for interacting with a specific Landscape instance. It runs on its own compute resources, but gets attached to the same file system mount as your landscape.

When you're not actively using a Workspace, it automatically spins down to conserve resources. When you return, it wakes up and restores your session. This on-demand model allows Workspaces to only consume compute while you're actively using it.

Each Workspace comes with an integrated set of tools (the Workspace Toolkit) that let you build, deploy, and monitor your Landscape. The toolkit is organized around three modes:

• Code & Collaborate: A fully-featured Cloud IDE with local IDE connectivity, Git integration, and real-time team collaboration
• CI & Deploy: Configure CI pipelines and CI profiles, manage environment variables, and control deployments
• Monitor: Track application health and logs, trace requests, and monitor workspace & application performance

To get started, check out the Quickstart: Deploy your first Application guide.

Have a feature request?

Help us shape the future of Codesphere. You can request new features or vote on the community roadmap at feedback.codesphere.com.

The Landscape Lifecycle

The lifecycle of a Landscape is managed through the Workspace Toolkit and can be broken down into four stages:

1. Define Your Landscape
   Using the Workspace tools or by modifying the IaC ci.yml file, you compose your Landscape from Codesphere's building blocks: compute runtimes, managed services, routing rules, and storage options. This declarative approach keeps your deployment version-controlled and reproducible.

2. Codesphere Instantiates the Landscape
   When a Landscape is synced, Codesphere provisions all resources and spins up your services. The platform keeps track of any changes to your ci.yml. To update your running Landscape, click the Sync button in the Execution Manager. For details, see Landscape Lifecycle.

3. Manage with the Workspace
   The Workspace Toolkit gives you full control over your Landscape. Write and test code or configuration in the Cloud IDE, trigger builds and manage secrets in the CI/Deploy panel, and use the Monitor tools to inspect logs, trace requests, and debug issues in real time.

4. Users Access the Application
   Once deployed, your services are exposed through the landscape router. Users reach your application via a custom domain or the dev domain, while internal services stay securely isolated within the private network.

Architectural Overview

The Workspace and corresponding Landscape instance are mounted to the same network file system but run on separate compute resources. This isolation ensures that Workspace activity (such as builds, dependency installations, or IDE operations) never impacts your live application's performance or availability.

loading...

What runs where:

• Workspace: Handles builds, dependency installations, file tree interactions, language servers, and terminal sessions.
• Each service in your Landscape: Runs on its own dedicated resources, serving your live application independently.

This means that even if your Workspace Deployment is running into errors (i.e., it is undersized for the type of workload running), your deployed Landscape services remain unaffected. This also means you can restart the Workspace (i.e., to get the latest version of Codesphere) without affecting the Landscape workloads.

Landscape Building Blocks

This section covers the core components that make up a Landscape. For a step-by-step guide on configuring these elements, see the Landscape Configuration article.

The ci.yml file

The ci.yml provides a standardized format to define your Landscape. You can configure it through the UI or edit the file manually in your repository. For a step-by-step guide, see Landscape Configuration. The file consists of two main sections:

• prepare: Defines the runtime environment and any dependencies as well as building your application
• run: Defines the deployment artifacts and their configuration

Below is an example of a ci.yml file that defines a Nextcloud application.

• Prepare: Fetches the application source and installs the necessary runtime dependencies using Nix to ensure environment reproducibility.
• Run: Configures the deployment resources, environment variables, and networking, then executes the command to start the service.

schemaVersion: v0.2

# 1. PREPARE: Define the runtime environment
prepare:
  steps:
    - name: Download Nextcloud
      command: wget -O nextcloud.zip https://download.nextcloud.com/server/releases/nextcloud-31.0.8.zip
    - name: Install Dependencies
      # We define the environment using Nix for reproducibility
      command: nix-env -iA nixpkgs.php83 nixpkgs.php83Extensions.pgsql nixpkgs.nginx

# 2. RUN: Orchestrate the Landscape
run:
  nextcloud:
    plan: 21
    env:
      # Internal networking is handled automatically
      PG_HOST: ms-postgres-internal-dns-string
      PG_PASSWORD: VAULT_PG_PASSWORD
    network:
      ports:
        - port: 3000
          isPublic: false # Secure internal port
      paths:
        - port: 3000
          path: /
    steps:
      - name: Start Stack
        command: |
          php-fpm -y ./nextcloud/php/nextcloud.conf
          nginx -c $(pwd)/nextcloud/nginx/nextcloud.conf

  pgnext:
    provider:
      name: postgres
      version: v1
    plan:
      id: 0

tip

This example file uses different runtime types (Codesphere Reactive, Managed Service) to define the Landscape. For a detailed breakdown of each runtime type, see the Runtimes article or find a short breakdown below.

Runtimes

Codesphere supports several runtime types within your Landscape:

• Codesphere Reactives: A containerized environment using a shared Codesphere base image with stateful serverless capabilities and millisecond startup times.
• Managed Containers: Bring your own Docker images while Codesphere provides the orchestration (scaling, IDE access, networking, and monitoring).
• Cloud Native Deployments: A virtual managed kubernetes cluster that can be used to deploy cloud native applications with full kubectl access.
• Virtual Machines (coming soon): A Kubevirt based virtual machine that can be configured with any custom image.
• Managed Services: Pre-configured services from the marketplace (databases, message queues, caches) that can be deployed and connected to your landscape.

For a detailed breakdown of each runtime type, see the Runtimes article.

Private Networking

By default, Landscapes are deployed within a secure private network. Services remain isolated and are only accessible from the public internet if explicitly configured in the ci.yml file or via the UI. For example, you could expose only an API gateway publicly while keeping backend microservices shielded from external traffic.

info

Container services (Reactives / Docker deployments) within a Landscape communicate using internal URLs: http://ws-server-[WorkspaceId]-[serviceName]:[port]. You can copy a service's internal URL from the Copy button in the port configuration panel.

These internal URLs are only resolvable within the Landscape's private network and cannot be accessed from the public internet or a user's browser. Public services can still be reached internally via their internal URL, but private services are only accessible through this internal network.

The Landscape Router

The Landscape Router defines the HTTP entry points to your publicly available reactive services (see Architectural Overview). When traffic arrives, the router inspects the request path and directs it to the appropriate service based on configured path prefixes.

Your services can be accessed through two types of URLs:

• Custom Domain: customdomain.com/* - your own domain, configured in the Domain Settings
• Dev Domain: https://[workspace-id]-3000.[datacenter-id].[your instance url]/* - Assigned to your Workspace by default

For example, if your Landscape defines three services (foo, bar, and tea), the router maps incoming requests like this:

• /foo/* → routes to the foo service
• /bar/* → routes to the bar service
• /tea/* → routes to the tea service

This path-based routing is configured in the network.paths section of your ci.yml for each service.

The router handles load balancing across service replicas automatically, ensuring requests are distributed evenly across all running instances of a service. It operates at the Landscape level, meaning each Landscape has its own isolated routing configuration, allowing multiple Landscapes to coexist with identical path structures without conflicts.

info

By default, the Landscape Router pings your reactive services on port 3000 to check their health. You can configure a custom health endpoints in the service configuration.

Network File System

Every Codesphere Reactive (including the Workspace deployment itself) is connected to a network file system. The total available storage is defined on the Workspace level and shared across all Reactive services in the Landscape. It can be changed in the Workspace settings from the Workspace table.

When setting up your application, ensure that services don't concurrently write to the same files during runtime to avoid data corruption. Best practice is to run each service in its own directory and configure that directory as a mount point.

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.

Troubleshooting & Common Issues

Issue	Root Cause	Solution
Services stuck in unhealthy state	Your application is not being detected by the Landscape Router	Ensure your application is running on port 3000 or configure a custom health endpoint in the service configuration
Files are lost after Workspace restart	Writing outside /home/user/app	Store all persistent data within the app directory
OOM during builds	Undersized Workspace plan	Upgrade Workspace resources from the Workspace settings in the Workspace table; deployed services remain unaffected
Service unreachable from browser	Service is not exposed publicly or is using incorrect port/path configuration	Check if the service is exposed properly via the landscape router confg in your ci.yml and verify the port settings