Skip to content

Develop a Service with Docker

Choreo is a platform that allows you to create and deploy applications in any language. In this guide, you will use Choreo to create a service component that exposes a REST API in Go. You are not required to have any prior knowledge of the Go language to follow the guide. To develop a service component that exposes a service in Ballerina, you can follow the Develop a Ballerina Service guide.

A REST API is a web service that follows the REpresentational State Transfer (REST) principles of using HTTP methods to access and manipulate resources. In this guide, you create a containerized service component in Go, deploy it on Choreo, and later use it in a client application.

In this guide, you will:

  • Build a simple greeting service. The greeter service has a single resource named “greet” and accepts a single query parameter as input.
  • Deploy it in Choreo using a Dockerfile. It runs on port 9090.
  • Test the service.


  • To deploy a containerized component, you will need a GitHub account with a repository that contains a Dockerfile. Fork the Choreo examples repository, which contains the sample for this guide.

Learn the repository file structure

Let's familiarize ourselves with the key files in the sample greeter application. The below table gives a brief overview of the important files in the greeter service.


The following file paths are relative to the path /go/greeter

Filepath Description
main.go The Go-based Greeter service code.
Dockerfile Choreo uses the Dockerfile to build the container image of the application.
.choreo/endpoints.yaml Choreo-specific configuration that provides information about how Choreo exposes the service.
openapi.yaml OpenAPI contract of the greeter service. This is needed to publish our service as a managed API. This openapi.yaml file is referenced by the .choreo/endpoints.yaml.

Let's get started!

Configure the service port with endpoints

We expect to run our greeter service on port 9090. To securely expose the service through Choreo, we must provide the port and other required information to Choreo. In Choreo, we expose our services with endpoints. You can read more about endpoints in our endpoint documentation.

Choreo looks for an endpoints.yaml file inside the .choreo directory to configure the endpoint details of a containerized component. Place the .choreo directory at the root of the Docker build context path.

In our greeter sample, the endpoints.yaml file is at go/greeter/.choreo/endpoints.yaml.

Step 1: Create a service component from a Dockerfile

Let's create a containerized service component by following these steps:

  1. Go to and sign in. This opens the project home page.
  2. Create a project to add the service component. You can follow the instructions under Prerequisites in the Connect Your Own GitHub Repository to Choreo guide.
  3. On the Components page, click on the Service card.
  4. Enter a unique name and a description of the service. For this guide, let's enter the following values:

    Field Value
    Name Greetings
    Description Sends greetings
  5. Go to the GitHub tab.

  6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the Choreo GitHub App.

    Alternatively, you can paste the Choreo samples repository URL in the Provide Repository URL field to connect to it without requiring authorization from the Choreo Apps GitHub application. However, authorizing the repository with the Choreo GitHub App is necessary if you want to enable Auto Deploy for the component.


    The Choreo GitHub App requires the following permissions:

    • Read and write access to code and pull requests.
    • Read access to issues and metadata.

    You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.

  7. Enter the following information:

    Field Description
    GitHub Account Your account
    GitHub Repository choreo-sample-apps
    Branch main
    Buildpack Docker
    Docker Context path go/greeter
    Dockerfile Path go/greeter/Dockerfile


    1. To successfully build your container with Choreo, it is essential to explicitly define a User ID (UID) under the USER instruction in your Dockerfile. For reference, see sample Dockerfile. To ensure that the defined USER instruction is valid, it must conform to the following conditions:

      • A valid User ID is a numeric value between 10000-20000, such as 10001 or 10500.
      • Usernames are considered invalid and should not be used. For example, my-custom-user-12221 or my-custom-user are invalid User IDs.
    2. The Dockerfile utilized in this guide is a Multi-stage Dockerfile, which is designed to keep the final image size small and provides the ability to build the application with a specific version of tools and libraries.

  8. Click Create. Once the component creation is complete, you will see the component overview page.

You have successfully created a Service component from a Dockerfile. Now let's build and deploy the service.

Step 2: Build and deploy

Now that we have connected the source repository, and configured the endpoint details, it's time to build the service and create an image. Then we can deploy that image test the greeter service.

Step 2.1: Build

To build the service, follow these steps:

  1. In the left navigation menu, click Build.
  2. Select the latest commit and click Build.
  3. Check the deployment progress by observing the console logs on the right of the page.


    Building the service component may take a while. You can track the progress by observing the logs. Once the build process is complete, the build status changes to Success.

You can access the following scans under Build.

  • The Dockerfile scan: Choreo performs a scan to check if a non-root user ID is assigned to the Docker container to ensure security. If no non-root user is specified, the build will fail.
  • Container (Trivy) vulnerability scan: This detects vulnerabilities in the final docker image.
  • Container (Trivy) vulnerability scan: The details of the vulnerabilities open in a separate pane. If this scan detects critical vulnerabilities, the build will fail.


If you have Choreo environments on a private data plane, you can ignore these vulnerabilities and proceed with the deployment.

Step 2.2: Deploy

Next, to deploy this service, follow these steps:

  1. In the left navigation menu, click Deploy.
  2. On the Set Up card, click Configure & Deploy.
  3. Skip configuring the Environment Configurations and click Next.
  4. Skip adding a File Mount. Click Deploy.
  5. Review the Endpoint Details and click Deploy.


    Deploying the service component may take a while. You can track the progress by observing the logs. Once the deploying is complete, the build status changes to Active on the Development environment card.

Once you have successfully deployed your service, you can test, manage, and observe it like any other component type in Choreo.

To perform a more detailed diagnosis of this Dockerfile-based REST API by viewing Kubernetes-level insights, see Choreo's DevOps capabilities.