Kurrent Cloud

Spin up a managed instance of KurrentDB and start building in minutes. Available in AWS, Azure and GCP.

Sign up for freeDocumentation

Quick start

KurrentDB can run as a single node or as a highly-available cluster. For the cluster deployment, you'd need three server nodes.

The installation procedure consists of the following steps:

• Create a configuration file for each cluster node. If you are using any licensed features, ensure that you configure alicense key.
• Install KurrentDB on each node using one of the available methods.
• Obtain SSL certificates, either signed by a publicly trusted or private certificate authority.
• Copy the configuration files and SSL certificates to each node.
• Start the KurrentDB service on each node.
• Check the cluster status using the Admin UI on any node.

Default access

License Keys

Some features of KurrentDB require a license key to access. When you purchase an enterprise subscription, the license key will be sent to your company's designated license administrator. Existing customers who would like to upgrade to a 24.10+ enterprise license should contact their Kurrent (formerly Event Store) account manager or contact ushere. As an existing customer, you can also try the enterprise features by signing up for afree trial license key.

There are various ways to provide the license key to KurrentDB. For more information, refer to theconfiguration guide.

Configuration file:

Licensing:  LicenseKey:Yourkey

Environment variable:

KURRENTDB_LICENSING__LICENSE_KEY

For most features that require a license, KurrentDB will not start if the feature is enabled but the license key is not provided or is invalid.

Package repositories

Packages for KurrentDB are hosted onCloudsmith, in the following repositories:

• kurrent-latest containing production-ready LTS andSTS packages.
• kurrent-preview containing non-production preview packages.

Linux

KurrentDB has pre-built packages available on Cloudsmith for RedHat or Debian-based distributions. The name of the KurrentDB package iskurrentdb.

Ubuntu/Debian packages

Debian packages can be found in the following repositories:

• kurrent-latest containing production-ready LTS andSTS packages.
• kurrent-preview containing non-production preview packages.

Distribution setup

To install packages, you can quickly set up the repository automatically (recommended):

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-latest/setup.deb.sh' \  |sudo -E bash

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-preview/setup.deb.sh' \  |sudo -E bash

If you need to force a specific distribution, release/version, architecture, or component (if supported), you can also do that (e.g. if your system is compatible but not identical):

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-latest/setup.deb.sh' \  |sudo -E distro=DISTRO codename=CODENAME arch=ARCH component=COMPONENT bash

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-preview/setup.deb.sh' \  |sudo -E distro=DISTRO codename=CODENAME arch=ARCH component=COMPONENT bash

Alternatively, you can find instructions to manually configure it yourself on Cloudsmith:

• kurrent-latest
• kurrent-preview

Install with apt-get

Install the package:

apt-get install kurrentdb=25.0.1

Uninstall with apt-get

You can uninstall the package with:

apt-get remove kurrentdb

If you want to also remove any configuration files and user settings, use:

apt-get purge kurrentdb

RedHat packages

RedHat packages can be found in the following repositories:

• kurrent-latest containing production-ready LTS andSTS packages.
• kurrent-preview containing non-production preview packages.

Distribution setup

To install packages, you can quickly set up the repository automatically (recommended):

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-latest/setup.rpm.sh' \  |sudo -E bash

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-preview/setup.rpm.sh' \  |sudo -E bash

If you need to force a specific distribution, release/version, or architecture, you can also do that (e.g. if your system is compatible but not identical):

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-latest/setup.rpm.sh' \  |sudo -E distro=DISTRO codename=CODENAME arch=ARCH bash

curl -1sLf \  'https://packages.kurrent.io/public/kurrent-preview/setup.rpm.sh' \  |sudo -E distro=DISTRO codename=CODENAME arch=ARCH bash

Alternatively, you can find instructions to manually configure it yourself on Cloudsmith:

• kurrent-latest.
• kurrent-preview.

Install with yum

Install the package:

yum install kurrentdb-25.0.1-1.x86_64

Uninstall with yum

You can uninstall the package with:

yum remove kurrentdb

Running the kurrentdb service

Once installed, the server is registered as a service. Therefore, you can start KurrentDB with:

systemctl start kurrentdb

When you install the KurrentDB package, the service doesn't start by default. This allows you to change the configuration located at/etc/kurrentdb/kurrentdb.conf and to prevent creating database and index files in the default location.

Windows

NuGet

KurrentDB has NuGet packages available onChocolatey.

Install with Chocolatey

You can install KurrentDB through Chocolatey:

choco install kurrentdb--version=25.0.1

KurrentDB can then be run withKurrentDB.exe:

KurrentDB.exe --config {your config file}

Uninstall with Chocolatey

