Skip to main content

Getting started

This guide shows you how to easily get started with K1.

Running K1 locally with Docker Compose​

In this section, you will be guided through how to get started with K1 in Docker.

By default K1 reads its configuration from the TOML file config.toml, but it is possible to provide another configuration file or to overwrite specific configuration options. For more information, see the Configuration section in the user manual.

In the following we show how to use the built in Standalone Key Provider. K1 also supports using an external Key Providers. See the integration guide for more details.

Step 1: Start a local Docker Compose instance​

Place the following Docker Compose file next to your config.toml.

services:
  k1:
    image: cybercryptio/k1
    container_name: k1
    environment:
      K1_STORAGE_USERNAME: "keyserver"
      K1_STORAGE_PASSWORD: "keyserver"
      K1_STORAGE_DATABASE: "keyserver"
      K1_STORAGE_HOST: "postgres"
    volumes:
      - ${PWD}/config.toml:/config.toml
    ports:
      - 50051:50051
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:alpine3.15
    container_name: postgres
    environment:
      POSTGRES_USER: "keyserver"
      POSTGRES_PASSWORD: "keyserver"
      POSTGRES_DB: "keyserver"
    ports:
      - 5432:5432
    healthcheck:
      test: pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}
      timeout: 30s
      interval: 5s
      retries: 5

To start the service call

docker compose up --detach

You now have a complete K1 instance inside Docker. The gRPC API is available on localhost:50051. When running the following command,

docker ps

the output will show that two containers, k1 and postgres, are running.

Step 2: Make a new Key Set​

The following command will create a new Key Set and return its ID:

docker exec k1 /k1 newKeySet

Note down the Key Set ID from the output. They should be used when generating a new Key Inititalization Key.

Step 3: Create a Key Inititalization Key​

Run the following command the create a new KIK:

docker exec k1 /k1 newKik --ksid <key set ID>

A KIK and a KIK ID will be returned. You will need to configure your D1 service with both of these for it to retrieve key material from K1.

Step 4: Shut down the K1 instance​

The K1 instance can be shut down by running:

docker compose down