No description
Find a file
2026-11-20 11:26:01 -05:00
.vscode chore: disable pyright type checking in vscode 2026-10-01 16:50:29 -04:00
.zed feat(web): setup wizard, settings page, Firebreak rename (#15) 2026-06-08 14:56:27 -04:00
cli Merge origin/main into fix/borderless-btn-red-default 2026-09-04 11:55:30 -04:00
docs docs(web): clarify snapshot and share-link terminology 2026-11-20 10:58:54 -05:00
examples fix(cli): address PR review feedback 2026-09-04 11:54:42 -04:00
web fix(web): secure Forgejo requests and pin picker branch tips 2026-11-20 11:26:01 -05:00
.dockerignore Add FastAPI web service with async SQLAlchemy and Docker (#10) 2026-04-24 16:03:54 -04:00
.gitignore chore: rename all references from myst/embargo to firebreak 2026-08-16 13:13:02 -04:00
agents.md fix(web): secure Forgejo requests and pin picker branch tips 2026-11-20 11:26:01 -05:00
docker-compose.yml feat(web): setup wizard, settings page, Firebreak rename (#15) 2026-06-08 14:56:27 -04:00
package.json chore: rename all references from myst/embargo to firebreak 2026-08-16 13:13:02 -04:00
pnpm-lock.yaml build(web): migrate tailwind build to pnpm-managed CLI 2026-10-01 16:50:31 -04:00
pnpm-workspace.yaml build(web): migrate tailwind build to pnpm-managed CLI 2026-10-01 16:50:31 -04:00
README.md fix(web): secure Forgejo requests and pin picker branch tips 2026-11-20 11:26:01 -05:00
tsconfig.base.json chore: clean up project structure and remove dead code 2026-08-16 19:32:41 -04:00
tsconfig.json chore: clean up project structure and remove dead code 2026-08-16 19:32:41 -04:00

Firebreak

Fight fire with fire. Your code. Your rules.

Firebreak is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for code snapshots.

System Diagram

This diagram shows how traffic moves through the public internet, the VPS or self-hosted server, the host firewall, the platform router, Firebreak, Forgejo, and Postgres.

Firebreak system routing diagram

Click the diagram to open the full-size SVG.

Features

Type Verification Use Case
Private Email verification code required Share with specific individuals
Public No verification, time-expired Job applications, portfolios

Security

  • Links pinned to immutable commit_sha — not moving branches
  • Email verification prevents unauthorized access
  • Time-expiration and revocation give owners control
  • No public repo listing — anti-scraping by design
  • Admin access protected upstream (Tailscale, VPN, Cloudflare Access)

Authentication

Purpose Method
User Identity Forgejo OAuth
Data Access User's Forgejo PAT

Tech Stack

  • Backend: Python + FastAPI
  • Frontend: Jinja2 templates + HTMX (no build step)
  • Database: PostgreSQL

HTMX provides interactivity (filtering, form submissions) with minimal JavaScript. Jinja2 handles server-side rendering for fast page loads.

Quick Start

1. Deploy with Docker Compose

docker compose up -d

2. Generate an Encryption Key

Firebreak encrypts OAuth tokens and PATs at rest using a Fernet key. Generate one and add it to your environment before running the setup wizard:

uv run python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

Add the output to your .env file (or your deployment platform's environment variables):

TOKEN_ENCRYPTION_KEY=your-generated-key-here

3. Run the Setup Wizard

Open http://localhost:8000 in your browser. On first boot, Firebreak redirects to a setup wizard where you configure:

  • Forgejo instance URL — use HTTPS unless Forgejo is a local service or loopback endpoint
  • OAuth credentials — register an OAuth application in Forgejo first (Settings → Applications → Create OAuth2 Application), then paste the Client ID and Client Secret
  • Public base URL (optional) — your production domain for OAuth redirects

4. Sign In and Register Your Token

After setup, sign in with your Forgejo account via OAuth. Register a personal access token (PAT) with read:user and read:repository so you can browse your repositories and preview snapshots.

See the Firebreak glossary for the difference between snapshots, share links, and grants.

5. Alternative Deployments

For non-Docker deployments, supply DATABASE_URL yourself:

  • VPS deployment: Hostinger or another VPS with Dokploy, Traefik, UFW, Firebreak, Forgejo, and a shared Postgres instance that contains separate forgejo and firebreak databases.
  • Self-hosted server deployment: a home server, mini PC, NAS, or other self-hosted Linux machine running Firebreak with Docker, Podman, Docker Compose, Coolify, Caddy, Nginx, or another reverse proxy.

Firebreak should not assume a VPS-only environment. The requirement is an existing Forgejo instance, Firebreak's own database, and a way to route the public and admin hostnames to the Firebreak app.

Phase 1 Progress

  • Project renamed from Embargo to Firebreak
  • CLI scaffold (firebreak config init)
  • Config generation (.env)
  • Service foundation (FastAPI + PostgreSQL)
  • firebreak config verify — verify Forgejo connectivity
  • firebreak config verify --diagnostic — comprehensive diagnostics
  • firebreak config view — show current config
  • Forgejo OAuth authentication
  • Repo ownership verification
  • Private link creation (email-verified)
  • Public link creation (time-expired)
  • Web-based code viewer
  • User dashboard
  • SMTP configuration UI
  • Access logs

Resources