### Advanced Configuration Examples

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/quick-install.md

Demonstrates how to use environment variables and flags to customize the installation, such as enabling TLS or specifying versions.

```bash
CB_MODE=docker CB_TLS=1 CB_HOSTNAME=cb.lan CB_YES=1 \
  curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install.sh | bash
```

```bash
bash install.sh --mode docker --version v0.2.0 --no-systemd
```

--------------------------------

### Install Prerequisites

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/quick-install.md

Installs necessary network utilities like curl or wget on Linux systems before running the installation script.

```bash
sudo apt-get update && sudo apt-get install -y curl   # or: apt-get install -y wget
```

--------------------------------

### Run Installation Script

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/quick-install.md

Executes the Circuit Breaker installation script using either curl or wget to fetch and run the installer.

```bash
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install.sh | bash
```

```bash
wget -qO- https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install.sh | bash
```

--------------------------------

### Install Backend Dependencies with Poetry

Source: https://github.com/blkleg/circuitbreaker/blob/main/poetry_errors.md

This command installs and locks the dependencies for the backend application using Poetry. It resolves all required packages and creates a lock file to ensure consistent installations across environments. Ensure Poetry is installed and configured correctly.

```bash
cd apps/backend && poetry lock && poetry install
```

--------------------------------

### Setup Ubuntu 22.04 with Python 3.12 and Node.js (Dockerfile)

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report.md

Initializes an Ubuntu 22.04 environment, installs necessary packages like `ca-certificates`, `curl`, `gnupg`, and `software-properties-common`. It adds the deadsnakes PPA for Python 3.12 and NodeSource for Node.js 20. Finally, it installs Python 3.12, Node.js, and related libraries, cleaning up apt lists afterward to reduce image size.

```dockerfile
# Native binary build with older glibc for compatibility with older Linux distros.
# Built on Fedora 43 / Ubuntu 24.04 links against GLIBC_ABI_GNU2_TLS (glibc 2.42+),
# which older systems (Debian 11, Ubuntu 20.04) lack. This image uses Ubuntu 22.04
# (glibc 2.35) so the resulting binary runs on Ubuntu 22.04+ and most older systems.
# Build-only image: no USER or HEALTHCHECK (not a long-running service).
FROM ubuntu:22.04

ENV DEBIAN_FRONTEND=noninteractive

# Add deadsnakes PPA for Python 3.12; NodeSource for Node 20 (Vite needs Node 18+)
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    curl \
    gnupg \
    software-properties-common \
    && add-apt-repository ppa:deadsnakes/ppa -y \
    && mkdir -p /etc/apt/keyrings \
    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \
    && apt-get update \
    && apt-get install -y --no-install-recommends \
    python3.12 \
    python3.12-venv \
    libpython3.12 \
    nodejs \
    binutils \
    && rm -rf /var/lib/apt/lists/*
```

--------------------------------

### Build and Start Services with Docker Compose

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/docker-compose-source.md

Commands to clone the repository, initialize the environment file, and build the Docker containers. It supports both direct docker-compose commands and Makefile shortcuts for optimized builds.

```bash
git clone https://github.com/BlkLeg/circuitbreaker.git
cd circuitbreaker
cp .env.example .env
DOCKER_BUILDKIT=1 COMPOSE_DOCKER_CLI_BUILD=1 docker compose up -d --build
```

```makefile
make compose-up
```

--------------------------------

### Non-Interactive Deployment

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/quick-install.md

Automates the installation process for CI/CD environments by setting environment variables or passing flags to bypass prompts.

```bash
CB_YES=1 CB_MODE=docker curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install.sh | bash
```

```bash
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install.sh -o install.sh
bash install.sh --mode docker --yes
```

--------------------------------

### Enable Docker Socket for Discovery

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

These bash commands show how to start the Docker Compose setup with an override file that mounts the Docker socket. This enables Docker-aware discovery, allowing the backend to enumerate containers and networks.

