Docker and Docker Compose

This guide covers how to run FalkorDB using Docker and Docker Compose, providing flexible deployment options for both development and production environments.

Docker Images

FalkorDB provides two main Docker images:

1. `falkordb/falkordb`

Includes: FalkorDB server + FalkorDB Browser
Use case: Development, quick start, interactive exploration
Ports:
- 6379 - Redis/FalkorDB server
- 3000 - FalkorDB Browser UI

2. `falkordb/falkordb-server`

Includes: FalkorDB server only
Use case: Production deployments, lighter footprint
Ports:
- 6379 - Redis/FalkorDB server

3. `falkordb/falkordb-browser`

Includes: FalkorDB Browser UI only
Use case: Running browser separately from the server, custom deployments
Ports:
- 3000 - FalkorDB Browser UI
Configuration: Requires FALKORDB_URL environment variable to connect to a FalkorDB server

Quick Start with Docker

Running with Browser (Development)

docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

Access the browser at http://localhost:3000

Running Server Only (Production)

docker run -p 6379:6379 -it --rm falkordb/falkordb-server:latest

Running with Authentication

docker run -p 6379:6379 -p 3000:3000 -it \
  -e REDIS_ARGS="--requirepass yourpassword" \
  --rm falkordb/falkordb:latest

Running with Custom Configuration

docker run -p 6379:6379 -p 3000:3000 -it \
  -e REDIS_ARGS="--requirepass yourpassword" \
  -e FALKORDB_ARGS="THREAD_COUNT 4 TIMEOUT 5000" \
  --rm falkordb/falkordb:latest

Using Docker Compose

Docker Compose provides a more flexible and maintainable way to run FalkorDB, especially when you need to configure multiple services or manage complex setups.

Quick Start: You can download a ready-to-use docker-compose.yml file from the FalkorDB repository.

Basic Docker Compose Setup

Create a docker-compose.yml file:

version: '3.8'

services:
  falkordb:
    image: falkordb/falkordb:latest
    container_name: falkordb
    ports:
      - "6379:6379"
      - "3000:3000"
    environment:
      - REDIS_ARGS=--requirepass falkordb
      - FALKORDB_ARGS=THREAD_COUNT 4
    restart: unless-stopped

Start FalkorDB:

docker-compose up -d

Stop FalkorDB:

docker-compose down

Production Setup with Persistence

For production environments, use the server-only image with data persistence:

version: '3.8'

services:
  falkordb:
    image: falkordb/falkordb-server:latest
    container_name: falkordb-server
    ports:
      - "6379:6379"
    environment:
      - REDIS_ARGS=--requirepass ${FALKORDB_PASSWORD:-falkordb} --appendonly yes
      - FALKORDB_ARGS=THREAD_COUNT 8 TIMEOUT_MAX 30000
    volumes:
      - falkordb_data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  falkordb_data:
    driver: local

Start with custom password:

FALKORDB_PASSWORD=your-secure-password docker-compose up -d

Separate Server and Browser Setup

Run FalkorDB server and browser as separate containers:

version: '3.8'

services:
  falkordb-server:
    image: falkordb/falkordb-server:latest
    container_name: falkordb-server
    ports:
      - "6379:6379"
    environment:
      - REDIS_ARGS=--requirepass falkordb
      - FALKORDB_ARGS=THREAD_COUNT 4
    volumes:
      - falkordb_data:/data
    restart: unless-stopped
    networks:
      - falkordb-network

  falkordb-browser:
    image: falkordb/falkordb-browser:latest
    container_name: falkordb-browser
    ports:
      - "3000:3000"
    environment:
      - FALKORDB_URL=redis://falkordb-server:6379
      - FALKORDB_PASSWORD=falkordb
    depends_on:
      - falkordb-server
    restart: unless-stopped
    networks:
      - falkordb-network

volumes:
  falkordb_data:
    driver: local

networks:
  falkordb-network:
    driver: bridge

Complete Production Setup

A comprehensive production-ready setup with all recommended configurations:

version: '3.8'

services:
  falkordb:
    image: falkordb/falkordb-server:latest
    container_name: falkordb-production
    ports:
      - "6379:6379"
    environment:
      # Redis Configuration
      - REDIS_ARGS=--requirepass ${FALKORDB_PASSWORD:-changeme} --appendonly yes --appendfsync everysec --maxmemory 2gb --maxmemory-policy allkeys-lru
      # FalkorDB Configuration
      - FALKORDB_ARGS=THREAD_COUNT 8 CACHE_SIZE 50 TIMEOUT_MAX 60000 TIMEOUT_DEFAULT 30000 QUERY_MEM_CAPACITY 104857600
    volumes:
      - falkordb_data:/data
      - ./falkordb-config:/etc/falkordb
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "$${FALKORDB_PASSWORD:-changeme}", "ping"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    networks:
      - falkordb-network
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  falkordb_data:
    driver: local

networks:
  falkordb-network:
    driver: bridge

Docker Compose Commands

Common Docker Compose commands for managing FalkorDB:

# Start services in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f falkordb

# Stop services
docker-compose stop

# Stop and remove containers
docker-compose down

# Stop and remove containers with volumes (WARNING: deletes data)
docker-compose down -v

# Restart services
docker-compose restart

# Check service status
docker-compose ps

# Execute commands in running container
docker-compose exec falkordb redis-cli

Environment Variables

