Running EventSourcingDB

Using Docker#

The following example shows how to run EventSourcingDB for development and testing purposes.

Starting EventSourcingDB#

Start EventSourcingDB using the following command:

docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb run \
  --api-token=secret \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui

Understanding the Command-Line Flags#

These flags allow you to customize EventSourcingDB. For a complete list of configuration options, see CLI Overview.

Flag	Purpose	Details
`--api-token=secret`	Sets the API token	Clients must send this token as a bearer token in the `Authorization` HTTP header.
`--data-directory-temporary`	Uses a temporary data directory	Avoids manual setup and cleans up data automatically on shutdown. With it, every license holds for at most 48 hours from the start.
`--http-enabled`	Enables HTTP access	Allows unencrypted HTTP access for development and testing purposes.
`--https-enabled=false`	Disables HTTPS access	Simplifies setup by avoiding private key and certificate configuration.
`--with-ui`	Enables the management UI	Provides a basic UI for monitoring and health checks.

Do Not Use These Configuration Settings In Production

These settings simplify setup for development and testing but are not secure for production. Refer to CLI Overview for production-ready configurations.

Changing the Default Port#

By default, EventSourcingDB runs on port 3000. To use a different port, update the -p flag. E.g., to run EventSourcingDB on port 4000, use:

docker run -it -p 4000:3000 [...]

If you change the default port, you must adjust all further examples appropriately.

Understanding Ports in Docker

The -p flag maps the host port (e.g., 4000) to the container's internal port (3000). Changing the internal port using the --http-port flag will only affect the container and can cause connectivity issues if not paired with the correct -p flag.

Browser-Blocked Ports

Some ports are blocked by browsers for security reasons and cannot be used to access the management UI. If you start EventSourcingDB with --with-ui on one of these ports, the API will work normally but the UI will not be accessible in browsers.

Common blocked ports include 22 (SSH), 25 (SMTP), 6000 (X11), 6665 (IRC), and many others. For a complete list, see the WHATWG Fetch specification.

Recommended ports: Use ports like 3000, 4000, 8080, or 8443 for development.

Verifying that EventSourcingDB is Running#

Changed in 1.3Verify that EventSourcingDB is running using the following command:

curl http://localhost:3000/api/v2/system/ping

If you see output like the following, EventSourcingDB is running successfully:

{
  "type": "event",
  "data": {
    "specversion": "1.0",
    "id": "01a17249-c6fb-752e-89a7-834df2a74de4",
    "source": "https://www.eventsourcingdb.io",
    "type": "io.eventsourcingdb.api.ping-received",
    "subject": "/api/v2/system/ping",
    "time": "2026-10-25T09:00:00.123456789Z",
    "datacontenttype": "application/json",
    "data": {
      "message": "My God, it's full of stars."
    }
  }
}

If not, review the previous steps, check the output for errors, and ensure the port mapping is correct.

Accessing the Management UI#

To access the management UI point your browser to http://localhost:3000.

Shutting Down EventSourcingDB#

Changed in 1.3Press Ctrl+C to gracefully shut down EventSourcingDB, or send it SIGTERM, as Docker and Kubernetes do, or SIGQUIT. A graceful shutdown ends running reads, observations, audits, verifications, backups, registrations of event schemas that still check the existing events, and writes whose EventQL precondition is still being evaluated, with the error server-shutting-down, and gives every other request up to five seconds to finish. It then writes everything EventSourcingDB has stored but not yet written to its data files, which can take a few seconds, so that the next start has nothing to replay. A restore that is running at that moment is interrupted; see When a Restore Fails.

If you suspect that EventSourcingDB has stalled during shutdown, you can force a non-graceful shutdown by pressing Ctrl+C again, or by sending it any of these signals a second time.

Non-Graceful Shutdowns

A non-graceful shutdown loses no write that EventSourcingDB has confirmed: the next start replays it from the write-ahead log, which makes that start take longer. A write that was in progress at that moment has not been confirmed, and its client receives an error.

Using Pre-Built Binaries#

Starting EventSourcingDB#

Start EventSourcingDB using the following command:

./eventsourcingdb run \
  --api-token=secret \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui

./eventsourcingdb run \
  --api-token=secret \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui

eventsourcingdb run ^
  --api-token=secret ^
  --data-directory-temporary ^
  --http-enabled ^
  --https-enabled=false ^
  --with-ui

Understanding the Command-Line Flags#

For an explanation of the command-line flags, see the Docker section above or consult CLI Overview.

Changing the Default Port#

To use a different port when running binaries, provide the --http-port flag:

./eventsourcingdb run \
  --http-port=4000 \
  [...]

./eventsourcingdb run \
  --http-port=4000 \
  [...]

eventsourcingdb run ^
  --http-port=4000 ^
  [...]

If you change the default port, you must adjust all further examples appropriately.

Browser-Blocked Ports

Common blocked ports include 22 (SSH), 25 (SMTP), 6000 (X11), 6665 (IRC), and many others. For a complete list, see the WHATWG Fetch specification.

Recommended ports: Use ports like 3000, 4000, 8080, or 8443 for development.

Verifying that EventSourcingDB is Running#

Changed in 1.3Verify that EventSourcingDB is running using the following command:

curl http://localhost:3000/api/v2/system/ping

If you see output like the following, EventSourcingDB is running successfully:

{
  "type": "event",
  "data": {
    "specversion": "1.0",
    "id": "01a17249-c6fb-752e-89a7-834df2a74de4",
    "source": "https://www.eventsourcingdb.io",
    "type": "io.eventsourcingdb.api.ping-received",
    "subject": "/api/v2/system/ping",
    "time": "2026-10-25T09:00:00.123456789Z",
    "datacontenttype": "application/json",
    "data": {
      "message": "My God, it's full of stars."
    }
  }
}

If not, review the previous steps, check the output for errors, and ensure the specified port is open and accessible.

Accessing the Management UI#

To access the management UI point your browser to http://localhost:3000.

For more information, see Using the Management UI.

Shutting Down EventSourcingDB#

If you suspect that EventSourcingDB has stalled during shutdown, you can force a non-graceful shutdown by pressing Ctrl+C again, or by sending it any of these signals a second time.

Non-Graceful Shutdowns

Exit Codes#

When EventSourcingDB stops, its exit code tells a supervisor, such as Docker, Kubernetes, or systemd, whether it stopped as intended. It exits with 0 after a graceful shutdown that a signal started, and with 1 if it stopped because of a problem or was forced to stop:

It could not start, for example because a required flag is missing, two flags contradict each other, the license is not valid, or another server has its data directory open, see One Server per Data Directory.
It was stopped while it was still starting, for example while it replayed its write-ahead log. This is as safe as a crash: the next start replays what this one did not finish.
Its HTTP or HTTPS port could not be opened, for example because another process uses it. EventSourcingDB then shuts down gracefully, but still exits with 1.
Closing its store at the end of a graceful shutdown failed, for example because writing its data files failed. The next start then replays the write-ahead log, which takes longer.
A second signal forced a non-graceful shutdown. This holds for any of the signals that start a shutdown, not only for a second Ctrl+C.