For development, Chainloop components (Control Plane, Artifact CAS and CLI) come pre-configured to talk to a set of auxiliary services (Dex, PostgresSQL and Vault) that can be run using Docker Compose, so you can start contributing in no time! :)

To get up and running you'll need

• Golang 1.20+ toolchain
• Docker Compose
• make

This will download and install the CLI tools required to work with our code.

make init

Chainloop requires some configuration to be in place such as

• PostgreSQL 14 connection from the Control plane
• Access to a secrets manager. Currently Hashicorp Vault, AWS Secrets Manager, GCP Secret Manager and Azure KeyVault are supported.
• Open ID connect (OIDC) single sign-on credentials.

Luckily, you can leverage the provided docker compose file that can be found in the devel directory to do all the setup for you.

cd devel
docker compose up

Once you have the pre-required services up and running, you should be able to run the different Chainloop server-side components, in our case we have:

• The Control Plane app/controlplane
• The Artifact Content Addressable Storage (CAS) Proxy app/artifact-cas

These components are built using Go, have a Makefile and a make run target for convenience.

• run controlplane make -C app/controlplane run
• run CAS make -C app/cas run

The Command line interface (CLI) is used for both a) operate on the control plane and b) run the attestation process on your CI/CD.

You can run it by executing go run app/cli/main.go

4.1 - Configure the CLI to point to the local control plane and CAS services.

go run app/cli/main.go config save --insecure --control-plane localhost:9000 --artifact-cas localhost:9001

4.2 - Logging in the control-plane

You should now be ready to authenticate the CLI

NOTE: In development a --insecure flag must be provided to talk to the local APIs

go run app/cli/main.go --insecure auth login

You will get redirected to the pre-configured local OIDC provider (DEX) where there are two configured users

• sarah@chainloop.local/password
• john@chainloop.local/password

Once logged in, please refer to our Getting Started guide to learn how to setup an OCI registry.

Refer to the Extensions documentation for more information.

You might be getting the following error on OSX with Docker Desktop:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

$ cd chainloop
$ make test
[...]
   --- FAIL: TestVaultIntegration/TestReadWriteCredentials (0.00s)
        keyval_test.go:182:
                Error Trace:    projects/chainloop/chainloop/internal/credentials/vault/keyval_test.go:182
                                                        projects/chainloop/chainloop/internal/credentials/vault/keyval_test.go:207
                                                        go/pkg/mod/github.com/stretchr/testify@v1.8.2/suite/suite.go:187
                Error:          Received unexpected error:
                                Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?: failed to create container
                Test:           TestVaultIntegration/TestReadWriteCredentials
        suite.go:87: test panicked: runtime error: invalid memory address or nil pointer dereference
[...]

We use testcontainers for integration tests. You can check all requirements on this page.

This is a known issue listed there:

"Docker Desktop Starting 4.13, run sudo ln -s $HOME/.docker/run/docker.sock /var/run/docker.sock"

Running the following command fixes the issue:

sudo ln -s $HOME/.docker/run/docker.sock /var/run/docker.sock

For quick testing you can use the provided compose.labs.yml file to run the Chainloop components and the auxiliary services.

• Docker and Docker Compose
• Add entry in /etc/hosts for the hostname dex pointing to 127.0.0.1

Run the labs environment

docker compose -f compose.labs.yml up

Download Chainloop CLI

curl -sfL https://docs.chainloop.dev/install.sh | bash -s

Configure the CLI to point to the local control plane and CAS services.

chainloop config save --insecure --control-plane localhost:9000 --artifact-cas localhost:9001

A new user and token has been created for you during bootstrap. An authentication token is available in the service logs (note that this is deactivated in production mode). Look for DEVELOPMENT USER TOKEN message in the container logs:

> docker compose -f compose.labs.yaml logs control-plane | grep -A 1  "DEVELOPMENT USER TOKEN"
control-plane-1  | {"level":"info","ts":1724772518.38039,"component":"service","msg":"******************* DEVELOPMENT USER TOKEN *******************"}
control-plane-1  | {"level":"info","ts":1724772518.3804584,"component":"service","msg":"Use chainloop 'auth login --skip-browser' and paste this token to start a headless session: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiNzc4ZmExMzAtNjUzOS00ZTVmLThlYmYtMGQyZTkxYjRlNmM5IiwiaXNzIjoiY3AuY2hhaW5sb29wIiwiYXVkIjpbInVzZXItYXV0aC5jaGFpbmxvb3AiXSwiZXhwIjoxNzI3MzY0NTE4fQ.nyQtlR3bpc0VIna_UIKlXcx62gwG1dbuhkVm22fEXv4"}

To authenticate, run this command and paste the token from the logs.

> chainloop --insecure auth login --skip-browser
WRN API contacted in insecure mode
WRN Both user credentials and $CHAINLOOP_TOKEN set. Ignoring $CHAINLOOP_TOKEN.
To authenticate, click on the following link and paste the result back here

  http://0.0.0.0:8000/auth/login?long-lived=true

Enter Token:
INF login successful!

you are now ready to use the CLI and follow the quickstart guide