2. Deploy your own application

Download the quickstart frontend, build its container image with the CLI, push it to your org’s private registry, and run it as a workload.

Overview

Part 1 ran an image someone else built. This part builds your own from source with cpln image build, pushes it to your org’s private registry, and runs it as the frontend workload, a Next.js launch page for a product about to open its waitlist. Every later update rolls out the same way, with the version already serving answering until the new one is ready in each location.

What you’ll build:

• A container image of the quickstart frontend, built from its source with no Dockerfile.
• The image stored in your org’s private registry.
• A frontend workload serving the launch page from both locations of quickstart-gvc.

Prerequisites

• Completed 1. Deploy your first workload: the quickstart-gvc GVC exists.
• Docker installed and running, or build on Control Plane with the --remote flag in step 4.

Step 1: Install the CLI

The CLI builds the image and pushes it to your org’s private registry.

npm

npm install -g @controlplane/cli

Requires Node.js version 18 or later (an active LTS release is recommended).

Homebrew

brew tap controlplane-com/cpln && brew install cpln

Binary

Download the binary

Pick your platform on the installation page.

Confirm the installation:

cpln --version

The CLI version number prints.

Step 2: Authenticate

Log in to Control Plane:

cpln login

The CLI prints a login URL and a six-digit confirmation code, then waits. Open the URL in a browser on any device, sign in, and enter the code. After the CLI confirms the login, set your default org (replace my-org with your org name):

cpln profile update default --org my-org

Step 3: Download the frontend

macOS / Linux

Downloads frontend.tgz, a gzipped tar archive.

Windows

Downloads frontend.zip, the same source as a zip archive.

Extract the archive and navigate to the directory:

macOS / Linux

tar -xvf frontend.tgz && cd frontend

Windows PowerShell

Expand-Archive frontend.zip && cd frontend

The frontend is a Next.js site: the launch page of a product called Beacon, with a waitlist form. site.config.ts holds the product name, tagline, description, and three features. The footer names the location that served the request, read from the environment variables Control Plane injects. The waitlist stays closed until part 3 connects the API that stores the signups.

Step 4: Build and push the image

With Docker

cpln image build --name frontend:1.0 --push

The build runs through Docker on your machine and pushes the result to your org’s private registry.

Without Docker

cpln image build --name frontend:1.0 --remote

The source is uploaded and built on Control Plane, and the image is pushed for you.

cpln image build detects the application type from its source and builds the image, so the application needs no Dockerfile: with Docker it uses Buildpacks, and with --remote the Control Plane build service does the detection. When a Dockerfile is present, the command uses that instead. The command ends by printing the image it pushed and its link, where your-org is the name of your org:

{
  "image": "your-org.registry.cpln.io/frontend:1.0",
  "link": "/org/your-org/image/frontend:1.0"
}

With --remote, a Pushed your-org.registry.cpln.io/frontend:1.0 in 42s line reports the push just above it.

Your org’s private registry now holds the image. List it:

cpln image get frontend:1.0

NAME           PULL                                    DIGEST             CREATED         TAGS
frontend:1.0   your-org.registry.cpln.io/frontend:1.0  sha256:5d2afe...   5 minutes ago

PULL is the address Docker would pull from. Workloads in your org reference the image as //image/frontend:1.0.

Console

Step 5: Create the workload

1. Navigate to Workloads

   Click Workloads in the left menu, then click New.

2. Configure basic settings

   Enter frontend as the name and make sure quickstart-gvc is the selected GVC.

3. Configure the container

   Click Containers in the left pane and keep Control Plane as the image source. In the image dropdown, type frontend and select frontend:1.0. Under Ports, keep protocol http and number 8080.

4. Configure the firewall and create

   Click Firewall in the left pane, click Make Public, then click Create. The workload summary page opens.

Step 6: Open the application

1. Wait for deployment

   The workload health shows Ready once the first deployment completes.

2. Open the canonical endpoint

   Under Endpoints, click the link next to Canonical Endpoint (Global). The launch page opens in a new window.

CLI

Step 5: Create the workload

cpln workload create --name frontend \
  --image //image/frontend:1.0 \
  --gvc quickstart-gvc \
  --port 8080 \
  --public

The //image/ prefix tells Control Plane to pull the image from your org’s private registry.

Step 6: Open the application

Wait for the workload to become ready:

cpln workload get frontend --gvc quickstart-gvc

When the READY column shows true, open the launch page:

cpln workload open frontend --gvc quickstart-gvc

Terraform

Step 5: Define the workload

Add to your existing main.tf from part 1:

resource "cpln_workload" "frontend" {
  gvc  = cpln_gvc.quickstart.name
  name = "frontend"
  type = "standard"

  container {
    name   = "frontend"
    image  = "/org/my-org/image/frontend:1.0"
    cpu    = "50m"
    memory = "128Mi"

    ports {
      protocol = "http"
      number   = 8080
    }
  }

  options {
    capacity_ai     = true
    timeout_seconds = 5

    autoscaling {
      metric    = "disabled"
      target    = 95
      min_scale = 1
      max_scale = 1
    }
  }

  firewall_spec {
    external {
      inbound_allow_cidr = ["0.0.0.0/0"]
    }
  }
}

