Getting Started

This guide provides instructions for setting up a local development environment for the book-keeper service.

The recommended way to develop within this monorepo is by using the provided VS Code Dev Container. This creates a consistent, fully-configured development environment with all necessary tools and backing services (PostgreSQL, Redis, NATS, etc.) running automatically.

---

Dev Container

This method provides a one-click setup for a complete, isolated development environment.

Prerequisites

• IDE that supports devcontainer
• Docker Desktop
• The Dev Containers extension.

Steps

1. Clone the repository:

   git clone https://gitlab.com/castlecraft/citadel.git
   cd citadel

2. Set up the Dev Container configuration:

   From the root of the project, copy the example configuration to create your local .devcontainer setup. This directory is ignored by git.

   cp -r devcontainer-example .devcontainer

3. Open in VS Code and Reopen in Container:

   Open the citadel folder in VS Code. A notification will appear in the bottom-right corner prompting you to "Reopen in Container". Click it.

   VS Code will build the container, start all the core services, and install all dependencies.

4. Set up Book Keeper's Environment Variables:

   Once the container is running, open a new terminal inside VS Code and run:

   cd /workspace/citadel/apps/book-keeper
   cp devcontainer.env .env

You are now ready to run, debug, and test the book-keeper service directly from within VS Code.

Enabling High-Performance Backends (Optional)

By default, the dev container runs with PostgreSQL. To test against high-performance backends like TigerBeetle and KurrentDB, you need to enable them before building the container.

1. Enable the Services in devcontainer.json:

   Before you "Reopen in Container", open the .devcontainer/devcontainer.json file. Find the dockerComposeFile array and uncomment the lines for compose.kurrentdb.yml and compose.tigerbeetle.yml:

   // .devcontainer/devcontainer.json
   "dockerComposeFile": [
     "compose.core.yml",
     // ... other services
     // --- For Specialized Event Store for Event Sourced Applications ---
     "compose.kurrentdb.yml",
   
     // --- For Book-Keeper Service Development ---
     "compose.tigerbeetle.yml",
     // ... other services
   ],

2. Rebuild the Container:

   Run the command Dev Containers: Rebuild Container from the VS Code command palette (Ctrl+Shift+P). This will restart the environment with the newly enabled services.

3. Update Environment for TigerBeetle:

   The TigerBeetle client requires an IP address. After the container has rebuilt and is running, open a terminal in VS Code and run the following command to automatically find the IP and update your .env file:

   cd /workspace/citadel/apps/book-keeper
   export IP_ADDRESS=$(getent hosts tigerbeetle | awk '{ print $1 }')
   sed -i "s|^TIGERBEETLE_REPLICA_ADDRESSES=.*|TIGERBEETLE_REPLICA_ADDRESSES=${IP_ADDRESS}:3000|" .env