Deployment

Deployment

While Brespi can run standalone, Docker is the recommended approach.

Please keep in mind that there are no pre-built Docker images. Instead, Brespi provides a build script that generates an image tailored to your setup.

Docker

To create an image, execute the ./brespi image create command in the project's root folder.

This command can be used with the --postgresql and --mariadb flags to ensure that the respective database client tools will be included in the created Docker image (which are required if your pipelines use PostgreSQL, MariaDB or MySQL backup steps).

# Clone the repository
git clone https://github.com/butterhosting/brespi.git
cd brespi

# Specify a version (or commit hash)
git checkout 1.0.0

# Build the Docker image
./brespi image create --postgresql --mariadb

For fully custom runtime environments, you can provide your own Dockerfile using the --dockerfile option. See the deployment/ directory in the source code for some examples.

After successfully building a Brespi image via ./brespi image create, you can verify it starts correctly via this command:

docker run --rm -p 3000:3000 brespi:latest

If you're looking to try Brespi out with a real PostgreSQL database, you can run docker compose up inside a folder containing the following compose.yaml file.

services:
  brespi:
    image: brespi:latest
    ports:
      - "3000:3000"
    environment:
      POSTGRESQL_URL: "postgresql://admin:password@postgres:5432"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:17
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: password
    configs:
      - source: seed
        target: /docker-entrypoint-initdb.d/seed.sql
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "admin"]
      interval: 1s
      timeout: 10s
      retries: 10

configs:
  seed:
    content: |
      CREATE DATABASE musicworld;
      \c musicworld;
      CREATE TABLE instruments (
          id SERIAL PRIMARY KEY,
          name VARCHAR(100),
          category VARCHAR(50),
          price DECIMAL(10, 2)
      );
      INSERT INTO instruments (name, category, price) VALUES
          ('Fender Stratocaster', 'Electric Guitar', 1299.99),
          ('Gibson Les Paul', 'Electric Guitar', 2499.99),
          ('Yamaha P-125', 'Digital Piano', 649.99),
          ('Roland TD-17KV', 'Electronic Drums', 1699.99),
          ('Shure SM58', 'Microphone', 99.99);

In a more realistic composed setup, you'll likely have Brespi joining external Docker networks and volumes:

services:
  brespi:
    image: brespi:latest
    ports:
      - "3000:3000"
    volumes:
      - ./config.json:/opt/brespi/config.json
      - ./.htpasswd:/opt/brespi/.htpasswd:ro
      - brespi-data:/opt/brespi/data/
      - wordpress-uploads:/mnt/wp-uploads:ro
    environment:
      ENCRYPTION_KEY: "secret-encryption-key"
      S3_URL: "s3://ACCESS_KEY:SECRET_KEY@s3.eu-central-1.amazonaws.com/backups"
      POSTGRESQL_URL: "postgresql://brespi:secretpassword@postgresql:5432"
      MARIADB_URL: "mariadb://brespi:secretpassword@mariadb:3306"
      SLACK_URL: "https://hooks.slack.com/services/T00/B00/xxxx"
    networks:
      - postgresql
      - wordpress

volumes:
  brespi-data:
  wordpress-uploads:
    external: true

networks:
  postgresql:
    external: true
  wordpress:
    external: true

Standalone

To run Brespi without Docker, please make sure the following are installed on your system:

  • Bun
  • Any database client tools your pipelines require (psql, mysqldump, etc.)

Brespi can then be started as follows.

# Install dependencies
bun install

# Start the application (will listen on port 3000)
bun start:prod

Authentication

Brespi supports HTTP Basic Authentication. To enable it, place a passwords file at /opt/brespi/.htpasswd using the standard Apache htpasswd format with bcrypt-hashes.

alice:$2b$10$0EhE06AyBn4shMGqCkJzqOIPGsYCJxO2mzbgCbfFQ4te5003PiYOK
bob:$2b$10$LbAfTfDmhD9SbroH.JVrc.uUpfNxVDDtjPDTvwE7UaCNnn3PxrQF2

The ./brespi hash command can be used to generate a bcrypt hash (requires Docker).

If no passwords file is present, authentication is disabled. For any deployments exposed to the internet, you should either enable authentication or place Brespi behind a reverse proxy that handles it.

Previous
Configuration