For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Features

MongoDB wire-protocol endpoint served by the NoSQLDB native engine
File-backed persistence under /data/nosqldb
SCRAM-SHA-256 authenticated root user and tenant users
Single-node multi-document transactions through the official drivers
Tenant provisioning with isolated database/user pairs
Admin UI for status, connection info, tenants, collections, and the operation log
Health and metrics endpoints for container orchestration
Single Docker image running on Node.js (host.today/ht-docker-node:alpine)

Quick Start

docker run -d \
  --name database \
  -p 27017:27017 \
  -p 127.0.0.1:3000:3000 \
  -v databasedata:/data \
  -e DBST_ROOT_PASSWORD=change-root-password \
  -e DBST_ADMIN_PASSWORD=change-admin-password \
  code.foss.global/lossless.zone/database:latest

Connect with mongodb://root:<password>@localhost:27017/admin?authSource=admin&directConnection=true. Open http://localhost:3000 and sign in with username admin and DBST_ADMIN_PASSWORD.

Development

pnpm install
pnpm run build
node cli.js server --ephemeral

pnpm run build writes the frontend bundle (ts_bundled/bundle.ts) and compiles every ts* folder to dist_*. node cli.ts.js server --ephemeral runs the TypeScript sources directly through tsrun, and pnpm run watch restarts that server on changes.

Configuration

Variable	Description	Default
`DBST_PORT`	MongoDB wire-protocol port	`27017`
`DBST_UI_PORT`	Management UI, health and metrics port	`3000`
`DBST_STORAGE_DIR`	Persistent storage directory	`/data`
`DBST_PUBLIC_HOST`	Hostname shown in connection strings	`127.0.0.1`
`DBST_ROOT_USERNAME`	Root database username (`admin` auth database, `root` role)	`root`
`DBST_ROOT_PASSWORD`	Root database password, applied when the storage is initialised	`admin`
`DBST_ADMIN_PASSWORD`	Admin UI password	`admin`
`DBST_AUTH_ENABLED`	Enable wire-protocol authentication	`true`
`DBST_ALLOW_INSECURE_DEFAULTS`	Allow default credentials on `/data`	`false`

Persistent /data refuses default root/admin passwords unless DBST_ALLOW_INSECURE_DEFAULTS=true is set for disposable development.

Root credentials

The root user is created from DBST_ROOT_USERNAME and DBST_ROOT_PASSWORD when the engine initialises an empty storage directory. NoSQLDB keeps authentication inside its storage, so on an existing volume the stored root credentials stay authoritative and a different DBST_ROOT_PASSWORD does not change them (like MONGO_INITDB_ROOT_* in the official MongoDB image).

The container checks this at startup: once the engine is up it authenticates with the configured root credentials. If they are rejected, the container keeps running but never reports ready: /readyz answers 503 with {"ok":false,"status":"misconfigured","reason":"…"}, the Docker health check turns unhealthy, and the log carries a NOT READY: line. The reason names the username and storage path, never the password. Recover by starting with the credentials the storage was initialised with, or change the stored password with updateUser while connected with them and restart with the new DBST_ROOT_PASSWORD.

Passwords are stored as SCRAM-SHA-256 credentials with 15000 iterations. The work factor is fixed per storage directory.

Transactions

The engine is one voting node. Drivers must connect with directConnection=true and without a replicaSet option; sessions and multi-document transactions (withTransaction, startTransaction/commitTransaction/abortTransaction) work in that topology. Tools that require a replica-set topology are not supported. As in MongoDB, a transaction that stays open for more than 60 seconds is aborted; its later statements and its commit fail with NoSuchTransaction.

Runtime user and data directory

The image runs as uid/gid 999:999 (user database), the same ids the ObjectStorage and official MongoDB images use. A bind-mounted /data must be writable by 999:999; the engine creates /data/nosqldb itself with mode 0700.

Upgrading from 2.x

Version 3 runs on Node.js instead of Deno and reads 2.x volumes unchanged: start it on the same /data volume. The image keeps its user (999:999), ports, volume and health check; its command is now node cli.js server, so tools that compare the container command (such as gitzone services) need a release that pins the version 3 image.

Upgrading from 1.x

Version 1.x stored SmartDB data in /data/smartdb and its users in /data/.database/users.json. NoSQLDB cannot open that layout, and version 2 never converts or deletes it: while /data/smartdb exists, startup is refused with a message that names the migration route.

Run code.foss.global/lossless.zone/database:1.1.0 on the old volume and export every database with the exportDatabase ops API (or mongodump).
Start version 2 on a fresh volume and import each export with the importDatabase ops API (or mongorestore with its default flags; exclude the admin and config namespaces). Recreate tenants with createDatabaseTenant.
Keep the old volume until the migration is verified.

CLI

node cli.js server [options]

Options:
  --ephemeral
  --database-port PORT
  --ui-port PORT
  --storage-dir DIR
  --public-host HOST
  --root-username USER
  --root-password PASS
  --admin-password PASS
  --disable-auth

Endpoints

Served on the UI port:

GET /livez liveness
GET /readyz readiness (200 once the engine accepts connections and the configured root credentials authenticate; 503 with status: "starting" before, or status: "misconfigured" and a reason)
GET /healthz JSON health details
GET /metrics Prometheus-style metrics
POST /typedrequest authenticated management API

The image's Docker HEALTHCHECK probes /readyz inside the container, so the UI port does not need to be published.

Testing

pnpm run build
pnpm test

Docker smoke test (builds the image, checks its user, entrypoint, command and health check, connects with the MongoDB driver, stops it with SIGTERM, restarts on the same volume). Containers run with --cpus=2 --memory=2g; everything the test creates is removed:

pnpm run test:docker

Upgrade check (also pulls the published 2.0.0 image, writes data with it and reads it back with the new image on the same volume):

pnpm run test:docker-upgrade

Set DBST_DOCKER_PLATFORM=linux/arm64 to build and run either check for another platform (emulated when it is not the host's).

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.