output "frontend_endpoint" {
  value = cpln_workload.frontend.status[0].canonical_endpoint
}

Replace my-org with your org name; Terraform needs the full image path.

Apply the configuration:

terraform apply

Step 6: Open the application

Open the endpoint URL from the Terraform output:

terraform output

Pulumi

Step 5: Define the workload

Add to your existing Pulumi project from part 1:

TypeScript

// The quickstart frontend
const frontend = new cpln.Workload("frontend", {
  gvc: gvc.name,
  name: "frontend",
  type: "standard",
  containers: [
    {
      name: "frontend",
      image: "/org/my-org/image/frontend:1.0",
      cpu: "50m",
      memory: "128Mi",
      ports: [{ protocol: "http", number: 8080 }],
    },
  ],
  options: {
    capacityAi: true,
    timeoutSeconds: 5,
    autoscaling: {
      metric: "disabled",
      target: 95,
      minScale: 1,
      maxScale: 1,
    },
  },
  firewallSpec: {
    external: {
      inboundAllowCidrs: ["0.0.0.0/0"],
    },
  },
});

export const frontendEndpoint = frontend.statuses.apply(
  (s) => s?.[0]?.canonicalEndpoint ?? "pending"
);

Python

# The quickstart frontend
frontend = cpln.Workload("frontend",
    gvc=gvc.name,
    name="frontend",
    type="standard",
    containers=[cpln.WorkloadContainerArgs(
        name="frontend",
        image="/org/my-org/image/frontend:1.0",
        cpu="50m",
        memory="128Mi",
        ports=[cpln.WorkloadContainerPortArgs(
            protocol="http",
            number=8080,
        )],
    )],
    options=cpln.WorkloadOptionsArgs(
        capacity_ai=True,
        timeout_seconds=5,
        autoscaling=cpln.WorkloadOptionsAutoscalingArgs(
            metric="disabled",
            target=95,
            min_scale=1,
            max_scale=1,
        ),
    ),
    firewall_spec=cpln.WorkloadFirewallSpecArgs(
        external=cpln.WorkloadFirewallSpecExternalArgs(
            inbound_allow_cidrs=["0.0.0.0/0"],
        ),
    ))

pulumi.export("frontend_endpoint", frontend.statuses[0].canonical_endpoint)

Go

// The quickstart frontend
frontend, err := cpln.NewWorkload(ctx, "frontend", &cpln.WorkloadArgs{
	Gvc:  gvc.Name,
	Name: pulumi.String("frontend"),
	Type: pulumi.String("standard"),
	Containers: cpln.WorkloadContainerArray{
		&cpln.WorkloadContainerArgs{
			Name:   pulumi.String("frontend"),
			Image:  pulumi.String("/org/my-org/image/frontend:1.0"),
			Cpu:    pulumi.String("50m"),
			Memory: pulumi.String("128Mi"),
			Ports: cpln.WorkloadContainerPortArray{
				&cpln.WorkloadContainerPortArgs{
					Protocol: pulumi.String("http"),
					Number:   pulumi.Int(8080),
				},
			},
		},
	},
	Options: &cpln.WorkloadOptionsArgs{
		CapacityAi:     pulumi.Bool(true),
		TimeoutSeconds: pulumi.Int(5),
		Autoscaling: &cpln.WorkloadOptionsAutoscalingArgs{
			Metric:   pulumi.String("disabled"),
			Target:   pulumi.Int(95),
			MinScale: pulumi.Int(1),
			MaxScale: pulumi.Int(1),
		},
	},
	FirewallSpec: &cpln.WorkloadFirewallSpecArgs{
		External: &cpln.WorkloadFirewallSpecExternalArgs{
			InboundAllowCidrs: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
		},
	},
})
if err != nil {
	return err
}

ctx.Export("frontend_endpoint", frontend.Statuses.Index(pulumi.Int(0)).CanonicalEndpoint())

C#

// The quickstart frontend
var frontend = new Workload("frontend", new WorkloadArgs
{
    Gvc = gvc.Name,
    Name = "frontend",
    Type = "standard",
    Containers = new[]
    {
        new WorkloadContainerArgs
        {
            Name = "frontend",
            Image = "/org/my-org/image/frontend:1.0",
            Cpu = "50m",
            Memory = "128Mi",
            Ports = new[]
            {
                new WorkloadContainerPortArgs
                {
                    Protocol = "http",
                    Number = 8080
                }
            }
        }
    },
    Options = new WorkloadOptionsArgs
    {
        CapacityAi = true,
        TimeoutSeconds = 5,
        Autoscaling = new WorkloadOptionsAutoscalingArgs
        {
            Metric = "disabled",
            Target = 95,
            MinScale = 1,
            MaxScale = 1
        }
    },
    FirewallSpec = new WorkloadFirewallSpecArgs
    {
        External = new WorkloadFirewallSpecExternalArgs
        {
            InboundAllowCidrs = new[] { "0.0.0.0/0" }
        }
    }
});

