Skip to content

Installation

This guide covers all the different ways to install and run DBX.

Prerequisites

  • Redis Server: A running Redis instance (version 6.0 or higher)
  • Rust: For building from source (version 1.70 or higher)
  • Docker: For containerized deployment (optional)
  • Node.js: For TypeScript SDK (version 16 or higher)

Quick Start

Docker (Recommended)

The fastest way to get started:

# Run with Docker
docker run -d --name dbx -p 3000:3000 \
  -e REDIS_URL=redis://localhost:6379 \
  effortlesslabs/0dbx_redis:latest
 
# Or use Docker Compose
docker-compose up -d

Installation Methods

Docker Installation

Pull and Run

# Pull the latest image
docker pull effortlesslabs/0dbx_redis:latest
 
# Run with default configuration
docker run -p 3000:3000 effortlesslabs/0dbx_redis:latest

Custom Configuration

# Run with custom Redis URL
docker run -p 3000:3000 -e REDIS_URL=redis://your-redis-server:6379 effortlesslabs/0dbx_redis:latest
 
# Run with custom port
docker run -p 8080:3000 effortlesslabs/0dbx_redis:latest
 
# Run with custom log level
docker run -p 3000:3000 -e LOG_LEVEL=DEBUG effortlesslabs/0dbx_redis:latest

Docker Compose

Create a docker-compose.yml file:

version: "3.8"
services:
  dbx:
    image: effortlesslabs/0dbx_redis:latest
    ports:
      - "3000:3000"
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Then run:

docker-compose up -d

Binary Installation

Download Pre-built Binary

# Download the latest release
curl -L https://github.com/effortlesslabs/dbx/releases/latest/download/dbx-x86_64-unknown-linux-gnu.tar.gz | tar xz
 
# Make executable
chmod +x dbx-redis-api
 
# Run
./dbx-redis-api --redis-url redis://localhost:6379

Platform-Specific Binaries

# Linux (x86_64)
curl -L https://github.com/effortlesslabs/dbx/releases/latest/download/dbx-x86_64-unknown-linux-gnu.tar.gz | tar xz
 
# macOS (x86_64)
curl -L https://github.com/effortlesslabs/dbx/releases/latest/download/dbx-x86_64-apple-darwin.tar.gz | tar xz
 
# macOS (ARM64)
curl -L https://github.com/effortlesslabs/dbx/releases/latest/download/dbx-aarch64-apple-darwin.tar.gz | tar xz
 
# Windows (x86_64)
curl -L https://github.com/effortlesslabs/dbx/releases/latest/download/dbx-x86_64-pc-windows-msvc.zip

Build from Source

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
 
# Install build dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev
 
# Install build dependencies (macOS)
brew install pkg-config openssl

Clone and Build

# Clone the repository
git clone https://github.com/effortlesslabs/dbx.git
cd dbx
 
# Build the project
cargo build --release
 
# Run the server
cargo run --bin dbx-redis-api -- --redis-url redis://localhost:6379

Development Build

# Build for development
cargo build
 
# Run with debug logging
RUST_LOG=debug cargo run --bin dbx-redis-api -- --redis-url redis://localhost:6379

Package Manager Installation

Using Cargo

# Install from crates.io (if published)
cargo install dbx-redis-api
 
# Run
dbx-redis-api --redis-url redis://localhost:6379

TypeScript SDK Installation

NPM

npm install @0dbx/redis

Yarn

yarn add @0dbx/redis

PNPM

pnpm add @0dbx/redis

Usage

import { DbxRedisClient } from "@0dbx/redis";
 
const client = new DbxRedisClient("http://localhost:3000");
 
// Test connection
const value = await client.string.get("test-key");
console.log("Connected to DBX:", value);

Platform-Specific Instructions

Linux

Ubuntu/Debian

# Install dependencies
sudo apt-get update
sudo apt-get install -y curl build-essential pkg-config libssl-dev
 
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
 
# Clone and build
git clone https://github.com/effortlesslabs/dbx.git
cd dbx
cargo build --release

CentOS/RHEL

# Install dependencies
sudo yum groupinstall "Development Tools"
sudo yum install pkg-config openssl-devel
 
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
 
# Clone and build
git clone https://github.com/effortlesslabs/dbx.git
cd dbx
cargo build --release

macOS

Using Homebrew

