build-on-nildb.md

Building on nilDB

This section outlines specific builder-related tasks and is deliberately utilitarian.

Documentation

An OpenAPI documentation site is available at localhost:8080/api/v1/openapi/docs/ when the node is running. The API specification is defined in /src/docs/openapi.yaml.

Note

Admin routes are not included in the OpenAPI documentation. For admin endpoints, refer to /src/admin/routes.ts.

Development Options

Run a single nilDB node

For simple development tasks, you can run a single node. However, note that secret sharing features require multiple nodes. To run a single node:

• Follow the source build instructions in CONTRIBUTING.md, or
• Modify docker-compose.local.yaml to run a single node

Run a local development cluster

1. Build the image:

   docker buildx build -f Dockerfile -t local/nildb-api:latest . 

2. Start the cluster:

   docker compose -p nildb-local -f docker-compose.local.yaml up -d

   [!CAUTION] The three nodes in docker-compose.local.yaml are prepopulated with root and node secret keys. These keys are for development purposes only and must not be used in production.

3. Verify the nodes are running:

   curl -s localhost:9181/about | jq
   curl -s localhost:9182/about | jq
   curl -s localhost:9183/about | jq

4. Monitor cluster logs:

   docker compose -p nildb-local logs -f

5. Cleanup:

   docker compose -p nildb-local down -v --remove-orphans

   [!WARNING] This command removes all containers, volumes, and networks associated with the cluster.