Skip to content

installation.md

Latest commit

 

History

History
135 lines (101 loc) · 5.01 KB

installation.md

File metadata and controls

135 lines (101 loc) · 5.01 KB
Raw
title Installation

Installation

TrogonEventStore can run as a single node for local development or as a cluster for production-like deployments.

Default access

User Password
admin changeit
ops changeit

Change the default credentials before using a node outside a disposable local environment.

Local development

Build the cluster node from source:

dotnet build -c Release src

Start a single local node:

dotnet ./src/EventStore.ClusterNode/bin/Release/net10.0/EventStore.ClusterNode.dll \
  --dev \
  --db ./tmp/data \
  --index ./tmp/index \
  --log ./tmp/log

The --dev option is intended for disposable local development. For any shared or production-like environment, configure certificates and authentication explicitly.

Docker

Build a local Docker image from the repository:

docker build --tag trogondb-local . \
  --build-arg CONTAINER_RUNTIME=noble \
  --build-arg RUNTIME=linux-x64

Run a single local node:

docker run --rm --name trogondb-node -it -p 2113:2113 \
  trogondb-local \
  --dev \
  --db /var/lib/trogondb/data \
  --index /var/lib/trogondb/index \
  --log /var/log/trogondb

For durable local data, mount database, index, and log directories into the container.

Production checklist

Before running a durable node or cluster:

  • Choose an approved PKI or issuer and follow the production certificate management guidance.
  • Issue a separate node certificate with the required SAN, common-name, and key-usage policy for each node.
  • Mount node certificates, private keys, and trusted roots read-only, and automate renewal plus explicit reload or rolling restart.
  • Decide whether clients use TLS and configure the connection strings accordingly.
  • Configure authentication methods in Security.
  • Store data, index, and logs on durable volumes.
  • Expose /-/liveness, /-/readiness, and /-/metrics to the platform.
  • Use gRPC clients for application reads and writes.
  • Expose the node HTTP(S) endpoint to clients and operators. Allow peer nodes to reach the dedicated cluster HTTP(S) endpoint on the private cluster network. No legacy EventStore TCP protocol listener is required or supported.

Linux service notes

When running on Linux, set the open file limit high enough for the expected database size and workload. The precise value depends on the deployment, but operators commonly start between 30000 and 60000.

Configuration can be supplied with command-line options, YAML, or environment variables. See Configuration.

Windows service notes

TrogonEventStore can run under the Windows Service Control Manager, but the source build does not register itself automatically.

The node handles Service Control Manager stop requests through graceful shutdown.

::: warning Windows startup deadline Windows Service Control Manager expects a service to report that it is running within its configured startup deadline. Configuration, certificate loading, and host construction occur before TrogonEventStore connects to the service manager, so delays or failures in that work can exhaust the deadline. Windows records service startup timeouts as Service Control Manager events such as 7000 or 7011.

Service Control Manager can report the service as running before the database is ready to accept traffic. Always use /-/readiness as the traffic gate. Before registering the node as a service, start the same command interactively to expose configuration or certificate delays. If Windows stops an otherwise healthy startup, investigate the delay first. If it is expected, increase the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ServicesPipeTimeout DWORD incrementally. The value is measured in milliseconds, and Windows must be restarted for a change to take effect. Microsoft documents this policy in A slow service does not start due to time-out error in Windows. :::

Example service registration:

sc.exe create TrogonDB binPath= "C:\TrogonDB\EventStore.ClusterNode.exe --config C:\TrogonDB\trogondb.conf"
sc.exe start TrogonDB

Do not rely on Service Control Manager failure actions alone to keep the service running. Some server workflows intentionally exit successfully, including the restart required after database truncation, and successful exits do not trigger failure recovery. Use an external service monitor or scheduled start command when automatic recovery is required.

Cluster startup

A production cluster normally uses three nodes. For each node:

  1. Create a node-specific configuration file.
  2. Provide node certificates and trusted roots.
  3. Configure gossip addresses for the cluster members.
  4. Start the node.
  5. Check readiness on /-/readiness.
  6. Check the cluster view in the Admin UI.