```bash
# Development
docker compose -f docker/docker-compose.yml -f docker/docker-compose.docker-socket.yml up -d

# Production (prebuilt images)
docker compose -f docker/docker-compose.prod.yml -f docker/docker-compose.docker-socket.yml up -d
```

--------------------------------

### Setup MFA

Source: https://context7.com/blkleg/circuitbreaker/llms.txt

Initiates the Multi-Factor Authentication setup process by generating a TOTP secret and URI. Requires an authorization token.

```bash
curl -X POST "http://localhost:8000/api/v1/auth/mfa/setup" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Troubleshoot System Permissions and Recovery

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/quick-install.md

Commands used to resolve common system-level issues such as user group permissions for Docker and recovering vault keys after installation failures.

```bash
sudo usermod -aG docker $USER
docker logs circuit-breaker
cb vault-recover
```

--------------------------------

### Install Circuit Breaker CLI Tool

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Installs the 'cb' command-line interface tool after the Docker Compose stack has been started. This tool provides access to operational commands for the circuit breaker.

```bash
make install-cb
```

--------------------------------

### Install Mono Image with Environment Variables

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Installs and runs the self-contained 'mono' Docker image, which bundles PostgreSQL, NATS, backend, workers, and frontend. Requires setting environment variables for tag, database password, and vault key.

```bash
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install-mono.sh | \
  CB_TAG=v0.2.0 CB_DB_PASSWORD='strongpass123' \
  CB_VAULT_KEY="$(openssl rand -base64 32)" bash
```

--------------------------------

### Install cb utility manually

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/cb-cli.md

Manual installation command for the cb utility on Linux systems. This copies the binary to the local bin directory with appropriate execution permissions.

```bash
sudo install -Dm755 ./cb /usr/local/bin/cb
```

--------------------------------

### Initialize Feature Branch

Source: https://github.com/blkleg/circuitbreaker/blob/main/DEV_PLAYBOOK.md

Standard Git workflow to ensure development starts from the latest integration branch.

```bash
git checkout dev
git pull origin dev
git checkout -b feat/my-feature
```

--------------------------------

### Install Playwright for Cross-Browser Testing

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/cross-browser-audit.md

Commands to install the Playwright test framework and the required browser binaries for Chromium, Firefox, and WebKit to enable cross-browser regression testing.

```bash
npm install -D @playwright/test
npx playwright install chromium firefox webkit
```

--------------------------------

### Configure OAuth Callback URLs

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/first-run.md

Required redirect URI patterns for OAuth and OIDC providers to ensure successful authentication handshakes with the Circuit Breaker application.

```text
https://<your-domain>/api/v1/auth/oauth/<provider>/callback
https://<your-domain>/api/v1/auth/oauth/oidc/oidc/callback
```

--------------------------------

### Build Frontend Assets (Dockerfile)

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report.md

Navigates to the frontend directory, installs Node.js dependencies using `npm ci` (which is generally faster and more reliable for CI environments than `npm install`), and then builds the frontend application using `npm run build`.

```dockerfile
# Build frontend
RUN cd apps/frontend && npm ci && npm run build
```

--------------------------------

### Install Backend Dependencies and PyInstaller (Dockerfile)

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report.md

Installs the necessary backend dependencies, including development packages for the application, and PyInstaller for building native executables. The `--no-cache-dir` flag helps reduce image size by not storing the pip cache.

```dockerfile
# Install backend deps + PyInstaller
RUN pip install --no-cache-dir -e "./apps/backend[dev]" pyinstaller
```

--------------------------------

### Manage Development Environment with Makefile

Source: https://github.com/blkleg/circuitbreaker/blob/main/DEV_PLAYBOOK.md

Commonly used Makefile commands to manage the development stack, including starting services, running tests, and performing code maintenance.

```bash
make dev
make backend
make frontend
make test
make lint
make format
make preflight
```

--------------------------------

### Install Circuit Breaker with Docker Compose (Option 2)

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Installs the circuit breaker using a curl script, opting for the full Docker Compose stack. This method downloads the production Docker Compose file and sets up the complete environment.

```bash
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install.sh | bash
```

--------------------------------

### One-line Install Script for Circuit Breaker

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Installs Circuit Breaker using a one-line script with curl or wget. It supports non-interactive installation with overrides for mode, acceptance, and tagged deployment. Upgrade and uninstall commands are also provided.

```bash
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/install.sh | bash