You can uninstall KurrentDB through Chocolatey with:

choco uninstall kurrentdb

Running as a service

KurrentDB 25.0.2+ can be run as a windows service. The following commands are for example. Consult thesc.exe documentation for details.

Create the service:

sc.exe create"KurrentDB" `  start= delayed-auto     `  binpath= "C:\ProgramData\chocolatey\lib\kurrentdb\kurrentdb-25.0.2-windows.x64\KurrentDB.exe --config=c:\path\to\kurrentdb-config.yaml"

Configure the restart policy:

sc.exe failure"KurrentDB" `  reset= 0                 `  actions= restart/5000/restart/5000/restart/5000

Start the service:

sc.exe start"KurrentDB"

Logs will still be written to the usual log file location. By default on windows this is thelogs directory within the directory that containsKurrentDB.exe.

Docker

You can run KurrentDB in a Docker container as a single node, using insecure mode. It is useful in most cases to try out the product and for local development purposes.

It's also possible to run a three-node cluster with or without SSL using Docker Compose. Such a setup is closer to what you'd run in production.

KurrentDB Docker images are hosted in the following registries:

• kurrent-latest containing production-ready LTS andSTS containers.
• kurrent-preview containing non-production preview containers.

Run with Docker

Pull the container with:

docker pull docker.kurrent.io/kurrent-latest/kurrentdb:latest

The following command will start the KurrentDB node using the default HTTP port, without security. You can then connect to it using one of the clients and thekurrentdb://localhost:2113?tls=false connection string. You can also access the Admin UI by opening http://localhost:2113 in your browser.

docker run --name kurrentdb-node -it -p 2113:2113 \    docker.kurrent.io/kurrent-latest/kurrentdb:latest --insecure --run-projections=All \    --enable-atom-pub-over-http

Then, you'd be able to connect to KurrentDB with gRPC clients. Also, the Stream Browser will work in the Admin UI.

In order to sustainably keep the data, we also recommend mapping the database and index volumes.

Use Docker Compose

You can also run a single-node instance or a three-node secure cluster locally using Docker Compose.

Insecure single node

You can use Docker Compose to run KurrentDB in the same setup as thedocker run command mentioned before.

Create a filedocker-compose.yaml with the following content:

services:  kurrentdb.db:    image:docker.kurrent.io/kurrent-latest/kurrentdb:latest    environment:      -KURRENTDB_CLUSTER_SIZE=1      -KURRENTDB_RUN_PROJECTIONS=All      -KURRENTDB_START_STANDARD_PROJECTIONS=true      -KURRENTDB_NODE_PORT=2113      -KURRENTDB_INSECURE=true      -KURRENTDB_ENABLE_ATOM_PUB_OVER_HTTP=true    ports:      -"2113:2113"    volumes:      -type:volume        source:kurrentdb-volume-data        target:/var/lib/kurrentdb      -type:volume        source:kurrentdb-volume-logs        target:/var/log/kurrentdbvolumes:  kurrentdb-volume-data:  kurrentdb-volume-logs:

Run the instance:

docker compose up

The command above would run KurrentDB as a single node without SSL. You also get AtomPub protocol enabled, so you can get the stream browser to work in the Admin UI.

Secure cluster

With Docker Compose, you can also run a three-node cluster with security enabled. This kind of setup is something you'd expect to use in production.

Create filedocker-compose.yaml with following content:

