Web development

For implementation details, see the dedicated Web development reference. This page focuses on getting a self-hosted development checkout running against a Pinchana API.

Clone and install

git clone https://github.com/Pinchana/pinchana-web.git
cd pinchana-web
bun install --frozen-lockfile
cp .env.example .env.local

Minimum local configuration:

PINCHANA_API_URL=http://127.0.0.1:8080
NEXT_PUBLIC_TURNSTILE_SITE_KEY=REPLACE_WITH_PUBLIC_SITE_KEY
SENTRY_MONITORING_ENABLED=false

The API must separately have the corresponding Turnstile secret/session configuration. For local UI work, Cloudflare’s documented test site/secret pair can be used.

Run

bun run dev

Open http://localhost:3000.

The development script synchronizes the local FFmpeg WebAssembly assets before starting Next.js.

Validate

bun run test
bun run lint
bun run build

Test at least:

• session gate/Turnstile flow;
• one normal scrape and authenticated media preview;
• audio mode/normal downloads when touched by the change;
• custom-instance validation when relevant;
• DLP capability gating and a test job when relevant;
• English/Ukrainian rendering for text changes.

Server/client boundary

Keep PINCHANA_API_URL server-only. Browser components should use same-origin /api/... handlers. Never introduce a public machine API key to make local development easier.

Only intentionally browser-visible values use NEXT_PUBLIC_..., such as the Turnstile site key and public build revision.

Custom instances

PINCHANA_INSTANCE_PUBLIC_KEY is optional. Without it, the custom-instance connection form is disabled. Configure it only when testing project-issued certificate validation.

Production custom origins require HTTPS; local development can use HTTP origins for development-only testing.

Docker parity

The production Docker image builds and runs with Bun as a non-root bun user. Compose binds Web to 127.0.0.1:3000 by default and expects a reverse proxy for public TLS.

Before shipping a change that only works under next dev, verify the production bun run build and, when deployment behavior changed, the repository Docker Compose build.