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

```shell
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](/docs/eventsourcingdb/cli)**.

| 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](/docs/eventsourcingdb/cli)** 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:

```shell
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](https://fetch.spec.whatwg.org/#port-blocking)**.
>
> **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:

```shell
curl http://localhost:3000/api/v1/ping
```

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

```json
{
  "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:

**macOS**

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

**Linux**

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

**Windows**

```shell
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](#understanding-the-command-line-flags)** above or consult **[CLI Overview](/docs/eventsourcingdb/cli)**.

#### Changing the Default Port

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

**macOS**

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

**Linux**

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

**Windows**

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

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](https://fetch.spec.whatwg.org/#port-blocking)**.
>
> **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:

```shell
curl http://localhost:3000/api/v1/ping
```

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

```json
{
  "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](/docs/eventsourcingdb/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.