bypass

Personal-scale archive.ph-like site.

Architecture

• bypass-api (Go) — HTTP server, save/snapshot routes, Postgres.
• bypass-fetcher (Go + Playwright/Chromium) — fetches and renders URLs as Googlebot.
• Postgres — one snapshots table.

See docs/superpowers/specs/2026-06-02-archive-snapshot-site-design.md for the full design.

Build

make build

Produces bin/bypass-api and bin/bypass-fetcher.

Test

make test

test runs test-api, test-fetcher, test-store, and helm-test. Store tests need a Postgres on localhost:5432 with a bypass_test database:

docker run -d --name pg-test -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=bypass_test postgres:16
export TEST_DATABASE_URL='postgres://postgres:postgres@localhost:5432/bypass_test?sslmode=disable'
make test-store

Other targets: make test-api, make test-fetcher, make lint.

Docker Compose

Spin up a full local instance with Docker Compose:

# Generate secrets for fetcher authentication and Postgres
export FETCHER_SECRET=$(openssl rand -hex 16)
export POSTGRES_PASSWORD=$(openssl rand -hex 16)

# Run migrations, then start all services
docker compose up -d

This starts four containers: postgres, migrate (one-shot), api, and fetcher. The API is available at http://127.0.0.1:8003.

Stop and clean up:

docker compose down -v

Build images

Build and push images to your own registry:

docker buildx build --push \
  -f Dockerfile.api     -t registry.example.com/bypass-api:latest     .
docker buildx build --push \
  -f Dockerfile.fetcher -t registry.example.com/bypass-fetcher:latest .
docker buildx build --push \
  -f Dockerfile.migrate -t registry.example.com/bypass-migrate:latest .

Deploy (Helm)

kubectl create namespace bypass

# Install: chart includes a bundled Postgres StatefulSet + a helm hook
# Job that runs migrations on install/upgrade. The only secret baked
# in is the postgres password; everything else renders itself.
helm upgrade --install bypass charts/bypass -n bypass \
  --set postgres.password=<long-random-string>

The bundled Postgres lives in the same release (<release>-postgres) and is not exposed outside the cluster. To reuse an existing database, set postgres.enabled=false and provide a bypass-pg Secret with a url key.

Apply migrations

The chart ships a bypass-migrate Job as a post-install,post-upgrade hook, so helm upgrade --install runs it automatically. To re-run manually:

kubectl create job --from=job/bypass-migrate bypass-migrate-manual -n bypass

Smoke test

BASE=https://bypass.koetsier.org ./scripts/smoke.sh

Deploy to a remote VM (docker compose)

The deploy target is not stored in the repo:

export BYPASS_DEPLOY_HOST=root@<host>
./deploy.sh

The script syncs the source, generates .env (random FETCHER_SECRET and POSTGRES_PASSWORD) if missing, runs migrations, and waits for the health check. docker-compose.yml refuses to start without POSTGRES_PASSWORD set.