Quick start

EventStoreDB 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.
• Install EventStoreDB 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 EventStoreDB service on each node.
• Check the cluster status using the Admin UI on any node.

Default access

User	Password
admin	changeit
ops	changeit

Linux

Install from PackageCloud

EventStoreDB has pre-built packages available for Debian-based distributions, or you can build from source. The package name to install is eventstore-oss.

Commercial version with additional features is available as a separate package eventstore-commercial.

Before installing the package from Packagecloud, add the repository to your system:

curl -s https://packagecloud.io/install/repositories/EventStore/EventStore-OSS/script.deb.sh | sudo bash

For the commercial version:

curl -s https://<key>@packagecloud.io/install/repositories/EventStore/EventStore-Commercial/script.deb.sh | sudo bash

Then, install the package:

sudo apt install eventstore-oss

For the commercial version:

sudo apt install eventstore-commercial

TIP

RPM packages are not available as part of the EventStore/EventStore-OSS Packagecloud repository

If you installed from a pre-built package, the server is registered as a service. Therefore, you can start EventStoreDB with:

sudo systemctl start eventstore

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

WARNING

We recommend that when using Linux you set the 'open file limit' to a high number. The precise value depends on your use case, but at least between 30,000 and 60,000.

Building from source

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

Uninstall

If you installed one of the pre-built packages for Debian based systems, you can remove it with:

sudo apt-get purge eventstore-oss

or

sudo apt-get purge eventstore-commercial

This removes EventStoreDB completely, including any user settings.

If you built EventStoreDB from source, remove it by deleting the directory containing the source and build and manually removing any environment variables.

Windows

WARNING

EventStoreDB doesn't install as a Windows service. You need to ensure that the server executable starts automatically.

Install from Chocolatey

EventStoreDB has Chocolatey packages available that you can install with the following command with administrator permissions.

choco install eventstore-oss

Download the binaries

You can also download a binary, unzip the archive and run from the folder location with administrator permissions.

The following command starts EventStoreDB in dev mode with the database stored at the path ./db and the logs in ./logs. Read more about configuring the EventStoreDB server in the Configuration section.

EventStore.ClusterNode.exe --dev --db ./db --log ./logs

EventStoreDB runs in an administration context because it starts an HTTP server through http.sys. For permanent or production instances, you need to provide an ACL such as:

netsh http add urlacl url=http://+:2113/ user=DOMAIN\username

For more information, refer to Microsoft's add urlacl documentation.

To build EventStoreDB from source, refer to the EventStoreDB GitHub repository.

Uninstall

If you installed EventStoreDB with Chocolatey, you can uninstall with:

choco uninstall eventstore-oss

This removes the eventstore-oss Chocolatey package.

If you installed EventStoreDB by downloading a binary, you can remove it by:

• Deleting the EventStore-OSS-Win-* directory.
• Removing the directory from your PATH.

Docker

You can run EventStoreDB 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.

Run with Docker

EventStoreDB has a Docker image available for any platform that supports Docker.

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

docker run --name esdb-node -it -p 2113:2113 \
    eventstore/eventstore:latest --insecure --run-projections=All
    --enable-atom-pub-over-http

Then, you'd be able to connect to EventStoreDB 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 EventStoreDB in the same setup as the docker run command mentioned before.

Create file docker-compose.yaml with following content:

version: "3.4"

services:
  eventstore.db:
    image: eventstore/eventstore:24.2.0-jammy
    environment:
      - EVENTSTORE_CLUSTER_SIZE=1
      - EVENTSTORE_RUN_PROJECTIONS=All
      - EVENTSTORE_START_STANDARD_PROJECTIONS=true
      - EVENTSTORE_HTTP_PORT=2113
      - EVENTSTORE_INSECURE=true
      - EVENTSTORE_ENABLE_ATOM_PUB_OVER_HTTP=true
    ports:
      - "2113:2113"
    volumes:
      - type: volume
        source: eventstore-volume-data
        target: /var/lib/eventstore
      - type: volume
        source: eventstore-volume-logs
        target: /var/log/eventstore

volumes:
  eventstore-volume-data:
  eventstore-volume-logs:

Run the instance:

docker-compose up

The command above would run EventStoreDB 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.

WARNING

The legacy TCP client protocol is disabled by default and will no longer be available from 24.2. To enable it in versions lower than 24.2, add the environment variable to the yaml file: EVENTSTORE_ENABLE_EXTERNAL_TCP=true

