Deploy an app from a monorepo

Before you start

• Commit the monorepo lockfile, such as bun.lock, package-lock.json, or pnpm-lock.yaml.
• Know where the deployable app lives, such as apps/web or services/api.
• Know whether dependency install must run from the app folder or the repository root.
• Make sure the app listens on the PORT environment variable if it serves HTTP traffic.

Option 1: app folder as root directory

Use this when the app folder contains the files needed to install, build, and start the app, such as its own package.json and lockfile or a self-contained backend project.

root directory: apps/web
install command: bun install
build command: bun run build
start command: bun run start
health check path: /

This is the simplest setup when the app can be built independently from the rest of the repository.

Option 2: repository root with targeted commands

Use this when dependencies, workspace config, or shared packages live at the repository root. Keep root directory as ./, then target the app in your commands.

root directory: ./
install command: bun install
build command: bun --filter @acme/web build
start command: bun --filter @acme/web start
health check path: /

Replace @acme/web with the package name from the app's package.json. For npm or pnpm workspaces, use the equivalent workspace command your repository already uses.

Deploy multiple apps from one repo

Create one Shiprr app per deployable service. For example, a monorepo with a web app and an API should usually become two Shiprr apps with separate runtime settings, env vars, domains, logs, and rollback history.

web app root directory: apps/web
api app root directory: services/api

This keeps scaling and rollback independent for each service.

Environment variables

Add runtime values under App → Settings → Environment variables. Env vars are configured per Shiprr app, so the frontend and API can have different secrets and public config.

DATABASE_URL=postgres://...
PUBLIC_API_BASE_URL=https://api.example.com
NODE_ENV=production

Saving env vars redeploys the app so new values apply to live replicas.

Health checks

Set a health check path for each app that serves traffic. For web apps, / is often enough. For APIs, use a lightweight endpoint such as /health.

• The health endpoint should not require login.
• It should return a 2xx status when the app is ready.
• It should be fast enough to respond during deploy startup.

Deploy

1. Open the dashboard and choose Apps → New app.
2. Select the monorepo repository and branch.
3. Choose the root directory or keep ./ with targeted commands.
4. Confirm install, build, start command, health check path, resources, and env vars.
5. Create and deploy the app.

If the build cannot find shared packages, switch to the repository-root setup and use targeted commands.

Verify and debug

• Use build logs when workspace install, package resolution, or build scripts fail.
• Use runtime logs when the app starts and then crashes.
• Check root directory first if the build says a project file cannot be found.

After the default Shiprr hostname works, attach a custom domain from the app's Domains page.

Rollback

Rollback is per Shiprr app. If a web release breaks, rolling back the web app does not roll back the API app, database contents, or external services.