REDIS_ARGS

Pass arguments directly to the Redis server:

environment:
  - REDIS_ARGS=--requirepass mypassword --maxmemory 1gb --appendonly yes

Common Redis arguments:

--requirepass <password> - Set authentication password
--appendonly yes - Enable AOF persistence
--appendfsync everysec - AOF sync frequency
--maxmemory <bytes> - Maximum memory limit
--maxmemory-policy <policy> - Eviction policy (e.g., allkeys-lru)

FALKORDB_ARGS

Pass configuration to FalkorDB module:

environment:
  - FALKORDB_ARGS=THREAD_COUNT 4 CACHE_SIZE 25 TIMEOUT_MAX 10000

See the Configuration page for all available FalkorDB parameters.

Data Persistence

Using Named Volumes

Named volumes are the recommended approach for data persistence:

services:
  falkordb:
    image: falkordb/falkordb-server:latest
    volumes:
      - falkordb_data:/data

volumes:
  falkordb_data:

Using Bind Mounts

For specific host directory mapping:

services:
  falkordb:
    image: falkordb/falkordb-server:latest
    volumes:
      - ./falkordb-data:/data

Create the directory first:

mkdir -p ./falkordb-data

Health Checks

Add health checks to ensure FalkorDB is running properly:

healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

With authentication:

healthcheck:
  test: ["CMD", "redis-cli", "-a", "yourpassword", "ping"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Networking

Custom Networks

Create isolated networks for better security:

networks:
  falkordb-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.25.0.0/16

Expose vs Ports

Use expose for internal communication and ports for external access:

services:
  falkordb:
    image: falkordb/falkordb-server:latest
    expose:
      - "6379"  # Only accessible within Docker network
    # Or use ports for external access:
    # ports:
    #   - "6379:6379"

Best Practices

Use Environment Variables: Store sensitive information like passwords in .env files or environment variables: Create a .env file:

FALKORDB_PASSWORD=your-secure-password
FALKORDB_THREADS=8

Reference in docker-compose.yml:

environment:
  - REDIS_ARGS=--requirepass ${FALKORDB_PASSWORD}
  - FALKORDB_ARGS=THREAD_COUNT ${FALKORDB_THREADS}

Enable Persistence: Always use volumes for production data:
volumes: - falkordb_data:/data

Set Resource Limits: Prevent resource exhaustion:

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G
    reservations:
      cpus: '2'
      memory: 4G

Use Health Checks: Ensure automatic recovery:

healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 30s
  timeout: 10s
  retries: 3

Configure Logging: Manage log file sizes:

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Separate Concerns: Use different images for different purposes:
- Development: falkordb/falkordb (with browser)
- Production: falkordb/falkordb-server (server only)
Use Specific Tags: Pin to specific versions for stability:
image: falkordb/falkordb-server:4.0.0

Troubleshooting

Check Container Logs

docker-compose logs falkordb

Check Container Status

docker-compose ps

Test Connection

docker-compose exec falkordb redis-cli ping

Access Redis CLI

docker-compose exec falkordb redis-cli

View Running Processes

docker-compose top

Inspect Configuration

docker-compose config

Next Steps

Learn about Persistence for data durability
Set up Replication for high availability
Configure a Cluster for scalability
Review Configuration options
Deploy to Kubernetes for orchestration

Frequently Asked Questions

What is the difference between falkordb/falkordb and falkordb/falkordb-server images?

The falkordb/falkordb image includes both the FalkorDB server and the Browser UI (ports 6379 and 3000). The falkordb/falkordb-server image includes only the server (port 6379), making it lighter for production use.

How do I set a password for FalkorDB in Docker?

Pass --requirepass <password> via the REDIS_ARGS environment variable: -e REDIS_ARGS='--requirepass mypassword'. For Docker Compose, add it to the environment section.

How do I configure FalkorDB module parameters like thread count?

Use the FALKORDB_ARGS environment variable: -e FALKORDB_ARGS='THREAD_COUNT 8 CACHE_SIZE 50 TIMEOUT_MAX 60000'. See the Configuration page for all available parameters.

Why is my data lost when I restart the container?

You need to mount a persistent volume. Use -v falkordb_data:/var/lib/falkordb/data to attach a Docker volume to the default data directory, and enable AOF for durability.

How do I check if FalkorDB is healthy in Docker Compose?

Add a healthcheck using redis-cli ping: test: ['CMD', 'redis-cli', 'ping']. With authentication, include -a yourpassword in the test command.

​Docker Images

​1. falkordb/falkordb

​2. falkordb/falkordb-server

​3. falkordb/falkordb-browser

​Quick Start with Docker

​Running with Browser (Development)

​Running Server Only (Production)

​Running with Authentication

​Running with Custom Configuration

​Using Docker Compose

​Basic Docker Compose Setup

​Production Setup with Persistence

​Separate Server and Browser Setup

​Complete Production Setup

​Docker Compose Commands

​Environment Variables

​REDIS_ARGS

​FALKORDB_ARGS

​Data Persistence

​Using Named Volumes

​Using Bind Mounts

​Health Checks

​Networking

​Custom Networks

​Expose vs Ports

​Best Practices

​Troubleshooting

​Check Container Logs

​Check Container Status

​Test Connection

​Access Redis CLI

​View Running Processes

​Inspect Configuration

​Next Steps

​Frequently Asked Questions