Try Kosli locally

A quick local demo of Kosli’s core features using Docker — no GitHub account or CI pipeline required. Runs entirely from your terminal in about 10 minutes.

This tutorial runs entirely on your local machine using Docker — no GitHub account or CI pipeline required. If you’d prefer a full hands-on introduction using a real CI/CD pipeline, see the Kosli Learning Labs instead.

In this tutorial, you’ll learn how Kosli allows you to track a source code change from runtime environments. You’ll set up a docker environment, use Kosli to record build and deployment events, and track what artifacts are running in your runtime environment.

As you go through the steps you can also check your progress in your browser. In the upper left corner, select the organization you want to view — your personal organization has the same name as your GitHub login.

Prerequisites

• Install Docker.
• Install Kosli CLI.
• Get a Kosli API token.

Steps

1. Set up

   Set the KOSLI_ORG and KOSLI_API_TOKEN environment variables:

   export KOSLI_ORG=<your-org>
   export KOSLI_API_TOKEN=<your-api-token>
   

   Check your Kosli setup:

   kosli list flows
   

   This should return a list of flows or “No flows were found”.

   Clone the quickstart repository and export the current commit SHA:

   git clone https://github.com/kosli-dev/quickstart-docker-example.git
   cd quickstart-docker-example
   export GIT_COMMIT=$(git rev-parse HEAD)
   
2. Create a Kosli Flow

   The repository includes a kosli.yml template file. Inspect it:

   cat kosli.yml
   

   trail:
     artifacts:
       - name: nginx
   

   Create a Flow called quickstart-nginx using this template:

   kosli create flow quickstart-nginx \
       --description "Flow for quickstart nginx image" \
       --template-file kosli.yml
   

   Confirm it was created:

   kosli list flows
   

   NAME              DESCRIPTION                          VISIBILITY
   quickstart-nginx  Flow for quickstart nginx image      private
   

   In the web interface, select Flows in the left sidebar. You should see quickstart-nginx listed. No artifacts have been reported yet.

3. Create a Kosli Trail

   Create a Trail in the quickstart-nginx Flow, named after the current git commit:

   kosli begin trail ${GIT_COMMIT} \
       --flow quickstart-nginx
   
4. Attest an artifact

   The repository’s docker-compose.yml uses a public nginx image as the artifact for this tutorial.

   Attest it to Kosli:

   kosli attest artifact nginx:1.21 \
       --name nginx \
       --flow quickstart-nginx \
       --trail ${GIT_COMMIT} \
       --artifact-type oci \
       --build-url https://example.com \
       --commit-url https://github.com/kosli-dev/quickstart-docker-example/commit/9f14efa0c91807da9a8b1d1d6332c5b3aa24a310 \
       --commit $(git rev-parse HEAD)
   

   Verify the artifact was recorded:

   kosli list artifacts --flow quickstart-nginx
   

   COMMIT   ARTIFACT                                                                       STATE      CREATED_AT
   9f14efa  Name: nginx:1.21                                                               COMPLIANT  Tue, 01 Nov 2022 15:46:59 CET
            Fingerprint: 2bcabc23b45489fb0885d69a06ba1d648aeda973fae7bb981bafbb884165e514
   
5. Create a Kosli environment

   Create an environment called quickstart of type docker:

   kosli create environment quickstart \
       --type docker \
       --description "quickstart environment for tutorial"
   

   Verify it was created:

   kosli list environments
   

   NAME        TYPE    LAST REPORT  LAST MODIFIED
   quickstart  docker               2022-11-01T15:30:56+01:00
   

   In the web interface, select Environments. You should see quickstart listed with no snapshots yet.

6. Report what is running

   Run the artifact:

   docker compose up -d
   

   Confirm the container is running:

   docker ps
   

   CONTAINER ID  IMAGE      COMMAND                  CREATED         STATUS         PORTS                  NAMES
   6330e545b532  nginx:1.21 "/docker-entrypoint.…"  35 seconds ago  Up 34 seconds  0.0.0.0:8080->80/tcp   quickstart-nginx
   

   Snapshot the environment to report all running containers to Kosli:

   kosli snapshot docker quickstart
   

   Confirm the snapshot was created:

   kosli list snapshots quickstart
   

   SNAPSHOT  FROM                           TO   DURATION
   1         Tue, 01 Nov 2022 15:55:49 CET  now  11 seconds
   

   Get a detailed view of the snapshot:

   kosli get snapshot quickstart
   

   COMMIT  ARTIFACT                                                                       FLOW  RUNNING_SINCE  REPLICAS
   N/A     Name: nginx:1.21                                                               N/A   3 minutes ago  1
           Fingerprint: 8f05d73835934b8220e1abd2f157ea4e2260b9c26f6f63a8e3975e7affa46724
   

   In the web interface, the Environments page will now show a timestamp in the Last Change At column. Select quickstart to see the full snapshot.

7. Search Kosli

   Use kosli search to find everything Kosli knows about an artifact or git commit:

   kosli search ${GIT_COMMIT}
   

   Search result resolved to commit 9f14efa0c91807da9a8b1d1d6332c5b3aa24a310
   Name:              nginx:1.21
   Fingerprint:       2bcabc23b45489fb0885d69a06ba1d648aeda973fae7bb981bafbb884165e514
   Has provenance:    true
   Flow:              quickstart-nginx
   Git commit:        9f14efa0c91807da9a8b1d1d6332c5b3aa24a310
   Commit URL:        https://github.com/kosli-dev/quickstart-docker-example/commit/9f14efa0c91807da9a8b1d1d6332c5b3aa24a310
   Build URL:         https://example.com
   Compliance state:  COMPLIANT
   History:
       Artifact created                             Tue, 01 Nov 2022 15:46:59 CET
       Deployment #1 to quickstart environment      Tue, 01 Nov 2022 15:48:47 CET
       Started running in quickstart#1 environment  Tue, 01 Nov 2022 15:55:49 CET
   

   Visit the Kosli Querying guide to learn more about the search command.