Docker Deployment

Overview

Base Audit Bot includes production-ready Docker support with multi-stage builds, health checks, volume management, and log rotation.

Quick Start

Configure environment

cp .env.example .env
nano .env  # Add your API keys

Deploy with Docker Compose

docker-compose up -d

Verify deployment

docker-compose logs -f
curl http://localhost:5000/health

Dockerfile

The bot’s Dockerfile is optimized for production use:

FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Install git (required for cloning repos)
RUN apt-get update && apt-get install -y \
    git \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements first for better caching
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY *.py ./

# Create directories for data and logs
RUN mkdir -p /app/data /app/logs /app/temp_repos

# Set environment variables
ENV PYTHONUNBUFFERED=1
ENV DATABASE_PATH=/app/data/bot.db
ENV TEMP_DIR=/app/temp_repos

# Expose webhook port
EXPOSE 5000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:5000/health || exit 1

# Run the bot
CMD ["python", "bot.py"]

Dockerfile Features

Base image: Python 3.11 slim for smaller size
Git included: Required for cloning GitHub repositories
Layer caching: Dependencies installed before code for faster rebuilds
Health checks: Automatic container health monitoring
Unbuffered output: PYTHONUNBUFFERED=1 for real-time logs
Directory structure: Pre-created directories for data, logs, and temp files

Docker Compose

The docker-compose.yml provides a complete production setup:

version: '3.8'