# Overrides: CB_MODE=compose CB_YES=1 curl ... | bash (non-interactive compose install)
# Tagged deploy: CB_TAG=v1.2.0 curl ... | bash (pin to a specific release)
# Upgrade: cb update or docker compose -f ~/.circuit-breaker/docker-compose.prod.yml pull && docker compose -f ~/.circuit-breaker/docker-compose.prod.yml up -d
# Uninstall: cb uninstall or curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/uninstall.sh | bash
```

--------------------------------

### Docker Run Command with Vault Key

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/manual-docker.md

This command extends the minimal setup by including an environment variable `CB_VAULT_KEY` to encrypt stored credentials at rest. A Fernet key can be generated using a Python command.

```bash
docker run -d \
  --name circuit-breaker \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v circuit-breaker-data:/data \
  -e CB_VAULT_KEY=your-fernet-key-here \
  ghcr.io/blkleg/circuitbreaker:latest
```

```python
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

--------------------------------

### Securely Execute External Commands in Python using Subprocess

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report.md

This Python code imports the 'subprocess' module, which can pose security risks if not used carefully. The example shows starting a process with a partial path and without 'shell=True', which are generally safer practices but still require careful input validation.

```python
import subprocess

from app.core.validation import validate_snmp_community
```

```python
r = subprocess.run(
    ["snmpget", "-v2c", "-c", safe_community, "-Oqv", host, oid],
    capture_output=True,
    text=True,
    timeout=3,
)
```

```python
import subprocess

from app.core.validation import validate_snmp_community
```

--------------------------------

### Start Process with Partial Path in Python

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report-3-9.10.36.md

This snippet demonstrates starting a process using 'subprocess.run' with a partial executable path ('pg_dump'). This can lead to security risks if the system's PATH environment variable is manipulated. It's recommended to use absolute paths or ensure the environment is secure. Found in db_backup.py.

```python
proc = subprocess.run(  # noqa: S603
    ["pg_dump", "--no-password"],
    env=_pg_env_from_url(db_url),
    capture_output=True,
    check=True,
)
```

--------------------------------

### Inspect cb configuration

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/cb-cli.md

Displays the current configuration file for the cb utility. This file defines the installation mode and container naming conventions.

```bash
cat ~/.circuit-breaker/install.conf
```

--------------------------------

### Configure Python 3.12 and Install Pip (Dockerfile)

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report.md

This snippet configures the Docker environment to use Python 3.12 as the default interpreter and installs pip for it. It also sets up alternatives for python and python3 commands. This is crucial for managing Python versions and dependencies within the container.

