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 | Maintenance workers per node (trigger dispatch, embeddings, materialized views) |
| SOLI_WEBHOOK_SECRET | unset | Default HMAC-SHA256 key used to sign outbound trigger webhooks via X-Webhook-Signature. Per-target webhook_secret wins; if both are unset the signature header is omitted. See Triggers. |
| 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). |
| SOLIDB_API_RATE_LIMIT | 600 | Requests allowed per client IP per window across the whole API. Over the limit the server answers 429 with Retry-After. Set to 0 to disable — useful for load tests and CI, which drive far more than 10 req/s from one address. Internal cluster traffic and CORS preflights are always exempt. |
| SOLIDB_API_RATE_WINDOW_SECS | 60 | Length of the rate-limit window in seconds. |
| SOLIDB_TRUST_PROXY_HEADERS | false | Key rate limits on X-Forwarded-For / X-Real-IP instead of the socket peer. Set this only behind a proxy that overwrites those headers — otherwise any client can spoof its own identity and evade the limiter. |
| SOLIDB_TLS_REQUIRE | false | With --tls-cert set, drop any connection on the multiplexed port that does not offer TLS. Leave it off on a node that serves native driver clients or has cluster peers — neither speaks TLS. See Transport Security. |
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 maintenance workers per node. Each worker dispatches fired triggers and refreshes embeddings and materialized views. |
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
HTTPS (TLS certificates)
TLS is configured with command-line flags rather than environment variables, and both are required together — one without the other refuses to start rather than silently listening in plaintext.
./solidb --port 6745 --data-dir ./data --tls-cert fullchain.pem --tls-key privkey.pem
On a multiplexed port the listener only handshakes with clients that offer TLS, so plaintext driver and cluster peers keep working alongside HTTPS clients. See Transport Security.
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"