services:
  audit-bot:
    build: .
    container_name: base-audit-bot
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      # Persist database and logs
      - ./data:/app/data
      - ./logs:/app/logs
      # Temporary repos (can be ephemeral)
      - bot-temp:/app/temp_repos
    environment:
      # Base Chain
      - BASE_RPC_URL=${BASE_RPC_URL:-https://mainnet.base.org}
      - BASESCAN_API_KEY=${BASESCAN_API_KEY}
      # Anthropic
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # Twitter
      - TWITTER_API_KEY=${TWITTER_API_KEY}
      - TWITTER_API_SECRET=${TWITTER_API_SECRET}
      - TWITTER_ACCESS_TOKEN=${TWITTER_ACCESS_TOKEN}
      - TWITTER_ACCESS_SECRET=${TWITTER_ACCESS_SECRET}
      - TWITTER_BEARER_TOKEN=${TWITTER_BEARER_TOKEN}
      # Webhook
      - WEBHOOK_SECRET=${WEBHOOK_SECRET}
      - WEBHOOK_PORT=5000
      # Bot settings
      - SCAN_INTERVAL_MINUTES=${SCAN_INTERVAL_MINUTES:-15}
      - BLOCKS_TO_SCAN=${BLOCKS_TO_SCAN:-100}
      - MIN_CONTRACT_SIZE=${MIN_CONTRACT_SIZE:-100}
      - LOG_LEVEL=${LOG_LEVEL:-INFO}
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  bot-temp:
    driver: local

Volume Management

Data Volume (./data:/app/data)

Purpose: Persistent SQLite database storageContains:

bot.db - SQLite database with contracts, audits, tweets, and monitored repos

Backup: Regular backups recommended

cp data/bot.db data/bot.db.backup

Logs Volume (./logs:/app/logs)

Purpose: Persistent application logsContains:

bot.log - Application logs with rotation

Rotation: Handled by Docker logging driver (10MB, 3 files)

Temp Repos Volume (bot-temp:/app/temp_repos)

Purpose: Temporary GitHub repository clonesType: Named Docker volume (ephemeral)Cleanup: Automatically cleaned by bot, can be manually cleared:

docker-compose down
docker volume rm base-audit-bot_bot-temp
docker-compose up -d

Data persistence: The data and logs volumes are bind mounts to the host filesystem. Ensure these directories exist and have proper permissions before starting.

Container Management

Starting and Stopping

# Start in background
docker-compose up -d

# Start with logs visible
docker-compose up

# Stop containers
docker-compose down

# Stop and remove volumes
docker-compose down -v

# Restart
docker-compose restart

# Restart specific service
docker-compose restart audit-bot

Viewing Logs

# Follow all logs
docker-compose logs -f

# Follow specific service
docker-compose logs -f audit-bot

# View last 100 lines
docker-compose logs --tail=100

# View logs with timestamps
docker-compose logs -t

Executing Commands

# Open shell in container
docker-compose exec audit-bot /bin/bash

# Run Python shell
docker-compose exec audit-bot python

# Check database
docker-compose exec audit-bot sqlite3 /app/data/bot.db "SELECT COUNT(*) FROM contracts"

# View environment variables
docker-compose exec audit-bot env

Health Checks

The container includes built-in health monitoring via Dockerfile:32:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:5000/health || exit 1

Health Check Configuration

Interval: Check every 30 seconds
Timeout: 10 seconds per check
Start period: Wait 5 seconds after container start
Retries: Mark unhealthy after 3 consecutive failures

Checking Health Status

# Check health status
docker-compose ps

# Detailed health information
docker inspect --format='{{json .State.Health}}' base-audit-bot | jq

# Manual health check
curl http://localhost:5000/health

Expected health response:

{
  "status": "healthy",
  "timestamp": "2026-03-03T12:00:00.000000"
}

Log Rotation

Docker Compose is configured with automatic log rotation via docker-compose.yml:44:

logging:
  driver: "json-file"
  options:
    max-size: "10m"    # Rotate when file reaches 10MB
    max-file: "3"      # Keep 3 rotated files

This configuration:

Limits each log file to 10MB
Keeps up to 3 files (30MB total)
Automatically rotates when size limit is reached

Building Custom Images

Build from Source

# Build with default tag
docker build -t base-audit-bot .

# Build with custom tag
docker build -t base-audit-bot:v1.0.0 .

# Build with no cache
docker build --no-cache -t base-audit-bot .

Multi-Platform Builds

# Build for multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 -t base-audit-bot:latest .

Environment Variables

Docker Compose supports environment variables in two ways:

Method 1: .env file (Recommended)

env_file:
  - .env

All variables from .env are automatically loaded.

Method 2: Direct environment section

environment:
  - BASE_RPC_URL=${BASE_RPC_URL:-https://mainnet.base.org}
  - BASESCAN_API_KEY=${BASESCAN_API_KEY}

Supports default values with ${VAR:-default} syntax.

The bot uses both methods: the environment section provides defaults and documentation, while env_file loads all variables from .env.

Production Deployment

Prerequisites Checklist

Install Docker and Docker Compose

# Verify installation
docker --version    # Should be 20.10+
docker-compose --version  # Should be 2.0+

Configure environment

Copy .env.example to .env
Fill in all required API keys
Set production log level (INFO or WARNING)
Configure webhook secret

Create directories

mkdir -p data logs
chmod 755 data logs

Test configuration

docker-compose config

Deployment

# Build and start
docker-compose up -d

# Wait for health check
sleep 10

# Verify deployment
docker-compose ps
curl http://localhost:5000/health

# Monitor logs for errors
docker-compose logs --tail=50 -f

Updating the Container

Pull latest code

git pull origin main

Rebuild image

docker-compose build

Restart with new image

docker-compose down
docker-compose up -d

Data and logs are preserved in volumes.

Verify update

docker-compose logs --tail=20
curl http://localhost:5000/health

Troubleshooting

Container exits immediately

Check logs:

docker-compose logs

Common causes:

Missing required environment variables
Invalid configuration values
Permission issues with volumes

Health check failing

Verify webhook server is running:

docker-compose exec audit-bot curl http://localhost:5000/health

Check if port is bound:

docker-compose exec audit-bot netstat -tuln | grep 5000

Cannot access webhook endpoint

Check port mapping:

docker-compose ps
netstat -tuln | grep 5000

Verify firewall:

sudo ufw status

High disk usage

Check log size:

docker-compose logs --tail=1 | wc -c

Clear old logs:

docker-compose down
rm -f logs/*
docker-compose up -d

Check temp repos:

docker-compose exec audit-bot du -sh /app/temp_repos

For more troubleshooting guidance, see the Troubleshooting Guide.

Advanced Configuration

Custom Docker Network

services:
  audit-bot:
    networks:
      - bot-network

networks:
  bot-network:
    driver: bridge

Resource Limits

services:
  audit-bot:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

Multiple Instances

Run multiple instances with different configurations:

services:
  audit-bot-1:
    build: .
    env_file: .env.bot1
    ports:
      - "5001:5000"
    
  audit-bot-2:
    build: .
    env_file: .env.bot2
    ports:
      - "5002:5000"

Get Started

Core Concepts

Guides

Components

Overview

Quick Start

Dockerfile

Docker Compose

Volume Management

Container Management

Starting and Stopping

Viewing Logs

Executing Commands

Health Checks

Health Check Configuration

Checking Health Status

Log Rotation

Building Custom Images

Build from Source

Multi-Platform Builds

Environment Variables

Production Deployment

Prerequisites Checklist

Deployment

Updating the Container

Troubleshooting

Advanced Configuration

Custom Docker Network

Resource Limits

Multiple Instances

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Components

​Overview

​Quick Start

​Dockerfile

​Docker Compose

​Volume Management

​Container Management

​Starting and Stopping

​Viewing Logs

​Executing Commands

​Health Checks

​Health Check Configuration

​Checking Health Status

​Log Rotation

​Building Custom Images

​Build from Source

​Multi-Platform Builds

​Environment Variables

​Production Deployment

​Prerequisites Checklist

​Deployment

​Updating the Container

​Troubleshooting

​Advanced Configuration

​Custom Docker Network

​Resource Limits

​Multiple Instances

Build docs developers (and LLMs) love

Overview

Quick Start

Dockerfile

Docker Compose

Volume Management

Container Management

Starting and Stopping

Viewing Logs

Executing Commands

Health Checks

Health Check Configuration

Checking Health Status

Log Rotation

Building Custom Images

Build from Source

Multi-Platform Builds

Environment Variables

Production Deployment

Prerequisites Checklist

Deployment

Updating the Container

Troubleshooting

Advanced Configuration

Custom Docker Network

Resource Limits

Multiple Instances