Getting Started

This guide gets a Beacon instance running with Docker Compose. For ready-made examples including MinIO and sample datasets, see the beacon-example repository.

Prerequisites

• Docker
• Docker Compose

Local

Create a docker-compose.yml file and adjust the volume path to point at your datasets:

services:
    beacon:
        image: ghcr.io/maris-development/beacon:latest
        container_name: beacon
        restart: unless-stopped
        ports:
            - "8080:8080"   # HTTP API
            - "32011:32011" # Arrow Flight SQL
        environment:
            - BEACON_ADMIN_USERNAME=admin
            - BEACON_ADMIN_PASSWORD=securepassword
            - BEACON_VM_MEMORY_SIZE=4096
            - BEACON_HOST=0.0.0.0
            - BEACON_PORT=8080
        volumes:
            - ./datasets:/beacon/data/datasets
            - ./tables:/beacon/data/tables

Start Beacon:

docker compose up -d

Beacon is now running. Open http://localhost:8080/swagger to verify and explore the API. Any files placed in ./datasets are immediately available for querying.

S3-Compatible Object Storage

Add the S3 environment variables to your compose file and remove the datasets volume:

services:
    beacon:
        image: ghcr.io/maris-development/beacon:latest
        container_name: beacon
        restart: unless-stopped
        ports:
            - "8080:8080"
            - "32011:32011"
        environment:
            - BEACON_ADMIN_USERNAME=admin
            - BEACON_ADMIN_PASSWORD=securepassword
            - BEACON_VM_MEMORY_SIZE=4096
            - BEACON_HOST=0.0.0.0
            - BEACON_PORT=8080
            - AWS_ENDPOINT=https://s3.amazonaws.com
            - AWS_ACCESS_KEY_ID=your-access-key
            - AWS_SECRET_ACCESS_KEY=your-secret-key
            - BEACON_S3_BUCKET=your-bucket-name
            - BEACON_S3_DATA_LAKE=true
        volumes:
            - ./tables:/beacon/data/tables

Anonymous / public buckets

For publicly accessible buckets, omit AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY and add AWS_SKIP_SIGNATURE=true instead.

Start Beacon the same way:

docker compose up -d

Files already in the S3 bucket are available for querying immediately. The ./tables volume persists any external tables or views you create.

Next steps

Connect a client	JetBrains DataGrip · Python ADBC
Register datasets as SQL tables	External Tables · Views
Write queries	SQL Guide
Tune performance	Performance Tuning