Running EventSourcingDB¶
This guide shows how to run EventSourcingDB using either Docker or pre-built binaries. You'll learn how to start and stop the service and how to access the management UI.
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. |
--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:
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¶
Verify that EventSourcingDB is running using the following command:
If you see the following output, EventSourcingDB is running successfully:
{
"specversion": "1.0",
"id": "0",
"time": "...",
"source": "https://www.eventsourcingdb.io",
"subject": "/api/v1/ping",
"type": "io.eventsourcingdb.api.ping-received",
"datacontenttype": "application/json",
"data": {
"message": "Oh 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¶
Press Ctrl+C to gracefully shut down EventSourcingDB. Graceful shutdowns typically complete in less than a second, but may occasionally take longer.
If you suspect that EventSourcingDB has stalled during shutdown, you can force a non-graceful shutdown by pressing Ctrl+C again.
Avoid Non-Graceful Shutdowns
Forcing a non-graceful shutdown can corrupt EventSourcingDB's internal data structures and may lead to data loss.
Using Pre-Built Binaries¶
Starting EventSourcingDB¶
Start EventSourcingDB using the following command:
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:
If you change the default port, you must adjust all further examples appropriately.
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¶
Verify that EventSourcingDB is running using the following command:
If you see the following output, EventSourcingDB is running successfully:
{
"specversion": "1.0",
"id": "0",
"time": "...",
"source": "https://www.eventsourcingdb.io",
"subject": "/api/v1/ping",
"type": "io.eventsourcingdb.api.ping-received",
"datacontenttype": "application/json",
"data": {
"message": "Oh 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¶
Press Ctrl+C to gracefully shutdown EventSourcingDB. Graceful shutdowns typically complete in less than a second, but may occasionally take longer.
If you suspect that EventSourcingDB has stalled during shutdown, you can force a non-graceful shutdown by pressing Ctrl+C again.
Avoid Non-Graceful Shutdowns
Forcing a non-graceful shutdown can corrupt EventSourcingDB's internal data structures and may lead to data loss.