Set Up Preview Environments

Preview environments spin up a live, isolated deployment for every pull request. Reviewers get a real URL to click instead of pulling the branch and running it locally. When the PR is merged or closed, the preview is torn down automatically.

Prerequisites

• A running Vardo instance (installation guide)
• GitHub connected to Vardo (setup instructions)
• An app already deployed from a GitHub repo

---

How it works

1. You open a PR on GitHub
2. GitHub sends a webhook to Vardo
3. Vardo clones the PR branch, builds and deploys it as a temporary app
4. The preview gets its own subdomain — e.g., pr-42.my-app.vardo.example.com
5. Vardo posts the preview URL as a comment on the PR
6. When the PR is merged or closed, Vardo tears down the preview and cleans up

The preview app inherits environment variables from the parent app, so it works out of the box for most setups.

---

1. Enable preview environments on your app

1. Open your app's detail page

2. Go to the Settings tab

3. Under Preview Environments, toggle it on

4. Configure the options:

   Setting	Description	Default
   Branch filter	Only create previews for PRs targeting this branch	main
   Subdomain pattern	Template for preview URLs	pr-{{number}}.{{app}}
   Auto-destroy	Tear down when PR is merged/closed	On
   Expiry	Destroy idle previews after this duration	7 days

5. Click Save

That's it. The GitHub App webhook already receives PR events — Vardo starts listening for them on this app.

---

2. Open a pull request

Create a PR against the configured branch. Within a minute or two, you'll see:

1. A deployment status on the PR — "Deploying preview..."
2. A comment from your GitHub App with the preview URL once the build completes
3. The GitHub deployment status updates to "Active" with a link to the preview

Click the URL. It's a fully running instance of your app built from the PR branch.

---

3. Preview environment variables

Previews inherit all environment variables from the parent app by default. You can override specific variables for preview environments:

1. Open your app's Environment tab
2. Click Preview overrides
3. Add or change variables — for example:

   DATABASE_URL=postgresql://user:pass@db:5432/myapp_preview
   APP_ENV=preview
   BASE_URL=https://pr-{{number}}.my-app.vardo.example.com

4. Click Save

The {{number}} template variable gets replaced with the PR number at deploy time.

Tip: Use a separate database for previews so they don't touch production data. You can create a shared preview database or let each preview use an ephemeral SQLite/in-memory database if your app supports it.

---

4. Seeding preview databases

If your previews need seed data, add a post-deploy command in the preview settings:

1. Under Preview Environments settings, find Post-deploy command
2. Add your seed command:

   rails db:seed

   or for Node.js apps:

   npx prisma db seed

3. This runs inside the preview container after the app starts

---

5. Customizing preview URLs

The default subdomain pattern is pr-{{number}}.{{app}} — so PR #42 on an app called my-app gets pr-42.my-app.vardo.example.com.

Available template variables:

You can customize the pattern to whatever works for your team:

• preview-{{number}}.{{app}} → preview-42.my-app.vardo.example.com
• {{branch}}.{{app}} → feat-login.my-app.vardo.example.com

---

Resource management

Preview environments consume server resources. A few things to keep in mind:

• Expiry — set a reasonable expiry (default 7 days) so stale previews get cleaned up
• Concurrency — by default, Vardo limits previews to 5 per app. Adjust under Preview Environments → Max concurrent
• Resource limits — previews use the same resource limits as the parent app. Override them in preview settings if you want to give previews less CPU/memory

---

Troubleshooting

Preview not created after opening a PR

Check that:

• Preview environments are enabled on the app
• The PR targets the configured branch (usually main)
• The GitHub App has access to the repo — check Settings → Integrations → GitHub
• Webhook deliveries are succeeding — check your repo's Settings → Webhooks

---

Preview build fails

Open the preview's build log in Vardo. Common issues:

• Missing environment variables — check your preview overrides
• Branch has merge conflicts — resolve them in the PR
• Dockerfile uses features the preview runner doesn't support

---

Preview URL shows 404

The preview container might still be starting. Give it a minute. If it persists, check the container logs — the app might be crashing on startup due to missing config.

---

"Too many preview environments"

You've hit the concurrency limit. Close old PRs or increase the limit under Preview Environments → Max concurrent.

---

Next steps

• Set up custom domains for production
• Configure backups for your databases
• Add deployment notifications under Settings → Notifications so your team knows when previews are ready