No description
Find a file
Zach Tatman db15307efd
Merge pull request #29 from ZTatman/feature/learn-public-links
Add Forgejo repository browsing and snapshot selection
2026-11-20 17:01:28 -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 Merge pull request #29 from ZTatman/feature/learn-public-links 2026-11-20 17:01:28 -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: apply CodeRabbit auto-fixes 2026-11-20 16:56:32 -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: apply CodeRabbit auto-fixes 2026-11-20 16:56:32 -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 (required) — confirm the pre-filled URL or replace it with the Firebreak URL you want to use 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