Skip to content
Pinchana Docs

Deploy Pinchana Web

Pinchana Web is a server-backed Next.js application. It must be deployed as an application server; it is not a static browser bundle that can safely call Pinchana API directly.

Prerequisites

Section titled “Prerequisites”

Before deploying Web, have a reachable production Pinchana API with:

  • HTTPS public API origin;
  • browser endpoints including POST /v1/web/scrape;
  • API-side Turnstile secret/expected hostname/action/session signer;
  • normal modules healthy;
  • DLP either deliberately disabled or fully preflighted/canaried.

Create a Cloudflare Turnstile widget for the final Web hostname.

Configure Web

Section titled “Configure Web”
Terminal window
git clone https://github.com/Pinchana/pinchana-web.git
cd pinchana-web
cp .env.example .env
chmod 600 .env

Required production values:

PINCHANA_API_URL=https://api.example.com
NEXT_PUBLIC_TURNSTILE_SITE_KEY=REPLACE_WITH_PUBLIC_WIDGET_SITE_KEY

PINCHANA_API_URL is server-only and must never be renamed to a NEXT_PUBLIC_... variable.

The public site key must correspond to the private TURNSTILE_SECRET_KEY configured on API and must be registered for the final Web hostname expected by TURNSTILE_EXPECTED_HOSTNAME.

Build and start with Compose

Section titled “Build and start with Compose”
Terminal window
docker compose --env-file .env config --quiet
docker compose --env-file .env up --detach --build
docker compose --env-file .env ps

The Compose service:

  • builds the local source into ${PINCHANA_WEB_IMAGE:-pinchana-web:latest};
  • runs as the non-root bun user in the final image;
  • listens on container port 3000;
  • binds to ${WEB_BIND_ADDRESS:-127.0.0.1}:${WEB_HOST_PORT:-3000} by default;
  • health-checks the local Web server.

The image build uses Bun 1.3.14 and runs the repository production build (next build --webpack plus the Sentry-build verification script).

Reverse proxy and HTTPS

Section titled “Reverse proxy and HTTPS”

Keep the default loopback binding and publish Web through your reverse proxy:

https://pinchana.example.com -> http://127.0.0.1:3000

Production needs HTTPS both for the Web origin and the configured API origin. Preserve cookies and normal streaming/range behavior through the proxy.

Do not rewrite same-origin /api/... paths to the Pinchana API yourself. Those paths are implemented by the Next.js BFF and are responsible for attaching the signed session, validating custom instances, rewriting media, and streaming DLP files.

Custom API connections

Section titled “Custom API connections”

The configured default PINCHANA_API_URL works without an instance certificate because it is an operator-selected server-side origin.

If this Web deployment should let users select additional project-certified API origins, configure the project Ed25519 public key:

PINCHANA_INSTANCE_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nREPLACE_WITH_PROJECT_PUBLIC_KEY\n-----END PUBLIC KEY-----"

This enables server-side verification of certificates returned by custom APIs at /web/identity. Never install the project signing private key on the Web host.

Build revision

Section titled “Build revision”

Web can expose its public source revision in About:

NEXT_PUBLIC_PINCHANA_WEB_COMMIT=REPLACE_WITH_PUBLIC_GIT_COMMIT

When repository metadata is available the build can derive a commit automatically; Compose provides an explicit build argument because .git is excluded from the Docker context.

Optional Sentry monitoring

Section titled “Optional Sentry monitoring”

Monitoring is explicitly disabled by default:

SENTRY_MONITORING_ENABLED=false
NEXT_PUBLIC_SENTRY_DSN=
NEXT_PUBLIC_SENTRY_ENVIRONMENT=production

To enable it, set the feature flag and DSN and rebuild the image. Browser error events are sanitized; anonymous performance measurements still require visitor opt-in.

For production source-map upload, keep SENTRY_AUTH_TOKEN in a BuildKit secret. Do not expose it as NEXT_PUBLIC_... or bake it into the runtime environment.

DLP

Section titled “DLP”

Web does not receive Redis, DLP gateway, worker, VPN, Docker-socket, or Cookie Vault server secrets. It feature-detects DLP through API /web/capabilities after browser-session verification.

Deploy Web safely while DLP is still unavailable, complete the API/DLP canary, then enable DLP_ENABLED on the API gateway. Web will expose YouTube controls automatically when protocol v2 becomes healthy.

Upgrade

Section titled “Upgrade”

Pull/update the public Web source and rebuild/recreate the service:

Terminal window
docker compose --env-file .env config --quiet
docker compose --env-file .env up --detach --build

Re-run bun run test, bun run lint, and bun run build in the source checkout before production rollout when you are deploying your own modified Web code.