app-sidecar

App Sidecar Containers

Sidecars are pre-built Docker images deployed alongside an app backend in the same network namespace (sharing localhost). They enable auxiliary services that the backend communicates with over HTTP or other protocols on localhost.

Prerequisites

1. App must have a backend/ folder configured in fusebase.json

Use Cases

Sidecar	Image Example	Port	Purpose
Headless browser	browserless/chrome:latest	9222	Web scraping, PDF generation, screenshots
Lightweight browser	nicholasgriffintn/lightpanda:latest	9222	Fast page parsing
Redis cache	redis:7-alpine	6379	Caching, queues, pub/sub
Image processor	dpokidov/imageproxy:latest	8080	Image resizing/optimization

CLI Commands

Add a Sidecar

fusebase sidecar add \
  --app <appPath> \
  --name <name> \
  --image <dockerImage> \
  [--port <port>] \
  [--tier small|medium|large] \
  [--env KEY=VALUE ...] \
  [--secret KEY|KEY:ALIAS ...]

Example:

fusebase sidecar add \
  --app my-scraper \
  --name chromium \
  --image browserless/chrome:latest \
  --port 9222 \
  --tier medium \
  --env MAX_CONCURRENT_SESSIONS=5 \
  --env CONNECTION_TIMEOUT=30000

Remove a Sidecar

fusebase sidecar remove --app <appPath> --name <name>

List Sidecars

fusebase sidecar list --app <appPath>

--feature (-f) is accepted as a deprecated alias for --app (-a).

Whitelisting Secrets

By default, app secrets registered via fusebase secret create are injected only into the main backend container (and into cron job containers). Sidecars receive no app secrets unless you explicitly whitelist the keys you want each sidecar to see.

Use the repeatable --secret option on fusebase sidecar add to opt in:

# Inject the secret as an env var with the same name (DB_PASSWORD)
fusebase sidecar add --app my-scraper --name redis \
  --image redis:7-alpine \
  --secret DB_PASSWORD

# Inject the secret under a different env var name inside the sidecar
# (sidecar sees REDIS_AUTH_TOKEN; the underlying secret remains DB_PASSWORD)
fusebase sidecar add --app my-scraper --name redis \
  --image redis:7-alpine \
  --secret DB_PASSWORD:REDIS_AUTH_TOKEN