Secure cluster

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

Create file docker-compose.yaml with following content:

version: "3.5"

services:
  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

  node1.eventstore: &template
    image: eventstore/eventstore:24.2.0-jammy
    container_name: node1.eventstore
    env_file:
      - vars.env
    environment:
      - EVENTSTORE_INT_IP=172.30.240.11
      - EVENTSTORE_ADVERTISE_HTTP_PORT_TO_CLIENT_AS=2111
      - EVENTSTORE_GOSSIP_SEED=172.30.240.12:2113,172.30.240.13:2113
      - EVENTSTORE_TRUSTED_ROOT_CERTIFICATES_PATH=/certs/ca
      - EVENTSTORE_CERTIFICATE_FILE=/certs/node1/node.crt
      - EVENTSTORE_CERTIFICATE_PRIVATE_KEY_FILE=/certs/node1/node.key
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "curl --fail --insecure https://node1.eventstore: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.eventstore:
    <<: *template
    container_name: node2.eventstore
    env_file:
      - vars.env
    environment:
      - EVENTSTORE_INT_IP=172.30.240.12
      - EVENTSTORE_ADVERTISE_HTTP_PORT_TO_CLIENT_AS=2112
      - EVENTSTORE_GOSSIP_SEED=172.30.240.11:2113,172.30.240.13:2113
      - EVENTSTORE_TRUSTED_ROOT_CERTIFICATES_PATH=/certs/ca
      - EVENTSTORE_CERTIFICATE_FILE=/certs/node2/node.crt
      - EVENTSTORE_CERTIFICATE_PRIVATE_KEY_FILE=/certs/node2/node.key
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "curl --fail --insecure https://node2.eventstore:2113/health/live || exit 1",
        ]
      interval: 5s
      timeout: 5s
      retries: 24
    ports:
      - 2112:2113
    networks:
      clusternetwork:
        ipv4_address: 172.30.240.12

  node3.eventstore:
    <<: *template
    container_name: node3.eventstore
    environment:
      - EVENTSTORE_INT_IP=172.30.240.13
      - EVENTSTORE_ADVERTISE_HTTP_PORT_TO_CLIENT_AS=2113
      - EVENTSTORE_GOSSIP_SEED=172.30.240.11:2113,172.30.240.12:2113
      - EVENTSTORE_TRUSTED_ROOT_CERTIFICATES_PATH=/certs/ca
      - EVENTSTORE_CERTIFICATE_FILE=/certs/node3/node.crt
      - EVENTSTORE_CERTIFICATE_PRIVATE_KEY_FILE=/certs/node3/node.key
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "curl --fail --insecure https://node3.eventstore:2113/health/live || exit 1",
        ]
      interval: 5s
      timeout: 5s
      retries: 24
    ports:
      - 2113:2113
    networks:
      clusternetwork:
        ipv4_address: 172.30.240.13

networks:
  clusternetwork:
    name: eventstoredb.local
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.30.240.0/24

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

EVENTSTORE_CLUSTER_SIZE=3
EVENTSTORE_RUN_PROJECTIONS=All
EVENTSTORE_DISCOVER_VIA_DNS=false
EVENTSTORE_ENABLE_ATOM_PUB_OVER_HTTP=true
EVENTSTORE_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 the certs 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 or localhost) over HTTP, using ports specified below:

Node	HTTP port
node1	2111
node2	2112
node3	2113

You have to tell your client to use secure connection.

Protocol	Connection string
gRPC	esdb://localhost:2111,localhost:2112,localhost:2113?tls=true&tlsVerifyCert=false

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 the security section for detailed instructions.

Compatibility notes

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

Feature	Options impact
Connection without SSL or TLS	EventStoreDB 20.6+ is secure by default. Your clients need to establish a secure connection, unless you use the Insecure option.
Authentication and ACLs	When using the Insecure option for the server, all security is disabled. The Users menu item is also disabled in the Admin UI.
Projections	Running projections is disabled by default and the Projections menu item is disabled in the Admin UI. You need to enable projections explicitly by using the RunProjections option.
AtomPub protocol	In 20.6+, the AtomPub protocol is disabled by default. If you use this protocol, you have to explicitly enable it by using the EnableAtomPubOverHttp option.
Stream browser	The stream browser feature in Admin UI depends on the AtomPub protocol and is greyed out by default. You need to enable AtomPub (previous line) to make the stream browser work.