```dockerfile
# Ensure python3.12 is the default; install pip for it
RUN curl -sS https://bootstrap.pypa.io/get-pip.py | python3.12 - \
    && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1 \
    && update-alternatives --install /usr/bin/python python /usr/bin/python3.12 1
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/docker-compose-source.md

Commands to run the frontend and backend in hot-reload development mode, bypassing the full production stack.

```makefile
make dev
make backend
make frontend
make stop
```

--------------------------------

### Manage Circuit Breaker with cb CLI

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/quick-install.md

The 'cb' command-line tool allows users to monitor, update, and manage the lifecycle of the Circuit Breaker service. These commands are typically executed in a terminal environment where the binary is installed.

```bash
cb status       # Show container/service status
cb logs -f      # Follow live logs
cb restart      # Restart Circuit Breaker
cb update       # Pull latest image and restart
cb version      # Show installed version
cb uninstall    # Remove Circuit Breaker from this system
```

--------------------------------

### Troubleshoot DBus Errors During Package Installation

Source: https://github.com/blkleg/circuitbreaker/blob/main/poetry_errors.md

This snippet illustrates common DBus errors encountered during Python package installation, such as 'Remote peer disconnected'. These errors often indicate issues with the system's secret storage service or D-Bus communication, preventing packages like 'aiosmtplib', 'aiosqlite', 'apscheduler', and 'asyncpg' from installing.

```bash
# Example of a DBusErrorResponse during installation
# ...
# - Installing aiosmtplib (5.1.0): Failed
# 
# DBusErrorResponse
# 
# [org.freedesktop.DBus.Error.NoReply] ('Remote peer disconnected',)
# 
# at /usr/lib/python3.14/site-packages/secretstorage/util.py:48 in send_and_get_reply
# ...
# Cannot install aiosmtplib.
# 
# - Installing aiosqlite (0.22.1): Failed
# - Installing alembic (1.18.4): Pending...
# - Installing apscheduler (3.11.2): Failed
# - Installing asyncpg (0.31.0): Failed
# 
# DBusErrorResponse
# 
# [org.freedesktop.DBus.Error.NoReply] ('Remote peer disconnected',)
# 
# at /usr/lib/python3.14/site-packages/secretstorage/util.py:48 in send_and_get_reply
```

--------------------------------

### Release Management

Source: https://github.com/blkleg/circuitbreaker/blob/main/DEV_PLAYBOOK.md

Steps to cut a new release, including version bumping, merging development to main, publishing Docker images, and tagging the repository.

```bash
make preflight

git checkout main
git pull origin main
git merge --no-ff dev
git push origin main

docker login ghcr.io -u <your-github-username>
make docker-publish

git tag v0.1.5.1
git push origin main --tags

make test-pi-local
```

--------------------------------

### Python DBusErrorResponse Handling in SecretStorage

Source: https://github.com/blkleg/circuitbreaker/blob/main/poetry_errors.md

This Python code snippet demonstrates the handling of DBusErrorResponse within the secretstorage library. It specifically catches errors where the remote peer disconnects, leading to a SecretServiceNotAvailableException. This is a common cause for installation failures when interacting with system services.

```python
try:
    resp_msg: Message = self._connection.send_and_get_reply(msg)
    if resp_msg.header.message_type == MessageType.error:
        raise DBusErrorResponse(resp_msg)
    return resp_msg.body
except DBusErrorResponse as resp:
    if resp.name in (
        DBUS_UNKNOWN_METHOD,
        DBUS_NO_REPLY):
        data = resp.data
        if isinstance(data, tuple):
            data = data[0]
        raise SecretServiceNotAvailableException(data) from resp
    raise
```

--------------------------------

### Managing Circuit Breaker Docker Container

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/manual-docker.md

This section provides essential Docker commands for managing the Circuit Breaker container, including viewing logs, stopping, starting, restarting, updating the image, and removing the container and its associated data volume.

```bash
# View logs
docker logs circuit-breaker
docker logs -f circuit-breaker   # follow

# Stop
docker stop circuit-breaker

# Start
docker start circuit-breaker

# Restart
docker restart circuit-breaker

# Update to latest image
docker pull ghcr.io/blkleg/circuitbreaker:latest
docker stop circuit-breaker && docker rm circuit-breaker
# Re-run the original docker run command with the same volume

# Remove container only (data preserved in volume)
docker rm circuit-breaker

# Remove container and data
docker rm circuit-breaker
docker volume rm circuit-breaker-data
```

--------------------------------

### Minimal Docker Run Command for Circuit Breaker

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/manual-docker.md

This command starts the Circuit Breaker container in detached mode, assigns it a name, sets it to restart automatically, and maps the host's port 8080 to the container's port 8080. It also mounts a named volume for persistent data storage.

```bash
docker run -d \
  --name circuit-breaker \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v circuit-breaker-data:/data \
  ghcr.io/blkleg/circuitbreaker:latest
