GenesisDB CE

GenesisDB is an event sourcing database engine that can be easily deployed on Uberspace. This guide will walk you through the complete setup process for running GenesisDB CE (Community Edition).

Note

For this guide you should be familiar with the basic concepts of supervisord and web backends.

Prerequisites

Before setting up GenesisDB, ensure you have the following:

  1. Access to your Uberspace account

  2. Basic knowledge of command line operations

Installation

Step 1: Create Required Directories

First, create the necessary directories for GenesisDB:

[isabell@stardust ~]$ mkdir -p /home/$USER/bin
[isabell@stardust ~]$ mkdir -p /home/$USER/data
[isabell@stardust ~]$ mkdir -p /home/$USER/logs
[isabell@stardust ~]$

Step 2: Download and Install GenesisDB

Download the GenesisDB binary to your bin directory:

[isabell@stardust ~]$ cd /home/$USER/bin
[isabell@stardust bin]$ wget https://releases.genesisdb.io/latest/genesisdb-linux-amd64-ce -O genesisdb-ce-linux-amd64.tar.gz
[isabell@stardust bin]$ tar -xzf genesisdb-ce-linux-amd64.tar.gz

Configuration

Step 3: Create Supervisord Configuration

Create a configuration file ~/etc/services.d/genesisdb.ini for GenesisDB. Replace YOUR_AUTH_TOKEN with your actual GenesisDB authentication token. It is recommended to create a secure, strong password: pwgen 64 -1

[program:genesisdb]
command=/home/$USER/bin/genesisdb-ce-1.0.9-linux-amd64/genesisdb
directory=/home/$USER
autostart=true
autorestart=true
startsecs=2
stopsignal=TERM
environment=GENESISDB_AUTH_TOKEN="YOUR_AUTH_TOKEN",GENESISDB_TZ="Europe/Vienna",GENESISDB_PROMETHEUS_METRICS="false",GENESISDB_DATA_DIR="/home/$USER/data"
stdout_logfile=/home/$USER/logs/genesisdb.out.log
stderr_logfile=/home/$USER/logs/genesisdb.err.log

Step 4: Start GenesisDB Service

Reload supervisord configuration and start the GenesisDB service:

[isabell@stardust ~]$ supervisorctl reread
genesisdb: available
[isabell@stardust ~]$ supervisorctl update
genesisdb: added process group
[isabell@stardust ~]$ supervisorctl start genesisdb
genesisdb: started
[isabell@stardust ~]$

Step 5: Configure Web Access

Find an available port starting from 8081:

[isabell@stardust ~]$ ss -tlnp | grep :808
[isabell@stardust ~]$

If port 8081 is available, use it. Otherwise, try higher port numbers until you find an available one.

Add your custom domain and configure the web backend:

[isabell@stardust ~]$ uberspace web domain add genesisdb.domain.tld
[isabell@stardust ~]$ uberspace web backend set / --http --port 8081 --domain genesisdb.domain.tld
[isabell@stardust ~]$

Verification

Check if GenesisDB is running correctly:

[isabell@stardust ~]$ supervisorctl status genesisdb
genesisdb                        RUNNING   pid 1234, uptime 0:01:23
[isabell@stardust ~]$

Check the logs for any issues:

[isabell@stardust ~]$ tail -f /home/$USER/logs/genesisdb.out.log
[isabell@stardust ~]$ tail -f /home/$USER/logs/genesisdb.err.log
[isabell@stardust ~]$

Your GenesisDB instance should now be accessible via your configured domain.

Configuration Options

GenesisDB supports various environment variables for configuration:

  • GENESISDB_AUTH_TOKEN: Your authentication token (required)

  • GENESISDB_DATA_DIR: Data directory path (default: /home/$USER/data)

  • GENESISDB_TZ: Timezone setting (default: Europe/Vienna)

  • GENESISDB_PROMETHEUS_METRICS: Enable Prometheus metrics (default: false)

Maintenance

Managing the Service

To stop GenesisDB:

[isabell@stardust ~]$ supervisorctl stop genesisdb
[isabell@stardust ~]$

To restart GenesisDB:

[isabell@stardust ~]$ supervisorctl restart genesisdb
[isabell@stardust ~]$

Log Rotation

GenesisDB logs are automatically rotated by supervisord. You can manually rotate logs if needed:

[isabell@stardust ~]$ supervisorctl signal USR2 genesisdb
[isabell@stardust ~]$

Troubleshooting

Common Issues

  1. Service fails to start: Check the error logs in /home/$USER/logs/genesisdb.err.log

  2. Permission denied: Ensure the binary has execute permissions: chmod +x /home/$USER/bin/genesisdb-1.0.9-linux-amd64/genesisdb

  3. Port conflicts: Use ss -tlnp | grep :PORT to check if a port is already in use

  4. Domain issues: Verify domain configuration with uberspace web domain list

Getting Help

If you encounter issues:

  1. Check the GenesisDB documentation

  2. Review the supervisord logs: supervisorctl tail genesisdb

  3. Contact Uberspace support for platform-specific issues

Tested with GenesisDB CE 1.0.9, Uberspace 7.15.0