# Install dependencies
brew install pkg-config openssl
 
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
 
# Clone and build
git clone https://github.com/effortlesslabs/dbx.git
cd dbx
cargo build --release

Using MacPorts

# Install dependencies
sudo port install pkgconfig openssl3
 
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
 
# Clone and build
git clone https://github.com/effortlesslabs/dbx.git
cd dbx
cargo build --release

Windows

Using Chocolatey

# Install dependencies
choco install rust
 
# Clone and build
git clone https://github.com/effortlesslabs/dbx.git
cd dbx
cargo build --release

Using MSYS2

# Install MSYS2 and dependencies
pacman -S mingw-w64-x86_64-rust mingw-w64-x86_64-pkg-config mingw-w64-x86_64-openssl
 
# Clone and build
git clone https://github.com/effortlesslabs/dbx.git
cd dbx
cargo build --release

Cloud Deployment

Railway

# Create railway.toml
cat > railway.toml << EOF
[build]
builder = "dockerfile"
 
[deploy]
startCommand = "./dbx-redis-api"
healthcheckPath = "/redis/admin/health"
healthcheckTimeout = 300
restartPolicyType = "on_failure"
EOF
 
# Deploy
railway up

Heroku

# Create Procfile
echo "web: ./dbx-redis-api" > Procfile
 
# Create app.json
cat > app.json << EOF
{
  "name": "dbx-api",
  "description": "DBX Redis API Gateway",
  "repository": "https://github.com/effortlesslabs/dbx",
  "env": {
    "REDIS_URL": {
      "description": "Redis connection URL",
      "required": true
    }
  }
}
EOF
 
# Deploy
heroku create
heroku config:set REDIS_URL=your-redis-url
git push heroku main

DigitalOcean App Platform

# .do/app.yaml
name: dbx-api
services:
  - name: dbx
    source_dir: /
    github:
      repo: effortlesslabs/dbx
      branch: main
    run_command: ./dbx-redis-api
    environment_slug: rust
    envs:
      - key: REDIS_URL
        value: ${redis.DATABASE_URL}

AWS ECS

# task-definition.json
{
  "family": "dbx-api",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "containerDefinitions":
    [
      {
        "name": "dbx-api",
        "image": "effortlesslabs/0dbx_redis:latest",
        "portMappings": [{ "containerPort": 3000, "protocol": "tcp" }],
        "environment": [{ "name": "REDIS_URL", "value": "redis://your-redis-endpoint:6379" }],
        "healthCheck":
          {
            "command": ["CMD-SHELL", "curl -f http://localhost:3000/redis/admin/health || exit 1"],
            "interval": 30,
            "timeout": 5,
            "retries": 3,
          },
      },
    ],
}

Verification

Test Installation

# Test the server
curl http://localhost:3000/redis/admin/health
 
# Expected response
{"status":"ok","timestamp":"2024-01-15T10:30:00Z"}

Test TypeScript SDK

import { DbxRedisClient } from "@0dbx/redis";
 
async function testInstallation() {
  const client = new DbxRedisClient("http://localhost:3000");
 
  try {
    // Test string operations
    await client.string.set("test-key", "hello world");
    const value = await client.string.get("test-key");
    console.log("✅ String operations working:", value);
 
    // Test set operations
    await client.set.addMember("test-set", "member1");
    const members = await client.set.getMembers("test-set");
    console.log("✅ Set operations working:", members);
 
    console.log("🎉 Installation successful!");
  } catch (error) {
    console.error("❌ Installation failed:", error);
  }
}
 
testInstallation();

Troubleshooting

Common Issues

Build Errors

# SSL/TLS errors
export OPENSSL_DIR=/usr/local/opt/openssl
export OPENSSL_LIB_DIR=/usr/local/opt/openssl/lib
 
# Linker errors
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

Runtime Errors

# Redis connection failed
redis-cli -u redis://localhost:6379 ping
 
# Port already in use
lsof -i :3000
netstat -tulpn | grep :3000
 
# Permission denied
sudo chmod +x dbx-redis-api

Docker Issues

# Container won't start
docker logs dbx
 
# Port conflicts
docker run -p 8080:3000 effortlesslabs/0dbx_redis:latest
 
# Volume mounts
docker run -v $(pwd)/data:/app/data effortlesslabs/0dbx_redis:latest

Getting Help

Next Steps