Skip to main content
Version: Next

Install BeaRust

BeaRust ships as a single Docker image, rizalord/bearust, published to Docker Hub. You do not need to clone the source repository to run it — this page's quick start creates just two files yourself and starts the stack from the published image. A second section covers building from a source checkout instead, for contributors or anyone who wants to build the image locally.

Prerequisites​

  • Docker Engine with the Docker Compose plugin available as docker compose.
  • Two files you create yourself: a docker-compose.yml and a route configuration file. Nothing else.

Quick start (no clone required)​

1. Create a working directory​

mkdir bearust && cd bearust

2. Write docker-compose.yml​

This is the production-oriented stack: the data plane on 8080, the control API and UI on 127.0.0.1:8081 only, persistent state in named Docker volumes, and a read-only, non-root container.

docker-compose.yml
services:
  bearust:
    image: rizalord/bearust:latest
    command: ["serve", "--config", "/etc/bearust/bearust.toml", "--json-logs"]
    ports:
      - "8080:8080"
      - "127.0.0.1:8081:8081"
    volumes:
      - "./bearust.toml:/etc/bearust/bearust.toml:ro"
      - bearust-data:/data
      - bearust-tls:/etc/bearust/tls
    environment:
      RUST_LOG: "info"
      # Set this once to avoid the generated one-time setup token on first
      # startup. Use a long, random value — never a real value in version
      # control or in shared documentation.
      BEARUST_SETUP_TOKEN: ""
    working_dir: /run/bearust
    healthcheck:
      test: ["CMD-SHELL", "test -s /run/bearust/bearust.pid && nc -z 127.0.0.1 8080 && nc -z 127.0.0.1 8081"]
      interval: 5s
      timeout: 3s
      start_period: 10s
      retries: 20
    read_only: true
    tmpfs:
      - /tmp:mode=1777
      - /run/bearust:uid=10001,gid=10001,mode=0755
    cap_drop: [ALL]
    security_opt: [no-new-privileges:true]
    restart: unless-stopped

volumes:
  bearust-data:
  bearust-tls:

3. Write a minimal bearust.toml​

This starts BeaRust with no routes configured yet — enough to boot, reach the setup API, and verify health. Add upstream pools and routes once you have a backend to point at (see Configure your first proxy).

bearust.toml
[server]
bind = "0.0.0.0:8080"
control_bind = "0.0.0.0:8081"
control_database = "/data/bearust.sqlite"
pid_file = "/run/bearust/bearust.pid"
certificate_store = "/data/certificates"

[health]

4. Start the stack​

docker compose up -d

5. Verify the deployment​

docker compose ps
curl --fail http://127.0.0.1:8081/api/setup/status

Expect the bearust service to show running (healthy) and the curl command to return {"initialized":false} on a new deployment (or true after setup). That healthy state includes Compose's checks for the PID file and both the container's 8080 data-plane and 8081 control-plane listeners.

Continue to first-time setup to create the first administrator.

Bootstrap token​

On the first SQLite-backed start, BeaRust generates a one-time setup token and writes it to the persistent data area with owner-only permissions. On a trusted host, retrieve it from the running container without copying it into tickets, chat, or shell history:

docker compose exec bearust cat /data/setup-token

The startup log records that a token file was generated, but does not print the token value. To set a deterministic bootstrap token instead, add a long random value to the BEARUST_SETUP_TOKEN environment variable in docker-compose.yml, or move it into a .env file next to the Compose file:

.env
BEARUST_SETUP_TOKEN=replace-with-a-long-random-value

Then use that value only for first-time setup. The token does not replace ordinary administrator authentication after initialization.

Use an external database (PostgreSQL or MySQL)​

The default stack uses SQLite. To use PostgreSQL or MySQL instead, add the corresponding service to your docker-compose.yml and point DATABASE_URL at it:

docker-compose.yml (excerpt — add under services:)
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: bearust
      POSTGRES_PASSWORD: "<postgres-password>"
      POSTGRES_DB: bearust
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 10

Add postgres-data: under volumes:, add a DATABASE_URL environment entry to the bearust service, and have bearust depend on postgres's health check:

.env
DATABASE_URL=postgres://bearust:<postgres-password>@postgres:5432/bearust

Use a credential-shaped placeholder in documentation and automation, never a real password. Compose waits for the selected database's health check, and BeaRust runs migrations at startup. Switching from SQLite to PostgreSQL is not an in-place change: perform and test an explicit export/import, retain the old bearust-data volume as a rollback copy, and do not delete it until the new deployment is verified.

Building from a source checkout instead​

If you are contributing to BeaRust or want to build the image yourself rather than pull rizalord/bearust, clone the source repository and use its bundled Compose file, which supports building locally and additional profiles:

git clone https://github.com/rizalord/bearust.git
cd bearust
cp .env.example .env
docker compose up -d --build

This uses config/bearust.example.toml from the checkout instead of a hand-written file, and supports the same PostgreSQL/MySQL profiles described above via docker compose --profile postgres up -d --build. See contributor development setup if you plan to modify BeaRust itself.

Next, initialize the first administrator.