Docker Installation

Run NexaDB in an isolated container on any platform. Universal solution for macOS, Linux, and Windows.

Quick Start

Get NexaDB running in seconds with a single Docker command:

Terminal
docker run -d \
  --name nexadb \
  -p 6969:6969 \
  -p 6970:6970 \
  -p 9999:9999 \
  -v nexadb-data:/app/nexadb_data \
  --restart unless-stopped \
  krishcdbry/nexadb:latest
✓ Binary Protocol on port 6970
✓ JSON REST API on port 6969
✓ Admin Web UI on port 9999
✓ Data persisted in Docker volume

Prerequisites

Docker Engine

  • • Docker Engine 20.10+
  • • Docker Compose 2.0+ (optional)
  • • 2GB free disk space
  • • 4GB RAM (8GB+ recommended)

Installation Methods

Method 1: Docker Run (Recommended)

Step 1: Pull the Image

docker pull krishcdbry/nexadb:latest

Downloads the latest NexaDB Docker image (~200MB compressed).

Step 2: Run the Container

docker run -d \
  --name nexadb \
  -p 6969:6969 -p 6970:6970 -p 9999:9999 \
  -v nexadb-data:/app/nexadb_data \
  --restart unless-stopped \
  krishcdbry/nexadb:latest

Command breakdown:

  • -d - Run in detached mode (background)
  • --name nexadb - Container name
  • -p 6969:6969 - JSON REST API port
  • -p 6970:6970 - Binary protocol port
  • -p 9999:9999 - Admin UI port
  • -v nexadb-data:/app/nexadb_data - Persistent data volume
  • --restart unless-stopped - Auto-restart on reboot

Step 3: Verify It's Running

docker ps | grep nexadb

You should see the nexadb container with status "Up".

Method 2: Docker Compose (Production)

Step 1: Create docker-compose.yml

version: '3.8'

services:
  nexadb:
    image: krishcdbry/nexadb:latest
    container_name: nexadb
    ports:
      - "6969:6969"  # JSON REST API
      - "6970:6970"  # Binary Protocol
      - "9999:9999"  # Admin Web UI
    volumes:
      - nexadb-data:/app/nexadb_data
    restart: unless-stopped
    environment:
      - NEXADB_HOST=0.0.0.0
      - NEXADB_PORT=6969
      - BINARY_PORT=6970
      - ADMIN_PORT=9999
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6969/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  nexadb-data:
    driver: local

Step 2: Start the Stack

docker-compose up -d

Starts NexaDB in the background with health checks and auto-restart.

Step 3: Check Status

docker-compose ps

Multi-Architecture Support

NexaDB Docker images support both x86_64 and ARM64 architectures. Docker automatically selects the right image for your system.

x86_64 (Intel/AMD)

  • ✓ Intel Core processors
  • ✓ AMD Ryzen processors
  • ✓ Most cloud servers
  • ✓ Traditional desktops/laptops

ARM64 (aarch64)

  • ✓ Apple Silicon (M1/M2/M3)
  • ✓ Raspberry Pi 4/5
  • ✓ AWS Graviton
  • ✓ Oracle Cloud ARM

Using nexa CLI with Docker

Access the interactive terminal inside your Docker container:

docker exec -it nexadb nexa -u root -p
$ docker exec -it nexadb nexa -u root -p
Password: ********

Connected to NexaDB v2.2.0 (Binary Protocol: localhost:6970)

nexa> collections
✓ Found 2 collection(s):
  [1] movies
  [2] users

nexa> use movies
✓ Switched to collection 'movies'

nexa> count
✓ Collection 'movies' has 1,234 document(s)

Container Management

Common Commands

Start container
docker start nexadb
Stop container
docker stop nexadb
Restart container
docker restart nexadb
View logs
docker logs -f nexadb

Data Management

List volumes
docker volume ls
Inspect volume
docker volume inspect nexadb-data
Backup data
docker cp nexadb:/app/nexadb_data ./backup
Remove container & data
docker rm -f nexadb && docker volume rm nexadb-data

Access the Admin Panel

Once the container is running, open your browser and visit:

http://localhost:9999/admin_panel/

Default Credentials

Username: root
Password: nexadb123

⚠️ Change the default password after first login!

Environment Variables

Customize NexaDB behavior with environment variables:

VariableDefaultDescription
NEXADB_HOST0.0.0.0Host to bind JSON API
NEXADB_PORT6969JSON REST API port
BINARY_PORT6970Binary protocol port
ADMIN_PORT9999Admin web UI port

Example with custom ports:

docker run -d --name nexadb \
  -e NEXADB_PORT=8080 \
  -e BINARY_PORT=8081 \
  -e ADMIN_PORT=8082 \
  -p 8080:8080 -p 8081:8081 -p 8082:8082 \
  krishcdbry/nexadb:latest

Troubleshooting

Container Won't Start

Check the logs for errors:

docker logs nexadb

Common issues: port conflicts, insufficient permissions, missing dependencies.

Port Already in Use

Find what's using the port:

lsof -i :6969

Either stop the conflicting service or change NexaDB ports using environment variables.

Data Not Persisting

Ensure you're using a named volume:

docker volume inspect nexadb-data

Without -v flag, data is lost when container is removed.

Can't Access from Host

Verify port mappings are correct (-p flag) and firewall isn't blocking connections.

Production Best Practices

Security

  • ✓ Change default admin password immediately
  • ✓ Use Docker secrets for sensitive data
  • ✓ Run behind a reverse proxy (nginx/traefik)
  • ✓ Enable TLS/SSL for production
  • ✓ Limit port exposure with firewall rules

Performance

  • ✓ Use named volumes for better I/O
  • ✓ Set resource limits (--memory, --cpus)
  • ✓ Enable health checks for monitoring
  • ✓ Use Docker Compose for multi-service setups
  • ✓ Regular backups of data volumes

Next Steps

Now that NexaDB is running in Docker, explore these resources: