---
title: GenesisDB
description: GenesisDB is the open source and GDPR-ready event sourcing database for building event-driven apps.
product: Marketplace
url: https://docs.digitalocean.com/products/marketplace/catalog/genesisdb/
last_updated: "2026-10-30"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# GenesisDB

Generated on 30 Oct 2026 from [the GenesisDB catalog page](https://marketplace.digitalocean.com/apps/genesisdb)

GenesisDB is an open source database engine built specifically for event sourcing. It handles committing, fetching, querying and subscribing to events with native precision, while keeping consistency, reliability and usability front and center. Whether you are exploring event sourcing, comparing tools or building event-driven apps, GenesisDB is ready for it.

GenesisDB is free and open source under the MIT license, with no editions and no artificial limits. Every feature is included, from atomic commits with preconditions and hash-chained events to GDBQL queries, JSON schemas, erasable reference payloads and Prometheus metrics.

This 1-Click App runs [GenesisDB](https://www.genesisdb.io) 2.0.0 in Docker on Ubuntu 24.04. On first boot, the Droplet generates random administrator, write and read tokens and starts the API on port 8080. Log in via SSH to see the API address and where the tokens are stored.

Read the full documentation: [https://docs.genesisdb.io](https://docs.genesisdb.io)

Source code: [https://github.com/genesisdb-io/genesisdb](https://github.com/genesisdb-io/genesisdb)

## Software Included

| Package | Version | License |
|---|---|---|
| [GenesisDB](https://www.genesisdb.io) | 2.0.0 | [MIT](https://github.com/genesisdb-io/genesisdb?tab=MIT-1-ov-file) |

## Creating an App using the Control Panel

Click the **Deploy to DigitalOcean** button to create a Droplet based on this 1-Click App. If you aren’t logged in, this link will prompt you to log in with your DigitalOcean account.

[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/droplets/new?onboarding_origin=marketplace&appId=252204436&image=genesisdb&activation_redirect=%2Fdroplets%2Fnew%3FappId%3D252204436%26image%3Dgenesisdb)

## Creating an App using the API

In addition to creating a Droplet from the GenesisDB 1-Click App using the control panel, you can also use the [DigitalOcean API](https://docs.digitalocean.com/reference/api). As an example, to create a 4GB GenesisDB Droplet in the SFO2 region, you can use the following `curl` command. You need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) to an environment variable or substitute it in the command below.

```shell
curl -X POST -H 'Content-Type: application/json' \
         -H 'Authorization: Bearer '$TOKEN'' -d \
        '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"genesisdb"}' \
        "https://api.digitalocean.com/v2/droplets"
```

## Getting Started After Deploying GenesisDB

### Getting Started After Droplet Creation

GenesisDB starts automatically on first boot. The Droplet generates its own random tokens, so there is nothing to configure before the first request.

**1. SSH into your Droplet:**

```
ssh root@<your-droplet-ip>
```

The login message shows the API address, the token file and the most important commands.

**2. Load your tokens:**

```
source /etc/genesisdb/genesisdb.env
```

`/etc/genesisdb/genesisdb.env` is readable by root only and contains three tokens:

| Token | Access |
|---|---|
| `GENESISDB_AUTH_TOKEN` | Administrator, all routes including backup, audit and erasure |
| `GENESISDB_WRITE_TOKEN` | Read and commit events |
| `GENESISDB_READ_TOKEN` | Read only |

Use the write or read token in your applications and keep the administrator token for administration.

**3. Verify GenesisDB is running:**

```
curl http://localhost:8080/api/v2/ping
```

**4. Check status (authenticated):**

```
curl -H "Authorization: Bearer $GENESISDB_AUTH_TOKEN" \
  http://localhost:8080/api/v2/status
```

**5. Commit your first events:**

```
curl "http://localhost:8080/api/v2/commit" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $GENESISDB_WRITE_TOKEN" \
  --data '{
    "events": [
      {
        "source": "io.genesisdb.app",
        "subject": "/customer",
        "type": "io.genesisdb.app.customer-added",
        "data": {
          "firstName": "Bruce",
          "lastName": "Wayne",
          "emailAddress": "bruce.wayne@enterprise.wayne"
        }
      }
    ]
  }'
```

The response contains the stored event with its ID, time and hash. A subject with a single segment such as `/customer` gets a generated ID appended.

**6. Fetch events:**

```
curl "http://localhost:8080/api/v2/fetch" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $GENESISDB_READ_TOKEN" \
  --data '{
    "subject": "/customer"
  }'
```

**7. Connect from your application:**

Use `http://<your-droplet-ip>:8080` with one of the tokens. Official clients are available for JavaScript and TypeScript, Python, Go, Java, .NET, PHP, Rust and Swift, see [https://docs.genesisdb.io](https://docs.genesisdb.io).

Port 8080 serves plain HTTP. Before production use, put a TLS proxy in front of it or set `GENESISDB_TLS_CERT_FILE` and `GENESISDB_TLS_KEY_FILE`, and restrict access with a DigitalOcean Cloud Firewall.

### Changing Configuration

Edit the environment file and restart the service:

```
nano /etc/genesisdb/genesisdb.env
systemctl restart genesisdb
```

All settings are listed in the documentation. Logs: `journalctl -u genesisdb -f`

### Backups and Upgrades

**Back up `/var/lib/genesisdb` before every upgrade**, for example with a Droplet snapshot. Then upgrade to another GenesisDB version:

```
/opt/genesisdb/upgrade.sh <version>
```

* * *

## Startup Script

This script is executed once when the Droplet is first created. It generates the tokens and starts GenesisDB. Docker CE, the `genesisdb/genesisdb:2.0.0` image and the systemd service `genesisdb` are already installed in the image.

**Path:** `/var/lib/cloud/scripts/per-instance/01-genesisdb.sh`

```
#!/bin/bash
# Runs once on the first boot of every new Droplet. Generates the tokens and starts GenesisDB.
set -euo pipefail

env_file=/etc/genesisdb/genesisdb.env

if [ ! -f "$env_file" ]; then
  umask 077
  cat > "$env_file" <<EOF
GENESISDB_AUTH_TOKEN=$(openssl rand -hex 32)
GENESISDB_WRITE_TOKEN=$(openssl rand -hex 32)
GENESISDB_READ_TOKEN=$(openssl rand -hex 32)
GENESISDB_TZ=UTC
GENESISDB_METRICS=true
EOF
fi

systemctl start genesisdb.service

# Remove the login block added during the image build.
sed -i '/^Match User root/,/ForceCommand/d' /etc/ssh/sshd_config
systemctl reload ssh || systemctl reload sshd || true
```

**Service:** `/etc/systemd/system/genesisdb.service`

```
[Unit]
Description=GenesisDB
After=docker.service network-online.target
Requires=docker.service
Wants=network-online.target
ConditionPathExists=/etc/genesisdb/genesisdb.env

[Service]
EnvironmentFile=/etc/genesisdb/image.env
ExecStartPre=-/usr/bin/docker rm -f genesisdb
ExecStart=/usr/bin/docker run --rm --name genesisdb \
  -p 8080:8080 \
  --env-file /etc/genesisdb/genesisdb.env \
  -v /var/lib/genesisdb:/app/data \
  ${GENESISDB_IMAGE}
ExecStop=/usr/bin/docker stop -t 30 genesisdb
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

* * *

## Droplet Summary

| Concern | How it’s handled |
|---|---|
| **Auth tokens** | Administrator, write and read tokens (32 random bytes each) generated on first boot in `/etc/genesisdb/genesisdb.env`, readable by root only |
| **Version** | GenesisDB 2.0.0, pinned in `/etc/genesisdb/image.env` |
| **License** | Open source, MIT. No license key needed |
| **Timezone default** | `UTC`, configurable via `/etc/genesisdb/genesisdb.env` |
| **Data persistence** | Host directory `/var/lib/genesisdb` mounted to `/app/data` in the container, owned by UID 10001 |
| **Auto-start on boot** | systemd service `genesisdb` with `Restart=always` |
| **Reconfiguration** | Edit `/etc/genesisdb/genesisdb.env`, then `systemctl restart genesisdb` |
| **Upgrades** | Back up `/var/lib/genesisdb` first, then `/opt/genesisdb/upgrade.sh <version>` |
| **Port** | `8080`, plain HTTP, opened in `ufw`. Use TLS for production |
| **Firewall** | `ufw` allows SSH (rate limited) and 8080 only |
| **Health check** | `GET /api/v2/ping` (no authentication required) |
| **Metrics** | Prometheus metrics enabled on port 2112 inside the container, not published on the host |
| **Logs** | `journalctl -u genesisdb -f` |