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
EventStore Configurator online tool can help you to go through all the required steps.
You can provide the details about your desired deployment topology, and get the following:
- Generated configuration files
- Instructions for obtaining or generating SSL certificates
- Installation guidelines
- gRPC and TCP client connection details
Event Store Cloud
Avoid deploying, configuring, and maintaining the EventStoreDB instance yourself by using Event Store Cloud.
Install from PackageCloud
EventStoreDB has pre-built packages available for Debian-based distributions, manual instructions for distributions that use RPM, or you can build from source. The final package name to install is
If you installed from a pre-built package, the server gets 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. It's done to allow you to change the configuration, located at /etc/eventstore/eventstore.conf and to prevent creating database and index files in the default location.
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
Building from source
You can also build EventStoreDB on Linux from source. Before doing that, you need to install .NET Core 3.1 or .NET 5 SDK. EventStoreDB packages have the .NET Core Runtime embedded, so you don't need to install anything except the EventStoreDB package.
If you installed one of the pre-built packages for Debian based systems, you can remove it with:
sudo apt-get purge eventstore-oss
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.
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 in an elevated terminal:
choco install eventstore-oss
Download the binaries
You can also download a binary, unzip the archive and run from the folder location with an administrator console.
The following command starts EventStoreDB with the database stored at the path ./db and the logs in ./logs. Read mode about configuring the EventStoreDB server node in the Configuration section.
EventStore.ClusterNode.exe --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
add urlacl documentation.
To build EventStoreDB from source, refer to the EventStoreDB GitHub repository.
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
- Removing the directory from your PATH.
You can run EventStoreDB in Docker container as a single node, using insecure mode. It's good enough 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 gRPC clients and
esdb://localhost:2113?tls=false connection string. The Admin UI will be accessible, but the Stream Browser won't work (it needs AtomPub to be enabled).
docker run --name esdb-node -it -p 2113:2113 -p 1113:1113 \ eventstore/eventstore:latest --insecure --run-projections=All
If you want to start the node with legacy protocols enabled (TCP and AtomPub), you need to add a couple of other options:
docker run --name esdb-node -it -p 2113:2113 -p 1113:1113 \ eventstore/eventstore:latest --insecure --run-projections=All \ --enable-external-tcp --enable-atom-pub-over-http
The command above would run EventStoreDB as a single node without SSL and with the legacy TCP protocol enabled, so you can try out your existing apps with the latest database version.
Then, you'd be able to connect to EventStoreDB with gRPC and TCP 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.
docker-compose.yaml with following content:
version: "3.4" services: eventstore.db: image: eventstore/eventstore:20.10.2-buster-slim environment: - EVENTSTORE_CLUSTER_SIZE=1 - EVENTSTORE_RUN_PROJECTIONS=All - EVENTSTORE_START_STANDARD_PROJECTIONS=true - EVENTSTORE_EXT_TCP_PORT=1113 - EVENTSTORE_HTTP_PORT=2113 - EVENTSTORE_INSECURE=true - EVENTSTORE_ENABLE_EXTERNAL_TCP=true - EVENTSTORE_ENABLE_ATOM_PUB_OVER_HTTP=true ports: - "1113:1113" - "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:
The command above would run EventStoreDB as a single node without SSL and with the legacy TCP protocol enabled. You also get AtomPub protocol enabled, so you can get the stream browser to work in the Admin UI.
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.
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:20.10.2-buster-slim 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_ADVERTISE_TCP_PORT_TO_CLIENT_AS=1111 - 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: - 1111:1113 - 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_ADVERTISE_TCP_PORT_TO_CLIENT_AS=1112 - 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: - 1112:1113 - 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_ADVERTISE_TCP_PORT_TO_CLIENT_AS=1113 - 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: - 1113:1113 - 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_EXTERNAL_TCP=true 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 to create the directory on startup, the container won't be able to get write access to it. Therefore, create the
certs directory manually. You only need to do it once.
Now you are ready to start the cluster.
Check the log messages, after some time the elections process completes, and you'd be able to connect to each node using the Admin UI. Nodes should be accessible on the loopback address (
localhost) over HTTP and TCP, using ports specified below:
|Node||TCP port||HTTP port|
You have to tell your client to use secure connection for both TCP and gRPC.
As you might've noticed, both connection strings have a setting to disable the certificate validation (
gRPC). It would prevent the invalid certificate error since the cluster uses a private, auto-generated CA. validation (
gRPC). It would prevent the invalid certificate error since the cluster uses self-signed certificates.
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 instruction of how to do it.
Depending on how your EventStoreDB instance is configured, some features might not work. On this page, you can find some notes about features being not available because of some options are set or not set accordingly.
|Connection for TCP clients||External TCP is disabled by default. You need to enable it explicitly by using the |
|Connection without SSL or TLS||EventStoreDB 20.6+ is secure by default. Your clients need to establish a secure connection, unless you use the |
|Authentication and ACLs||When using the |
|Projections||Running projections is disabled by default and the |
|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 |
|Stream browser||The stream browser feature in Admin UI depends on the AtomPub protocol and also gets greyed out by default. You need to enable AtomPub (previous line) to make the stream browser work.|