Choreon Documentation

Basics

Before diving into Choreon, you should know some of the core concepts.

Service

A service is a containerised application that you can deploy using Choreon. Choreon expects generic inputs and then takes care of deploying it and making it available for use, either public or private. Multiple services can communicate with each other simply by using their names. When you expose a service, e.g. an API service, Choreon optionally lets you secure it using basic auth.

You may have existing pipelines like Jenkins or GitHub Actions that build a container image and push it to a registry. Choreon can use that too. Alternatively, you can use the Choreon CLI in your pipeline to do a lot of that. While you are starting out or building MVPs and prototypes, it is also fine to host in a public registry and just provide image-related information to Choreon.

CPU, Memory and Storage Credits

In Choreon, CPU credits are a fraction of the CPU time you want your service to use. It is like a millicore in the Kubernetes world. If you consider 1 vCPU, then 100 credits is 0.1 vCPU, or roughly 100ms of CPU time if you consider 1 vCPU to be 1s of CPU time.

Memory and storage credits are in megabytes or gigabytes. If you have less than 1 GB of memory or storage available, the credit will be in MBs. If more than 1 GB, the credit will be a fractional GB, like 0.2 GB.

Deploying a service from the portal UI

Prerequisites

• For deployment from a repository: a GitHub or GitLab account, the one you used to log in.
• For deploying an image from a private registry: any private registry credentials, e.g. GitHub, GitLab, Docker Hub, etc.

Method 1 · Deploy a service image from a public registry

1. Navigate to Create Service.
2. Configure your service. Example inputs:

   Copy• Registry Host: docker.io
   • Image: nmatsui/hello-world-api
   • Port: 3000

3. Provide the healthcheck endpoint, then select appropriate CPU and memory credits for your service.
4. Click Deploy.

Expected result: the service deploys successfully with a public URL. You can uncheck the Expose Publicly checkbox to disable public exposure, in which case it will be privately available to other services you deploy, but not to anyone over the internet.

Method 2 · Deploy a service image from a private registry

1. Same as the public registry method, but now you must add your registry by clicking + Add private registry:

   Copy• Host: docker.io (or your registry URL)
   • Username: Your registry username
   • Password: Your registry password / auth token

2. Once added, select your configured registry from the dropdown in Registry Host.

Method 3 · Deploy from a repository

1. Toggle on Advanced Setup in Create Service.
2. Switch source kind from "From Container Registry" to "From Repository".
3. Select your repository, and then the branch the service image should be built from.
4. In build settings, provide your Dockerfile location in the source repository. By default Choreon expects it in the root, i.e. ./. Alternatively, Choreon can use Cloud Native Buildpacks, though support is experimental.
5. In deploy parameters, select resources as before and proceed.
6. In the miscellaneous step, provide any env variables and CORS settings. When you are happy, click Continue.

Expected result: the build process initiates automatically, the service deploys from the pipeline, and a public URL is generated which eventually serves a working response.

Troubleshooting

Port mismatch error: ensure the port matches your container image's listening port.

Authentication failure while fetching image: verify your registry credentials and ensure the registry was created using "Add private registry".

Build fails: check the Choreon-generated pipeline files, and contact us if you need support.

Image pull fails: verify the image name and version, and ensure you have proper access credentials.

Deploying a service using the CLI

Install

Install the CLI by running:

Copycurl -fsSL https://public.choreon.dev/artifacts/choreon-cli/install.sh | bash

After installation, verify the CLI is installed correctly:

Copychoreon version

Getting started

Copychoreon init

This command starts the login process with Choreon. It opens your default browser to complete the steps.

Managing services

Copychoreon service list

List all services in your account.

Copychoreon service create

Create a new service from either an image or a source code directory. Environment variables can be specified with the --envs flag or a .env file via --env-file. Deploy immediately after creation with the --deploy flag. Check the help with choreon -h to understand each option.

Examples

Deploy from a public image

Copychoreon service create \
 --name nginx-test \
 --image nginx:latest \
 --port 80 \
 --healthcheck / \
 --memory 128 \
 --cpu 50 \
 --public \
 --deploy

Deploy from a private registry

Copychoreon service create \
 --name my-app \
 --image registry.example.com/my-app:latest \
 --port 8080 \
 --healthcheck /health \
 --image-credentials '{"username": "user", "password": "pass"}' \
 --memory 512 \
 --cpu 100 \
 --public \
 --deploy

Deploy from a local source folder

Copychoreon service create \
 --name my-app \
 --src /path/to/source/dir \
 --port 8080 \
 --healthcheck / \
 --memory 128 \
 --cpu 100 \
 --public \
 --deploy

Inspect & remove

Copy# Get detailed information about a specific service
choreon service get --name [service-name]

# Delete a service from your account
choreon service delete --name [service-name]

Try choreon -h or choreon [command] [subcommand] -h to learn more about specific commands and options.