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

Start Beacon with a single docker run, or define a docker-compose.yml for a reproducible setup. Either way, adjust the volume paths to point at your datasets:

docker run

docker run -d \
    --name beacon \
    --restart unless-stopped \
    -p 5001:5001 \
    -p 32011:32011 \
    -e BEACON_ADMIN_USERNAME=admin \
    -e BEACON_ADMIN_PASSWORD=securepassword \
    -v ./datasets:/beacon/data/datasets \
    -v ./tables:/beacon/data/tables \
    ghcr.io/maris-development/beacon:latest

docker-compose.yml

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

If you used Compose, start it with docker compose up -d. Beacon is now running. Open http://localhost:5001/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 and remove the datasets volume:

docker run

docker run -d \
    --name beacon \
    --restart unless-stopped \
    -p 5001:5001 \
    -p 32011:32011 \
    -e BEACON_ADMIN_USERNAME=admin \
    -e BEACON_ADMIN_PASSWORD=securepassword \
    -e AWS_ENDPOINT=https://s3.amazonaws.com \
    -e AWS_ACCESS_KEY_ID=your-access-key \
    -e AWS_SECRET_ACCESS_KEY=your-secret-key \
    -e BEACON_S3_BUCKET=your-bucket-name \
    -e BEACON_S3_DATA_LAKE=true \
    -v ./tables:/beacon/data/tables \
    ghcr.io/maris-development/beacon:latest

docker-compose.yml

services:
    beacon:
        image: ghcr.io/maris-development/beacon:latest
        container_name: beacon
        restart: unless-stopped
        ports:
            - "5001:5001"
            - "32011:32011"
        environment:
            - BEACON_ADMIN_USERNAME=admin
            - BEACON_ADMIN_PASSWORD=securepassword
            - 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.

If you used Compose, start it with 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