services:  volumes-provisioner:    image:hasnat/volumes-provisioner    environment:      PROVISION_DIRECTORIES:"1000:1000:0755:/tmp/certs"    volumes:      -certs:/tmp/certs    network_mode:none  setup:    image:eventstore/es-gencert-cli:1.0.2    entrypoint:bash    user:"1000:1000"    command:>      -c "mkdir -p ./certs && cd /certs      && es-gencert-cli create-ca      && es-gencert-cli create-node -out ./node1 -ip-addresses 127.0.0.1,172.30.240.11 -dns-names localhost      && es-gencert-cli create-node -out ./node2 -ip-addresses 127.0.0.1,172.30.240.12 -dns-names localhost      && es-gencert-cli create-node -out ./node3 -ip-addresses 127.0.0.1,172.30.240.13 -dns-names localhost      && find . -type f -print0 | xargs -0 chmod 666"    container_name:setup    volumes:      -certs:/certs    depends_on:      -volumes-provisioner  node1.kurrentdb:&template    image:docker.kurrent.io/kurrent-latest/kurrentdb:latest    container_name:node1.kurrentdb    env_file:      -vars.env    environment:      -KURRENTDB_REPLICATION_IP=172.30.240.11      -KURRENTDB_ADVERTISE_NODE_PORT_TO_CLIENT_AS=2111      -KURRENTDB_GOSSIP_SEED=172.30.240.12:2113,172.30.240.13:2113      -KURRENTDB_TRUSTED_ROOT_CERTIFICATES_PATH=/certs/ca      -KURRENTDB_CERTIFICATE_FILE=/certs/node1/node.crt      -KURRENTDB_CERTIFICATE_PRIVATE_KEY_FILE=/certs/node1/node.key    healthcheck:      test:        [          "CMD-SHELL",          "curl --fail --insecure https://node1.kurrentdb:2113/health/live || exit 1",        ]      interval:5s      timeout:5s      retries:24    ports:      -2111:2113    volumes:      -certs:/certs    depends_on:      -setup    restart:always    networks:      clusternetwork:        ipv4_address:172.30.240.11  node2.kurrentdb:    <<:*template    container_name:node2.kurrentdb    env_file:      -vars.env    environment:      -KURRENTDB_REPLICATION_IP=172.30.240.12      -KURRENTDB_ADVERTISE_NODE_PORT_TO_CLIENT_AS=2112      -KURRENTDB_GOSSIP_SEED=172.30.240.11:2113,172.30.240.13:2113      -KURRENTDB_TRUSTED_ROOT_CERTIFICATES_PATH=/certs/ca      -KURRENTDB_CERTIFICATE_FILE=/certs/node2/node.crt      -KURRENTDB_CERTIFICATE_PRIVATE_KEY_FILE=/certs/node2/node.key    healthcheck:      test:        [          "CMD-SHELL",          "curl --fail --insecure https://node2.kurrentdb:2113/health/live || exit 1",        ]      interval:5s      timeout:5s      retries:24    ports:      -2112:2113    networks:      clusternetwork:        ipv4_address:172.30.240.12  node3.kurrentdb:    <<:*template    container_name:node3.kurrentdb    environment:      -KURRENTDB_REPLICATION_IP=172.30.240.13      -KURRENTDB_ADVERTISE_NODE_PORT_TO_CLIENT_AS=2113      -KURRENTDB_GOSSIP_SEED=172.30.240.11:2113,172.30.240.12:2113      -KURRENTDB_TRUSTED_ROOT_CERTIFICATES_PATH=/certs/ca      -KURRENTDB_CERTIFICATE_FILE=/certs/node3/node.crt      -KURRENTDB_CERTIFICATE_PRIVATE_KEY_FILE=/certs/node3/node.key    healthcheck:      test:        [          "CMD-SHELL",          "curl --fail --insecure https://node3.kurrentdb:2113/health/live || exit 1",        ]      interval:5s      timeout:5s      retries:24    ports:      -2113:2113    networks:      clusternetwork:        ipv4_address:172.30.240.13networks:  clusternetwork:    name:kurrentdb.local    driver:bridge    ipam:      driver:default      config:        -subnet:172.30.240.0/24volumes:  certs:

Quite a few settings are shared between the nodes and we use theenv file to avoid repeating those settings. So, add thevars.env file to the same location:

KURRENTDB_CLUSTER_SIZE=3KURRENTDB_RUN_PROJECTIONS=AllKURRENTDB_DISCOVER_VIA_DNS=falseKURRENTDB_ENABLE_ATOM_PUB_OVER_HTTP=trueKURRENTDB_ADVERTISE_HOST_TO_CLIENT_AS=127.0.0.1

Containers will use the shared volume using the local./certs directory for certificates. However, if you let Docker create the directory on startup, the container won't be able to get write access to it. Therefore, you should create thecerts directory manually. You only need to do it once.

mkdir certs

Now you are ready to start the cluster.

docker compose up

Watching the log messages, you will see that after some time, the elections process completes. Then you're able to connect to each node using the Admin UI. Nodes should be accessible on the loopback address (127.0.0.1 orlocalhost) over HTTP, using ports specified below:

You have to tell your client to use secure connection.

As you might've noticed, the connection string has a setting to disable the certificate validation (tlsVerifyCert=false). It would prevent the invalid certificate error since the cluster uses a private, auto-generated CA.

However,we do not recommend using this setting in production. Instead, you can either add the CA certificate to the trusted root CA store or instruct your application to use such a certificate. See thesecurity section for detailed instructions.

Kubernetes

KurrentDB can be deployed and managed using theOperator.

Building from source

You can also buildKurrentDB from source. Before doing that, you need to install the .NET 8 SDK. KurrentDB packages have the .NET Runtime embedded, so you don't need to install anything except the KurrentDB package.

Compatibility notes

Depending on how your KurrentDB instance is configured, some features might not work. Below are some features that are unavailable due to the specified options.