> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kosli.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.kosli.com/feedback
```json
{
"path": "/tutorials/try_kosli_locally",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# 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](/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](https://app.kosli.com). 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](/getting_started/install).
* [Get a Kosli API token](/getting_started/service-accounts).
## Steps
Set the `KOSLI_ORG` and `KOSLI_API_TOKEN` environment variables:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
export KOSLI_ORG=
export KOSLI_API_TOKEN=
```
Check your Kosli setup:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
git clone https://github.com/kosli-dev/quickstart-docker-example.git
cd quickstart-docker-example
export GIT_COMMIT=$(git rev-parse HEAD)
```
The repository includes a `kosli.yml` template file. Inspect it:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
cat kosli.yml
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
trail:
artifacts:
- name: nginx
```
Create a Flow called `quickstart-nginx` using this template:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli create flow quickstart-nginx \
--description "Flow for quickstart nginx image" \
--template-file kosli.yml
```
Confirm it was created:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli list flows
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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.
Create a Trail in the `quickstart-nginx` Flow, named after the current git commit:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli begin trail ${GIT_COMMIT} \
--flow quickstart-nginx
```
The repository's `docker-compose.yml` uses a public [nginx](https://nginx.org/) image as the artifact for this tutorial.
Attest it to Kosli:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli list artifacts --flow quickstart-nginx
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
COMMIT ARTIFACT STATE CREATED_AT
9f14efa Name: nginx:1.21 COMPLIANT Tue, 01 Nov 2022 15:46:59 CET
Fingerprint: 2bcabc23b45489fb0885d69a06ba1d648aeda973fae7bb981bafbb884165e514
```
Create an environment called `quickstart` of type `docker`:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli create environment quickstart \
--type docker \
--description "quickstart environment for tutorial"
```
Verify it was created:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli list environments
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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.
Run the artifact:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
docker compose up -d
```
Confirm the container is running:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
docker ps
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli snapshot docker quickstart
```
Confirm the snapshot was created:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli list snapshots quickstart
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
SNAPSHOT FROM TO DURATION
1 Tue, 01 Nov 2022 15:55:49 CET now 11 seconds
```
Get a detailed view of the snapshot:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli get snapshot quickstart
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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.
Use `kosli search` to find everything Kosli knows about an artifact or git commit:
```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli search ${GIT_COMMIT}
```
```plaintext theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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](/tutorials/querying_kosli) guide to learn more about the search command.