Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/brimblehq/rexec/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Docker Compose is the easiest way to run Rexec in production. This setup includes:
  • Rexec API Server - Main application server
  • PostgreSQL - User data and container metadata
  • Redis - Session management and caching
  • Persistent volumes - For recordings, SSH keys, and databases

​
Prerequisites

1

Install Docker

Ensure Docker Engine 20.10+ and Docker Compose V2 are installed:
docker --version
docker compose version
Install from https://docs.docker.com/engine/install/
2

Clone Repository

git clone https://github.com/brimblehq/rexec.git
cd rexec

​
Configuration

1

Create Environment File

Copy the example environment file and configure it:
cp .env.example .env
Edit .env with your configuration:
.env
# Security - REQUIRED
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
REXEC_ENCRYPTION_KEY=rexec-dev-key-do-not-use-in-prod
POSTGRES_PASSWORD=rexec_dev_password

# Server URLs
REXEC_APP_URL=http://localhost:8080
BASE_URL=http://localhost:8080

# Docker Configuration
DOCKER_HOST=unix:///var/run/docker.sock
VOLUME_PATH=/var/lib/rexec/volumes
Production Security: Always change JWT_SECRET, REXEC_ENCRYPTION_KEY, and POSTGRES_PASSWORD to secure random values before deploying to production.Generate secure keys:
openssl rand -base64 32
2

Remote Docker Configuration (Optional)

To connect to a remote Docker daemon instead of using the local Docker socket:
.env
# Remote Docker daemon
DOCKER_HOST=tcp://your-docker-host:2376
DOCKER_TLS_VERIFY=1
DOCKER_CA_CERT=/path/to/ca.pem
DOCKER_CLIENT_CERT=/path/to/cert.pem
DOCKER_CLIENT_KEY=/path/to/key.pem

​
Deployment

1

Start Services

Navigate to the Docker directory and start all services:
cd docker
docker compose up -d
This will:
  • Build the Rexec image from the Dockerfile
  • Start PostgreSQL and Redis containers
  • Start the Rexec API server
  • Create persistent volumes for data
2

Verify Deployment

Check that all services are running:
docker compose ps
You should see three services: rexec, postgres, and redis in the “Up” state.View logs:
docker compose logs -f rexec
3

Access Rexec

Open your browser to:
http://localhost:8080
Default credentials:
  • Username: admin
  • Password: admin
Change the default admin password immediately after first login in production environments.

​
Docker Compose Configuration

The docker-compose.yml file defines the complete stack:
docker/docker-compose.yml
version: "3.8"

services:
  # Rexec API (connects to remote Docker daemon)
  rexec:
    build:
      context: ../
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
      - "22:22" # SSH Gateway (optional, enable with SSH_GATEWAY_ENABLED=true)
    environment:
      - PORT=8080
      - JWT_SECRET=${JWT_SECRET:-rexec-dev-secret-change-me}
      - DATABASE_URL=postgres://rexec:${POSTGRES_PASSWORD:-rexec_dev_password}@postgres:5432/rexec?sslmode=disable
      - REDIS_URL=redis://redis:6379
      # Remote Docker daemon configuration
      - DOCKER_HOST=${DOCKER_HOST}
      - DOCKER_TLS_VERIFY=${DOCKER_TLS_VERIFY:-1}
      - SSH_GATEWAY_ENABLED=${SSH_GATEWAY_ENABLED:-false}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    volumes:
      - recordings-data:/app/recordings
      - ssh-keys:/app/.ssh
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=rexec
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-rexec_dev_password}
      - POSTGRES_DB=rexec
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  redis-data:
  postgres-data:
  recordings-data:
  ssh-keys:

​
Enabling SSH Gateway

Rexec includes an optional SSH gateway that allows SSH access to containers:
1

Enable SSH Gateway

Add to your .env file:
.env
SSH_GATEWAY_ENABLED=true
SSH_GATEWAY_HOST_KEY=/app/.ssh/host_key
2

Restart Services

docker compose restart rexec
The SSH gateway will now be available on port 22.

​
Managing the Deployment

​
View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f rexec

​
Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart rexec

​
Stop Services

# Stop (keeps data)
docker compose stop

# Stop and remove containers (keeps volumes)
docker compose down

# Stop and remove everything including volumes
docker compose down -v

​
Update Rexec

1

Pull Latest Code

git pull origin main
2

Rebuild and Restart

cd docker
docker compose up -d --build

​
Persistent Data

Docker Compose creates named volumes for persistent data:
  • postgres-data - User data, container metadata, audit logs
  • redis-data - Session data and cache
  • recordings-data - Terminal session recordings
  • ssh-keys - SSH host keys for the gateway
To backup volumes: 
# Backup PostgreSQL
docker compose exec postgres pg_dump -U rexec rexec > backup.sql

# Backup recordings
docker compose exec rexec tar czf - /app/recordings > recordings-backup.tar.gz

​
Troubleshooting

​
Health Check Failing

Check if the API is responding: 
curl http://localhost:8080/health
View detailed logs: 
docker compose logs rexec | tail -100

​
Database Connection Issues

Verify PostgreSQL is ready: 
docker compose exec postgres pg_isready -U rexec

​
Port Already in Use

Change the port mapping in docker-compose.yml: 
ports:
  - "8081:8080"  # Use port 8081 instead

​
Next Steps

Configuration

Learn about all environment variables and advanced configuration

Manual Setup

Deploy without Docker Compose

Build docs developers (and LLMs) love

Get started for freeTalk to us