​
Prerequisites

Before starting, you’ll need:
  • A Ctrlplane Workspace (cloud-hosted or self-hosted)
  • The Ctrlplane CLI installed on your local machine

​
Step 1: Create a System

A System in Ctrlplane organizes related deployments and environments into logical groups. This structure helps maintain consistency and simplifies management. To create your first system:
  1. In the Ctrlplane UI, click the + button in the top left corner
  2. Select New System from the dropdown menu
  3. Enter a descriptive name (e.g., Hello World Demo)

​
Step 2: Create a Deployment

A Deployment in Ctrlplane represents a complete delivery process for your software or infrastructure. It orchestrates how changes move through your environments. To create a deployment:
  1. Click the + button in the top left corner
  2. Select New Deployment from the dropdown
  3. Keep the default option selected for this example
  4. Enter a name for your deployment (e.g., Hello World Deployment)
  5. Click Create

​
Create a new Resource

Resources in Ctrlplane represent entities that your deployments can target - these can be infrastructure components like servers and databases, or abstract concepts like API endpoints and service accounts. For this tutorial, we’ll create a simple resource to represent a server:
  1. Click the + button in the top left corner to open the menu
  2. Select New Resource from the dropdown
  3. Fill in the following details:
    FieldValueDescription
    Nameserver-aA name for your resource
    Identifierdeployment-server-aA unique identifier used to reference this resource within your workspace
    KindServerThe type of resource being created
    Versiontutorial/v1The API version for this resource type
    Configuration{}Resource-specific configuration options (empty for this tutorial)
    Metadatatutorial = trueAdditional metadata tags for organizing resources under environments
  4. Click Create
In a real deployment, you would configure additional details like connection information and authentication. For this tutorial, we’re creating a placeholder resource just to demonstrate the workflow.

​
Configuring Environments

When you create a new system, Ctrlplane automatically creates three default environments: QA, Staging, and Production. For this simple example, we’ll keep just one environment and delete the others. To delete environments:
  1. Click on the “Environments” tab in the left sidebar under your system
  2. For each environment you want to delete:
    • Click on the environment node in the tree view
    • Click on the three dots menu (⋮) next to the environment name in the top left of the drawer
    • Click the Delete button from the dropdown
  3. Keep only one environment (e.g., Production) for this tutorial
  4. Click on the Production environment node in the tree view
  5. Go to the Resources tab
  6. Here you can create a filter to down to the resources this environment to the resource we previously created (see image below).
While this tutorial uses a simple single environment setup, real-world deployments often require more sophisticated environment organization.For example, in globally distributed systems, you might organize environments by geographic regions.

​
Create Job Agent

A Job Agent executes deployment tasks. For this tutorial, we’ll create a job agent to run scripts on your local machine.
  1. Download and install the Ctrlplane CLI
  2. Get your API key from <Workspace Name> > Workspace Settings > API Keys
  3. Get your workspace ID from <Workspace Name> > Workspace Settings > General
  4. Run the following command: 
    ctrlc run exec \
    --name tutorial-agent \
    --api-key <your-api-key> \
    --workspace <your-workspace-id>
    This agent will execute scripts that you configure in the UI when jobs are triggered.
Keep this process running as it listens for jobs to execute when deployments are triggered.
Job Agents execute deployment tasks in your infrastructure. In production, you would configure agents with appropriate permissions and access to your deployment targets. For this tutorial, we’re using a basic configuration.

​
Connect Agent to Deployment

  1. Navigate to your deployment settings page
  2. Find the Job Agents section
  3. Select your job agent from the dropdown
  4. Add this simple script: 
    echo "Deploying Hello World {{.release.version}} to {{.resource.name}}"
  5. Click Save

​
Create a Release

  1. Go to the release page and click Create Release
  2. Enter a name like v1.0.0
  3. Click Create

​
Deploy the Release

When the release is created, the job agent will be triggered. You should see this output in your job agent terminal: