Build and deploy

This page covers the frontend side of shipping: what the build produces and how the repo’s workflows package it. Server access details and secret values are not documented here on purpose.

The standalone build

apps/saas/next.config.ts:

const nextConfig: NextConfig = {
	output: "standalone",
	deploymentId: process.env.DEPLOYMENT_VERSION,
	outputFileTracingRoot: path.join(__dirname, "../../"),
	transpilePackages: ["@repo/auth", "@repo/ui"],
	// ...
};

output: "standalone" makes next build emit apps/saas/.next/standalone/, a self contained tree with apps/saas/server.js, the traced workspace packages and a slim node_modules.
outputFileTracingRoot points at the monorepo root so files from packages/* are traced in.
deploymentId ties the client bundle to a release, which lets Next.js detect a browser running an older build.

Standalone output does not include static assets. A release has to add them:

Copy	To
`apps/saas/.next/static`	`apps/saas/.next/static` inside the release
`apps/saas/public`	`apps/saas/public` inside the release
The marketing export	`apps/saas/public/mkt` and `apps/saas/public/mkt-assets`

apps/saas/public holds the trainee app preview bundle, the assistant avatar images and the wizard assets. If a file is not on disk under public when the release is packaged, it is not in production. The server is started with node apps/saas/server.js. It reads PORT and HOSTNAME.

Build time and run time variables

Variable	When it matters
`NEXT_PUBLIC_SAAS_URL`, `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_MEDIA_CDN_URL`, other `NEXT_PUBLIC_*`	Build time. Inlined into the client bundle
`CORE_API_URL`, `CORE_API_SERVICE_ID`, `SERVICE_AUTH_SECRET`	Run time. Read on the server for every API call
`DEPLOYMENT_VERSION`	Build time. The commit SHA in the workflows
`NEXT_SERVER_ACTIONS_ENCRYPTION_KEY`	Build time. Keeps server action payload encryption stable across instances of one release
`MARKETING_URL`	Development only
`DATABASE_URL`, `BETTER_AUTH_SECRET`	Not read by web code at run time. See the note below

The Dockerfile and both workflows still pass DATABASE_URL and BETTER_AUTH_SECRET into the build. No code in apps or packages reads either. In dev.yml, BETTER_AUTH_SECRET is only used as the input for deriving the server actions encryption key. The Dockerfile supplies obvious placeholders for both.

SERVICE_AUTH_SECRET must match the core API’s value, or every signed call fails.

The Docker image

frontend/Dockerfile is a two stage build on node:22-bookworm-slim. Builder:

corepack enable, copy the repo, pnpm install --frozen-lockfile.
Take NEXT_PUBLIC_SAAS_URL, NEXT_PUBLIC_SITE_URL and CORE_API_URL as build arguments.
pnpm build (both apps through Turborepo).
pnpm --filter=marketing build, then copy the export into apps/saas/public/mkt and mkt-assets.

Runner:

Copy .next/standalone, .next/static and public.
Set NODE_ENV=production, PORT=3043 and a HOSTNAME that binds all interfaces inside the container.
CMD ["node", "apps/saas/server.js"].

.dockerignore excludes node_modules, .next, .turbo, .git, .github, env files and logs.

Workflows

Three files in .github/workflows.

File	Trigger	What it does
`ci.yml`	Pull requests, and pushes to branches other than `dev` and `main`	Boundary check, type-check, lint, tests. See Tooling
`deploy-do.yml`	Push to `dev`, or manual	Builds the Docker image, pushes it to the GitHub container registry tagged `latest` and with the commit SHA, then pulls and restarts it on the server with Docker Compose
`dev.yml`	Manual only (`workflow_dispatch`)	The older release flow: builds on the runner, packages a tarball and installs it under PM2 with symlinked releases

deploy-do.yml passes the public production URLs as build arguments: the app at https://app.byperform.co.il and the API at https://perform-api.otherwise.co.il. It uses a concurrency group per ref, so a newer push cancels an in flight deploy. So a push to dev deploys through Docker. main has no deploy workflow in this repo.

The PM2 flow (`dev.yml`)

Kept for manual use. In order:

Install, derive NEXT_SERVER_ACTIONS_ENCRYPTION_KEY (a SHA-256 of a fixed prefix plus BETTER_AUTH_SECRET, masked in the log), type-check, build.
Package: standalone output, static files, public, the marketing export, the deploy/ scripts and ecosystem.config.cjs, into one tarball named with a UTC timestamp.
Upload with a checksum comparison on both ends and up to three attempts. A truncated upload can otherwise exit zero and only fail later at extraction.
On the server: extract into releases/<id>/, run deploy/dev/release.sh <id>.

deploy/dev/ scripts:

Script	Role
`release.sh`	Links the shared `.env` into the release, swaps the `current` symlink atomically, reloads PM2, runs the health check and rolls back if it fails, then prunes
`rollback.sh`	Points `current` at a previous release and reloads
`health-check.sh`	Polls the local server, 15 attempts 2 seconds apart by default. Overridable with `HEALTH_URL`, `ATTEMPTS`, `DELAY`
`prune.sh`	Keeps the newest 5 releases (`KEEP`)

ecosystem.config.cjs defines one PM2 app, byperform-app, running apps/saas/server.js in fork mode with one instance, --env-file=.env, a 1 GB memory restart limit and PORT 3043.

No database step

Neither workflow touches a database. The web app has no schema of its own any more. Auth and billing tables are owned by the core API.

Local production run

cd frontend
pnpm build
./dev.sh

dev.sh loads .env and starts node apps/saas/server.js on port 3010. Copy .next/static and public into the standalone tree first if you need assets to load, as the release packaging does.

Checklist before a release

pnpm type-check, pnpm lint and pnpm test pass.
Translations for new keys exist in en and he.
If the mobile app changed, the trainee preview bundle under apps/saas/public/trainee-preview was re-exported. See Trainee app previews.
If the oRPC router changed in the backend, orpc-router.generated.d.ts matches it.
If the plan catalog changed in the backend, packages/payments/config.ts matches it.
The core API release that the web build expects is already deployed. The web app is useless without a compatible API.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Build and deploy

The standalone build

Build time and run time variables

The Docker image

Workflows

The PM2 flow (`dev.yml`)

No database step

Local production run

Checklist before a release

​The standalone build

​Build time and run time variables

​The Docker image

​Workflows

​The PM2 flow (dev.yml)

​No database step

​Local production run

​Checklist before a release

The standalone build

Build time and run time variables

The Docker image

Workflows

The PM2 flow (`dev.yml`)

No database step

Local production run

Checklist before a release