```

--------------------------------

### Copy Built Artifacts to Host (Dockerfile)

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report.md

Defines the default command to run when the container starts. It copies all files from the `dist/native` directory within the container to a host-mounted volume at `/out`. It then lists the contents of the `/out` directory. This is useful for retrieving build artifacts from the container.

```dockerfile
# When run with -v $(pwd)/dist/native:/out, copy built artifacts to host
CMD ["sh", "-c", "cp -av dist/native/. /out/ && ls -la /out"]
```

--------------------------------

### Manual Docker Compose Deployment (Production)

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Manually downloads the production Docker Compose file and deploys the circuit breaker stack. Requires placing Caddyfile and .env files alongside the compose file.

```bash
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/docker/docker-compose.prod.yml -o docker-compose.prod.yml
docker compose -f docker-compose.prod.yml up -d
```

--------------------------------

### Download and Start Circuit Breaker with Docker Compose

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/docker-compose.md

Quickly deploy Circuit Breaker by downloading the `docker-compose.prebuilt.yml` file and starting the service in detached mode. The application will be accessible on port 8080.

```bash
# 1. Download the compose file
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/docker/docker-compose.prebuilt.yml \
  -o docker-compose.yml

# 2. Start Circuit Breaker
docker compose up -d
```

--------------------------------

### Build Native Release Dockerfile

Source: https://github.com/blkleg/circuitbreaker/blob/main/SECURITY_REPORTS/security_scan_report.md

This Dockerfile sets up a build environment for native binaries. It installs Python 3.12, Node.js 20, and necessary build tools, then executes the build pipeline for both frontend and backend before copying artifacts to an output directory.

```dockerfile
FROM ubuntu:22.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    curl \
    gnupg \
    software-properties-common \
    && add-apt-repository ppa:deadsnakes/ppa -y \
    && mkdir -p /etc/apt/keyrings \
    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \
    && apt-get update \
    && apt-get install -y --no-install-recommends \
    python3.12 \
    python3.12-venv \
    libpython3.12 \
    nodejs \
    binutils \
    && rm -rf /var/lib/apt/lists/*

RUN curl -sS https://bootstrap.pypa.io/get-pip.py | python3.12 - \
    && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1 \
    && update-alternatives --install /usr/bin/python python /usr/bin/python3.12 1

WORKDIR /build
COPY . .

RUN pip install --no-cache-dir -e "./apps/backend[dev]" pyinstaller
RUN cd apps/frontend && npm ci && npm run build
RUN python3 scripts/build_native_release.py --clean

CMD ["sh", "-c", "cp -av dist/native/. /out/ && ls -la /out"]
```

--------------------------------

### Build and run Circuit Breaker from source

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Commands to clone the repository and initialize the stack using Docker Compose. This is the standard method for building the application from source code.

```bash
git clone https://github.com/BlkLeg/circuitbreaker.git && cd circuitbreaker
docker compose -f docker/docker-compose.yml up -d
```

--------------------------------

### Grafana Panel PromQL Examples for Circuit Breaker

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/metrics.md

Example PromQL queries suitable for direct use in Grafana panels to visualize circuit breaker metrics. These cover service status, storage utilization, and inventory totals.

```promql
# Service status overview (stat panel)
sum by (status) (circuitbreaker_service_status == 1)

# Degraded/stopped services (alert panel)
sum(circuitbreaker_service_status{status=~"stopped|degraded"} == 1)

# Storage utilization (gauge panel)
sum(circuitbreaker_storage_used_gb_total) / sum(circuitbreaker_storage_capacity_gb_total) * 100

# Inventory totals (stat panels)
circuitbreaker_hardware_total, circuitbreaker_services_total, circuitbreaker_compute_units_total

# RAM by host (bar chart)
circuitbreaker_hardware_memory_configured_gb

# Storage by item (bar chart)
circuitbreaker_storage_capacity_gb
```

--------------------------------

### Manage Optional Service Profiles

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/installation/docker-compose-source.md

Commands to launch the stack with specific profiles, such as PostgreSQL for database persistence or Cloudflare Tunnel for remote access.

```bash
docker compose -f docker/docker-compose.yml --profile pg up -d --build
docker compose -f docker/docker-compose.yml --profile tunnel up -d
```

--------------------------------

### Single-Container Prebuilt Docker Compose Deployment

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Deploys a minimal single-container setup using a prebuilt Docker Compose file. This is a streamlined option that does not include discovery workers.

```bash
curl -fsSL https://raw.githubusercontent.com/BlkLeg/circuitbreaker/main/docker/docker-compose.prebuilt.yml -o docker-compose.yml && docker compose up -d
```

--------------------------------

### GET /api/v1/proxmox

Source: https://context7.com/blkleg/circuitbreaker/llms.txt

Retrieve a list of all configured Proxmox integrations.

```APIDOC
## GET /api/v1/proxmox

### Description
Returns a list of all Proxmox integrations currently configured in the system.

### Method
GET

### Endpoint
/api/v1/proxmox

### Request Example
curl -X GET "http://localhost:8000/api/v1/proxmox" -H "Authorization: Bearer $TOKEN"

### Response
#### Success Response (200)
- **integrations** (array) - List of Proxmox integration objects.
```

--------------------------------

### GET /api/v1/storage

Source: https://context7.com/blkleg/circuitbreaker/llms.txt

Retrieve a list of storage pools and volumes.

```APIDOC
## GET /api/v1/storage

### Description
Lists all storage items, with optional filtering by storage kind or hardware association.

### Method
GET

### Endpoint
/api/v1/storage

### Query Parameters
- **kind** (string) - Optional - Storage type (e.g., zfs)
- **hardware_id** (integer) - Optional - Filter by hardware node

### Response
#### Success Response (200)
- **storage_items** (array) - List of storage objects
```

--------------------------------

### Build and Publish Production Docker Images

Source: https://github.com/blkleg/circuitbreaker/blob/main/README.md

Commands to set up Docker buildx and publish production-ready Docker images for the circuit breaker backend and frontend. Requires a specific tag for versioning.

```bash
make setup-buildx
make docker-publish-prod TAG=v0.2.0-2-beta
```

--------------------------------

### Initialize PostgreSQL Database

Source: https://github.com/blkleg/circuitbreaker/blob/main/docs/mono-db-production-plan.md

Explicitly invokes the initdb binary using its full system path to bypass environment PATH limitations in Debian-based containers.

```bash
/usr/lib/postgresql/15/bin/initdb -D /var/lib/postgresql/data
```

--------------------------------

### GET /api/v1/graph/topology

Source: https://context7.com/blkleg/circuitbreaker/llms.txt

Retrieve the infrastructure topology graph with optional filtering and caching support.

```APIDOC
## GET /api/v1/graph/topology

### Description
Fetches the complete infrastructure topology including nodes and edges. Supports filtering by environment, rack, and entity type.

### Method
GET

### Endpoint
/api/v1/graph/topology

### Parameters
#### Query Parameters
- **environment** (string) - Optional - Filter by environment (e.g., production)
- **include** (string) - Optional - Comma-separated list of entity types
- **rack_id** (integer) - Optional - Filter by rack ID

### Response
#### Success Response (200)
- **nodes** (array) - List of infrastructure nodes
- **edges** (array) - List of connections between nodes

### Response Example
{
  "nodes": [{"id": "hw-1", "type": "hardware", "label": "pve-node-01"}],
  "edges": [{"id": "e-1", "source": "hw-1", "target": "cu-1"}]
}
```

--------------------------------

### Validate Docker Environment

Source: https://github.com/blkleg/circuitbreaker/blob/main/DEV_PLAYBOOK.md

Commands to verify the application stack, including fresh builds and clean database states for testing OOBE (Out-of-Box Experience).

```bash
make compose-fresh
make compose-clean
make compose-up
```