For AI agents: The documentation index is at 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 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 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

Source code: https://github.com/genesisdb-io/genesisdb

Software Included

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.

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. 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 to an environment variable or substitute it in the command below.

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:

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": "[email protected]"
        }
      }
    ]
  }'

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.

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