Getting Started
Get up and running with SoliDB in minutes. Learn the basics of installation, connecting, and running your first queries.
Installation
1 Quick Install (Recommended)
curl -sSL https://raw.githubusercontent.com/solisoft/solidb/main/install.sh | sh
Installs the latest pre-built binary to ~/.local/bin. Use --system flag for system-wide install to /usr/local/bin.
2 Using Cargo
cargo install solidb
3 From Source
4 Using Docker
Docker Compose: For production deployments, use docker-compose.yml from the repository.
Docker Deployment
SoliDB publishes official Docker images to the GitHub Container Registry at
ghcr.io/solisoft/solidb for easy deployment in containerized environments.
Images are tagged :latest and per release (e.g. :v0.31.0).
If the package is private, run docker login ghcr.io with a token that has read:packages first.
Docker Compose (Recommended)
version: '3.8'
services:
solidb:
image: ghcr.io/solisoft/solidb:latest
ports:
- "6745:6745"
volumes:
- solidb-data:/data
environment:
- SOLIDB_PORT=6745
- RUST_LOG=solidb=info
restart: unless-stopped
volumes:
solidb-data:
Environment Variables
| Variable | Default | Description |
|---|---|---|
| SOLIDB_PORT | 6745 | HTTP server port |
| SOLIDB_DATA_DIR | /data | Data directory path |
| SOLIDB_LOG_LEVEL | info | Log verbosity level |
| SOLIDB_ADMIN_PASSWORD | auto-generated | Admin user password |
| JWT_SECRET | auto-generated | Secret for signing JWT tokens |
| QUEUE_WORKERS | 4 | Background job workers per node |
| SOLI_WEBHOOK_SECRET | unset | Default HMAC-SHA256 key used to sign outbound webhook jobs & triggers via X-Webhook-Signature. Per-target webhook_secret wins; if both are unset the signature header is omitted. See Queues → Configuration. |
| SOLI_JOBS_SECRET | unset | Legacy fallback used only when SOLI_WEBHOOK_SECRET is unset. Prefer the latter for new setups. |
| SOLIDB_LUA_POOL_SIZE | CPU cores | Number of Lua VM pool states |
| SOLIDB_LUA_FAST_MODE | false | Skip Lua global reset between requests |
| SOLIDB_CLUSTER_SCHEME | http | Protocol for cluster communication |
Build Image Locally
Health Check: The Docker image includes a built-in health check at
/_api/health. Container orchestrators can use this to monitor instance health.
Docker Cluster Setup
For high availability, use the cluster compose file to run multiple nodes.
Kubernetes Deployment
Deploy SoliDB on Kubernetes using the provided manifests for single-node or cluster deployments.
Single Node Deployment
# Apply manifests kubectl apply -f k8s/namespace.yaml kubectl apply -f k8s/configmap.yaml kubectl apply -f k8s/secret.yaml kubectl apply -f k8s/single/ # Verify deployment kubectl -n solidb get pods kubectl -n solidb port-forward svc/solidb 6745:6745
Cluster Deployment (StatefulSet)
Uses StatefulSet with headless service for automatic peer discovery via DNS.
# Generate keyfile for cluster auth openssl rand -hex 32 > keyfile.txt # Create secret with keyfile kubectl create namespace solidb kubectl create secret generic solidb-secret \ -n solidb --from-file=keyfile=keyfile.txt # Deploy 3-node cluster kubectl apply -f k8s/configmap.yaml kubectl apply -f k8s/cluster/ # Watch pods come up kubectl -n solidb get pods -w
Cluster Architecture
Included Features
- • Liveness & readiness probes
- • Prometheus annotations
- • Pod anti-affinity
- • PodDisruptionBudget
Scaling
kubectl -n solidb scale statefulset solidb --replicas=5
Basic Usage
Start the server and interact with the HTTP API using curl or your preferred client.
1. Start Server
Check the terminal output for the generated admin password. You will need it to authenticate.
2. Create Database
Creates a new database namespace called "mydb".
3. Insert Document
-d '{"name": "Alice", "age": 30, "city": "Paris"}'
Inserts a JSON document into the "users" collection within "mydb".
Admin UI
SoliDB includes a web-based Admin UI for managing databases, collections, documents, and running queries.
Launch Admin UI
The Admin UI will be available at http://localhost:8080
Note: The Admin UI requires SoliDB to be running on port 6745 (or accessible at a configured URL). Configure the connection in the UI login screen.
Configuration
SoliDB can be configured using command-line arguments, environment
variables, or an .env file
located in the same directory as the executable.
Security
| Variable | Default | Description |
|---|---|---|
| SOLIDB_ADMIN_PASSWORD | auto-generated | Override the default admin user password. If not set, a random password is generated and printed at startup. |
| JWT_SECRET | auto-generated | Secret key for signing JSON Web Tokens. 32+ characters recommended. If not set, a random secret is generated (warning logged). |
Performance Tuning
| Variable | Default | Description |
|---|---|---|
| SOLIDB_LUA_POOL_SIZE | CPU cores (min 4) | Number of pre-initialized Lua VM states in the pool. Each state handles one script at a time. Increase beyond CPU core count (e.g. 32 or 64) to reduce contention under high concurrency. |
| SOLIDB_LUA_FAST_MODE | false | Set to 1 or true to skip Lua global reset between requests. Provides maximum throughput for stateless scripts. Do not enable if scripts rely on clean global state. |
| QUEUE_WORKERS | 4 | Number of concurrent background job workers per node. Each worker polls for queued jobs and cron tasks. |
Cluster & Networking
| Variable | Default | Description |
|---|---|---|
| SOLIDB_CLUSTER_SCHEME | http | Protocol for inter-node communication (http or https). Used for replication, sharding, blob sync, and scatter-gather queries. |
CLI (solidb scripts)
| Variable | Default | Description |
|---|---|---|
| SOLIDB_API_KEY | none | API key for CLI authentication. Overrides the value in .solidb.json config file. |
| SOLIDB_HOST | none | Server hostname for CLI commands. Overrides config file. |
| SOLIDB_PORT | none | Server port for CLI commands. Overrides config file. |
| SOLIDB_DATABASE | none | Target database for CLI commands. Overrides config file. |
| SOLIDB_SERVICE | default | Default service name for script API routing. |
Example .env
Cluster Authentication (Keyfile)
For cluster mode, inter-node authentication uses a shared keyfile instead of environment variables. All nodes must use the same keyfile content.
openssl rand -hex 32 > solidb.key
./solidb --keyfile solidb.key --cluster-peers "node2:6746"