From 8ff690f342e3616fb9fd9620e8eecebd7318093e Mon Sep 17 00:00:00 2001 From: Patric Eckhart Date: Tue, 26 Aug 2025 18:30:33 +0200 Subject: [PATCH 1/4] guide_genesis-db.rst added --- source/guide_genesis-db.rst | 212 ++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 source/guide_genesis-db.rst diff --git a/source/guide_genesis-db.rst b/source/guide_genesis-db.rst new file mode 100644 index 00000000..577f0872 --- /dev/null +++ b/source/guide_genesis-db.rst @@ -0,0 +1,212 @@ +.. highlight:: console + +.. author:: Patric Eckhart + +.. tag:: database +.. tag:: event-sourcing +.. tag:: event-store +.. tag:: event-storming +.. tag:: event-driven +.. tag:: event-driven-architecture +.. tag:: event-driven-design +.. tag:: event-driven-development +.. tag:: event-driven-architecture + +############ +Genesis DB +############ + +Genesis DB 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 Genesis DB. + +---- + +.. note:: For this guide you should be familiar with the basic concepts of :manual:`supervisord ` and :manual:`web backends `. + +Prerequisites +============= + +Before setting up Genesis DB, 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 Genesis DB: + +.. code-block:: bash + + [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 Genesis DB +--------------------------------------- + +Download the Genesis DB binary to your bin directory: + +.. code-block:: bash + + [isabell@stardust ~]$ cd /home/$USER/bin + [isabell@stardust bin]$ wget https://releases.genesisdb.io/latest/genesisdb-linux-amd64 + [isabell@stardust bin]$ chmod +x genesisdb + [isabell@stardust bin]$ + +Configuration +============= + +Step 3: Create Supervisord Configuration +----------------------------------------- + +Create the supervisord configuration directory if it doesn't exist: + +.. code-block:: bash + + [isabell@stardust ~]$ mkdir -p ~/etc/services.d + [isabell@stardust ~]$ + +Create a configuration file for Genesis DB. Replace ``YOUR_AUTH_TOKEN`` with your actual Genesis DB authentication token: + +.. code-block:: bash + + [isabell@stardust ~]$ cat > ~/etc/services.d/genesisdb.ini << EOF + [program:genesisdb] + command=/home/$USER/bin/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 + EOF + [isabell@stardust ~]$ + +Step 4: Start Genesis DB Service +------------------------------- + +Reload supervisord configuration and start the Genesis DB service: + +.. code-block:: bash + + [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: + +.. code-block:: bash + + [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: + +.. code-block:: bash + + [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 Genesis DB is running correctly: + +.. code-block:: bash + + [isabell@stardust ~]$ supervisorctl status genesisdb + genesisdb RUNNING pid 1234, uptime 0:01:23 + [isabell@stardust ~]$ + +Check the logs for any issues: + +.. code-block:: bash + + [isabell@stardust ~]$ tail -f /home/$USER/logs/genesisdb.out.log + [isabell@stardust ~]$ tail -f /home/$USER/logs/genesisdb.err.log + [isabell@stardust ~]$ + +Your Genesis DB instance should now be accessible via your configured domain. + +Configuration Options +===================== + +Genesis DB 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 Genesis DB: + +.. code-block:: bash + + [isabell@stardust ~]$ supervisorctl stop genesisdb + [isabell@stardust ~]$ + +To restart Genesis DB: + +.. code-block:: bash + + [isabell@stardust ~]$ supervisorctl restart genesisdb + [isabell@stardust ~]$ + +Log Rotation +------------ + +Genesis DB logs are automatically rotated by supervisord. You can manually rotate logs if needed: + +.. code-block:: bash + + [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`` +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 Genesis DB documentation +2. Review the supervisord logs: ``supervisorctl tail genesisdb`` +3. Contact Uberspace support for platform-specific issues + +---- + +Tested with Genesis DB 1.0.0, Uberspace 7.15.0 + +.. _Genesis DB: https://genesisdb.io/ +.. _Genesis DB Docs: https://docs.genesisdb.io/ From 5953e8c30cd93d727bdf917ff83decb5e1583e5d Mon Sep 17 00:00:00 2001 From: Patric Eckhart Date: Tue, 7 Oct 2025 19:02:21 +0200 Subject: [PATCH 2/4] Update guide_genesis-db.rst Meanwhile, the pre-built binaries have changed --- source/guide_genesis-db.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/guide_genesis-db.rst b/source/guide_genesis-db.rst index 577f0872..8a87ee6c 100644 --- a/source/guide_genesis-db.rst +++ b/source/guide_genesis-db.rst @@ -53,7 +53,9 @@ Download the Genesis DB binary to your bin directory: .. code-block:: bash [isabell@stardust ~]$ cd /home/$USER/bin - [isabell@stardust bin]$ wget https://releases.genesisdb.io/latest/genesisdb-linux-amd64 + [isabell@stardust bin]$ wget https://releases.genesisdb.io/latest/genesisdb-linux-amd64 -O genesisdb-linux-amd64.tar.gz + [isabell@stardust bin]$ tar -xzf genesisdb-linux-amd64.tar.gz + [isabell@stardust bin]$ cd genesisdb-1.0.5-linux-amd64 [isabell@stardust bin]$ chmod +x genesisdb [isabell@stardust bin]$ @@ -76,7 +78,7 @@ Create a configuration file for Genesis DB. Replace ``YOUR_AUTH_TOKEN`` with you [isabell@stardust ~]$ cat > ~/etc/services.d/genesisdb.ini << EOF [program:genesisdb] - command=/home/$USER/bin/genesisdb + command=/home/$USER/bin/genesisdb-1.0.5-linux-amd64/genesisdb directory=/home/$USER autostart=true autorestart=true @@ -191,7 +193,7 @@ 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`` +2. **Permission denied**: Ensure the binary has execute permissions: ``chmod +x /home/$USER/bin/genesisdb-1.0.5-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`` From ff6bd8a0c01a12dc50a986ddbbdaa6ff76e18966 Mon Sep 17 00:00:00 2001 From: Moritz Date: Thu, 13 Nov 2025 14:18:22 +0100 Subject: [PATCH 3/4] Update guide_genesis-db.rst adapt guide to our Stleguide --- source/guide_genesis-db.rst | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/source/guide_genesis-db.rst b/source/guide_genesis-db.rst index 8a87ee6c..8491f570 100644 --- a/source/guide_genesis-db.rst +++ b/source/guide_genesis-db.rst @@ -55,9 +55,6 @@ Download the Genesis DB binary to your bin directory: [isabell@stardust ~]$ cd /home/$USER/bin [isabell@stardust bin]$ wget https://releases.genesisdb.io/latest/genesisdb-linux-amd64 -O genesisdb-linux-amd64.tar.gz [isabell@stardust bin]$ tar -xzf genesisdb-linux-amd64.tar.gz - [isabell@stardust bin]$ cd genesisdb-1.0.5-linux-amd64 - [isabell@stardust bin]$ chmod +x genesisdb - [isabell@stardust bin]$ Configuration ============= @@ -65,18 +62,10 @@ Configuration Step 3: Create Supervisord Configuration ----------------------------------------- -Create the supervisord configuration directory if it doesn't exist: +Create a configuration file ``~/etc/services.d/genesisdb.ini`` for Genesis DB. Replace ``YOUR_AUTH_TOKEN`` with your actual Genesis DB authentication token: .. code-block:: bash - [isabell@stardust ~]$ mkdir -p ~/etc/services.d - [isabell@stardust ~]$ - -Create a configuration file for Genesis DB. Replace ``YOUR_AUTH_TOKEN`` with your actual Genesis DB authentication token: - -.. code-block:: bash - - [isabell@stardust ~]$ cat > ~/etc/services.d/genesisdb.ini << EOF [program:genesisdb] command=/home/$USER/bin/genesisdb-1.0.5-linux-amd64/genesisdb directory=/home/$USER @@ -87,8 +76,6 @@ Create a configuration file for Genesis DB. Replace ``YOUR_AUTH_TOKEN`` with you 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 - EOF - [isabell@stardust ~]$ Step 4: Start Genesis DB Service ------------------------------- From 2ea552ede67d1d05c1197d3fe7840da2bbec67e3 Mon Sep 17 00:00:00 2001 From: Patric Eckhart Date: Thu, 13 Nov 2025 16:48:30 +0100 Subject: [PATCH 4/4] Update guide for Genesis DB CE setup --- source/guide_genesis-db.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/guide_genesis-db.rst b/source/guide_genesis-db.rst index 8491f570..fa6141dd 100644 --- a/source/guide_genesis-db.rst +++ b/source/guide_genesis-db.rst @@ -12,11 +12,11 @@ .. tag:: event-driven-development .. tag:: event-driven-architecture -############ -Genesis DB -############ +############# +Genesis DB CE +############# -Genesis DB 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 Genesis DB. +Genesis DB 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 Genesis DB CE (Community Edition). ---- @@ -53,8 +53,8 @@ Download the Genesis DB binary to your bin directory: .. code-block:: bash [isabell@stardust ~]$ cd /home/$USER/bin - [isabell@stardust bin]$ wget https://releases.genesisdb.io/latest/genesisdb-linux-amd64 -O genesisdb-linux-amd64.tar.gz - [isabell@stardust bin]$ tar -xzf genesisdb-linux-amd64.tar.gz + [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 ============= @@ -62,12 +62,12 @@ Configuration Step 3: Create Supervisord Configuration ----------------------------------------- -Create a configuration file ``~/etc/services.d/genesisdb.ini`` for Genesis DB. Replace ``YOUR_AUTH_TOKEN`` with your actual Genesis DB authentication token: +Create a configuration file ``~/etc/services.d/genesisdb.ini`` for Genesis DB. Replace ``YOUR_AUTH_TOKEN`` with your actual Genesis DB authentication token. It is recommended to create a secure, strong password: ``pwgen 64 -1`` .. code-block:: bash [program:genesisdb] - command=/home/$USER/bin/genesisdb-1.0.5-linux-amd64/genesisdb + command=/home/$USER/bin/genesisdb-ce-1.0.9-linux-amd64/genesisdb directory=/home/$USER autostart=true autorestart=true @@ -180,7 +180,7 @@ 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.5-linux-amd64/genesisdb`` +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`` @@ -195,7 +195,7 @@ If you encounter issues: ---- -Tested with Genesis DB 1.0.0, Uberspace 7.15.0 +Tested with Genesis DB CE 1.0.9, Uberspace 7.15.0 .. _Genesis DB: https://genesisdb.io/ .. _Genesis DB Docs: https://docs.genesisdb.io/