Add to your return dictionary:

["frontend_endpoint"] = frontend.Statuses.Apply(s => s[0].CanonicalEndpoint)

Replace my-org with your org name; Pulumi needs the full image path.

Deploy the configuration:

pulumi up

Step 6: Open the application

Open the endpoint URL from the Pulumi output:

pulumi stack output

AI Agent

Step 5: Create the workload

The MCP server builds only from a git repository, so the build you ran in step 4 stays with the CLI. The agent takes over once the image is in your registry. The first prompt names your org and the GVC, so it works in a new conversation too. Replace my-org with your org name:

Using org "my-org" and GVC "quickstart-gvc", create a public
workload called "frontend" from the image //image/frontend:1.0
on port 8080, with one replica per location and the container
named "frontend". Keep everything else at its default.

The agent creates the workload, follows its deployments until both locations report ready, and reports the canonical endpoint.

Step 6: Open the application

Ask for the endpoint of each location. The prompt also returns the canonical endpoint, in case the agent stopped before reporting it:

Once it is ready in both locations, give me the endpoint of
each location and its canonical endpoint.

Open the canonical endpoint in your browser. The launch page opens.

Verify

Once frontend reports Ready, its canonical endpoint serves the launch page: the Launching soon label, the tagline On-call that gets out of your way., a waitlist form that is disabled with the note The waitlist opens once an API is connected. Set API_URL on this workload., three feature cards, and an empty Recent signups section. The footer names the location that served the request, the one nearest to you, for example:

Served from aws-us-west-2 by workload frontend, version 2

Open each location’s endpoint from the Deployments page, the cpln workload get-deployments frontend --gvc quickstart-gvc output, or the list your AI agent returned, and the footer switches to the other location.

Your own image is in the org’s private registry and running as a globally distributed workload.

Ship a change

Edit the product name or tagline in site.config.ts, then build a new tag:

With Docker

cpln image build --name frontend:1.1 --push

Without Docker

cpln image build --name frontend:1.1 --remote

Update the workload to the new image:

Console

Open frontend, click Containers in the left pane, select frontend:1.1 in the image dropdown, and click Update.

CLI

cpln workload update frontend --gvc quickstart-gvc --set spec.containers.frontend.image=//image/frontend:1.1

Terraform

Change the image tag to 1.1 in your Terraform configuration and run terraform apply.

Pulumi

Change the image tag to 1.1 in your Pulumi code and run pulumi up.

AI Agent

Update that workload to the image //image/frontend:1.1 and
tell me when the new version is serving in both locations.

The agent reads the workload, changes only the container image, and follows the rollout until both locations serve the new version.

The version already serving keeps answering until the new one reports ready in each location. Then the header and footer carry your product name, the hero shows your tagline, and the version in the footer has increased.

What you’ve learned

• Private registry: your images are stored within your org.
• Image references: the //image/ prefix for the CLI, the Console, and an AI agent, the full /org/<org>/image/ path for Terraform and Pulumi.
• No Dockerfile needed: cpln image build detects your application’s type and containerizes it, on your machine or on Control Plane.
• Rolling versions: an image update creates a new version that takes traffic in a location only once it reports ready there; the previous version serves until then.
• Environment variables: Control Plane injects CPLN_LOCATION, CPLN_WORKLOAD, CPLN_WORKLOAD_VERSION, and other CPLN_* variables automatically.

Next steps

3. Service-to-service communication

Build the API, keep it off the internet, and let the frontend reach it by name through the mesh.

Clean up

To remove everything the series has created so far:

Console

1. Delete the GVC

   Open quickstart-gvc, click Actions, then Delete, type the GVC name to confirm, and click Delete. web and frontend go with it.

2. Delete the images

   Open Images, select frontend, and click Actions, then Delete to remove all its tags.

CLI

cpln gvc delete quickstart-gvc
cpln image delete frontend:1.0
cpln image delete frontend:1.1

Terraform

terraform destroy

The images were built by the CLI, so delete them with it: cpln image delete frontend:1.0 and cpln image delete frontend:1.1.

Pulumi

pulumi destroy

The images were built by the CLI, so delete them with it: cpln image delete frontend:1.0 and cpln image delete frontend:1.1.

AI Agent

Delete the GVC "quickstart-gvc" and the images frontend:1.0
and frontend:1.1.

The agent tells you that the GVC takes web and frontend with it, asks you to confirm, then deletes the GVC and both images.

A --remote build also pushes a build cache image, frontend-cache:latest. Delete it with cpln image delete frontend-cache:latest if you built without Docker.