Run Crossbar with Docker Compose
Overview
Crossbar can be run pretty easily with Docker. The instructions below will walk you through running Crossbar in Docker containers using Docker Compose.
For Swagger documentation, see: https://crossbar.switchboard.xyz/docs
Crossbar Rust Implementation
The current version of Crossbar is implemented in Rust and includes built-in simulation capabilities, eliminating the need for a separate Task Runner Simulator service. This provides better performance and simplified deployment.
Prerequisites
Before running crossbar, ensure you have the following
Docker and Docker Compose installed on your machine.
A custom Solana RPC for improved performance (optional - strongly recommended)
Pinata or another IPFS node for job storage (optional)
Step 1: Set Up Your Project Directory
Create a Project Directory: Create a directory for your project. This directory will contain all the necessary files for your Docker container deployment.
mkdir my-crossbar-project cd my-crossbar-project
Step 2: Create the docker-compose.yml
File
docker-compose.yml
FileCreate a
docker-compose.yml
File: In your project directory, create a file nameddocker-compose.yml
. This file will define the Docker services and environment variables.
version: '3.8'
services:
crossbar:
image: switchboardlabs/crossbar:stable
ports:
- "8080:8080" # HTTP API
- "8081:8081" # WebSocket
environment:
# === Core Configuration ===
PORT: ${PORT:-8080}
WS_PORT: ${WS_PORT:-8081}
# === Blockchain RPCs (Optional - Recommended) ===
SOLANA_MAINNET_RPC_URL: ${SOLANA_MAINNET_RPC_URL:-"https://api.mainnet-beta.solana.com"}
SOLANA_DEVNET_RPC_URL: ${SOLANA_DEVNET_RPC_URL:-"https://api.devnet.solana.com"}
# === IPFS Configuration (Optional) ===
IPFS_GATEWAY_URL: ${IPFS_GATEWAY_URL:-"https://ipfs.io"}
PINATA_JWT_KEY: ${PINATA_JWT_KEY}
PINATA_GATEWAY_KEY: ${PINATA_GATEWAY_KEY}
# === Performance (Optional) ===
BROADCAST_WORKER_THREADS: ${BROADCAST_WORKER_THREADS:-32}
RUST_LOG: ${RUST_LOG:-"info"}
Step 3: Create the .env
File
.env
FileCreate a
.env
File: In the same directory, create a.env
file to store your environment variables. This file is read bydocker compose
and will override the default values in the compose file if specified.
# .env file
# All environment variables are optional and have sensible defaults
# Recommended for better performance
SOLANA_MAINNET_RPC_URL="your-mainnet-rpc-url"
SOLANA_DEVNET_RPC_URL="your-devnet-rpc-url"
# Optional IPFS configuration
# PINATA_JWT_KEY="your-pinata-jwt-key"
# PINATA_GATEWAY_KEY="your-pinata-gateway-key"
# IPFS_GATEWAY_URL="https://ipfs.io"
Step 4: Build and Run the Docker Container
Build and Run the Docker Container: Navigate to your project directory and run the following command to start your Docker container:
docker-compose up -d
This command will start the container in detached mode. The -d
flag stands for "detached," meaning the container runs in the background.
Step 5: Verify the Deployment
Verify the Deployment: Once the container is running, you can verify that the service is up and running by accessing it at
http://localhost:8080
. You can also check the status of the container by running:
docker-compose ps
This command will show the status of the running services.
Step 6: Stopping and Restarting the Docker Container
Stop the Docker Container: To stop the container, run:
docker-compose down
This command will stop and remove the containers defined in your docker-compose.yml
file.
Restart the Docker Container: To restart the container, run:
docker-compose up -d
Additional Tips
Logs: To view the logs of the running container, use the following command:
docker-compose logs -f
Updating Environment Variables: If you need to update the environment variables, edit the
.env
file and restart the container:
docker-compose down docker-compose up -d
Environment Variables Reference
Core Server Configuration
PORT
Optional
8080
HTTP server port
WS_PORT
Optional
8081
WebSocket server port
DISABLE_API
Optional
false
Set to "true" to disable HTTP API
Blockchain RPC Configuration
SOLANA_MAINNET_RPC_URL
Optional
https://api.mainnet-beta.solana.com
Solana mainnet RPC endpoint
SOLANA_DEVNET_RPC_URL
Optional
https://api.devnet.solana.com
Solana devnet RPC endpoint
IPFS Configuration
IPFS_GATEWAY_URL
Optional
https://ipfs.io
IPFS gateway for fetching data
PINATA_JWT_KEY
Optional
-
Pinata JWT key for storage
PINATA_GATEWAY_KEY
Optional
-
Pinata gateway key
KUBO_URL
Optional
-
Local Kubo IPFS node URL
Database Configuration (Optional)
DATABASE_URL
Optional
-
PostgreSQL connection string
PGUSER
Optional
-
PostgreSQL username
PGPASSWORD
Optional
-
PostgreSQL password
PGDATABASE
Optional
-
PostgreSQL database name
PGHOST
Optional
-
PostgreSQL host
PGPORT
Optional
-
PostgreSQL port
Performance & Caching
BROADCAST_WORKER_THREADS
Optional
32
Number of Tokio worker threads
SIMULATION_CACHE_TTL_SECONDS
Optional
3
Cache TTL for simulations
DISABLE_CACHE
Optional
false
Disable caching entirely
RATE_LIMIT
Optional
-
Rate limiting configuration
Development & Debugging
RUST_LOG
Optional
info
Log level (error, warn, info, debug, trace)
TOKIO_CONSOLE
Optional
false
Enable tokio console debugging
TOKIO_CONSOLE_PORT
Optional
6669
Port for tokio console
IS_LOCALHOST
Optional
false
Development mode flag
Testing it out:
Try the deployment out by navigating to (can take a few seconds the first run): http://localhost:8080/updates/evm/1115/4f0e020e3d6f65cf21adb7766d065f787293154964be259dddb56e848ff838a0
The equivalent result should look something like the output from the public node: https://crossbar.switchboard.xyz/updates/evm/1115/4f0e020e3d6f65cf21adb7766d065f787293154964be259dddb56e848ff838a0
Last updated