Sefism is free for learners. We are here to help you grow, one step at a time.Join for free
Sefism.
Cloud & DevOps

Pull Request Preview Environments on One Server with Sleep and Wake

A self-hosted tool that gives every pull request its own full-stack preview environment, app plus seeded database, on one affordable server, by sleeping idle previews and waking them on the first request. An intermediate cloud and DevOps final year project for small teams that cannot afford a staging server per branch.

Topics
Difficulty

Intermediate

A small team, or one strong student willing to learn something new.
Effort

2 semesters · 2 to 3 students

Deliverables

6 to ship

3 optional extras

Suggested stack

Go or Node.jsDocker and Docker ComposeTraefikGitHub App webhooksPostgreSQL templatesWildcard DNS and TLS
A suggestion, not a requirement. Swap anything for what you already know.

What you should ship

  • A GitHub App that creates a preview on pull request open, updates it on push and deletes it on close or merge, posting the preview URL as a PR comment.
  • Per-preview Compose stacks with isolated networks, a unique subdomain and a wildcard TLS certificate.
  • Database seeding from a sanitised template database, cloned per preview rather than restored from scratch, with the seeding time measured.
  • Sleep and wake: previews idle for a set time are stopped, and the first HTTP request wakes them while showing a short "starting" page.
  • Resource limits per preview and a server-wide budget that refuses or queues new previews when memory is exhausted, with a clear message on the PR.
  • An evaluation of density (active and sleeping previews per server), cold start time and cost compared with always-on previews.

If you have time left

  • A data sanitising step that turns a production snapshot into a safe template by masking personal fields with rules the team defines.
  • Automatic smoke tests against each preview with the result reported as a PR check.
  • Support for a second server with simple placement by free memory.

The problem: one staging server, five people waiting

Most small teams have one staging environment. Two developers push to it on the same afternoon, one overwrites the other, and the product manager reviews the wrong change. The fix is a preview environment per pull request: a live URL for every branch, with its own database, destroyed when the branch merges. Heroku popularised this as Review Apps, and frontend platforms made it standard for static sites.

For full-stack apps with a backend and a database, previews are either expensive (a hosted environment per branch, billed per hour) or complicated (a Kubernetes cluster). A small software house with one decent VPS cannot run ten copies of its stack all the time, but it rarely needs ten running at once: most previews sit idle most of the day.

What already exists and the gap

  • Vercel and Netlify create previews per pull request for frontend and serverless apps, not for a backend with its own database.
  • Coolify and Dokploy, self-hosted platforms, support pull request previews on your own server, though per-preview database set-up is left to you.
  • Bunnyshell, Qovery and Northflank offer full-stack preview environments on managed Kubernetes, priced as commercial platforms.
  • Neon and similar services offer database branching for PostgreSQL in their own cloud.

The gap is full-stack previews with a seeded database per PR on one self-hosted server, made affordable by scale-to-zero, the same idea behind machines that stop when idle and start on request on platforms like Fly.io.

What you build

  • Controller: receives GitHub webhooks, builds images, generates a Compose project per PR with unique names, networks and a subdomain, and records state.
  • Router: Traefik routes each subdomain to its stack. When a preview is asleep, requests go to a small waker service that starts the stack and holds or redirects the request.
  • Database seeding: PostgreSQL template databases let you create a per-preview database from a sanitised template quickly; document how this compares with restoring a dump.
  • Lifecycle and budget: idle detection from router access logs, sleep after a timeout, delete on merge, and a memory budget with queueing.
  • Feedback: PR comments with the URL, status and logs link.

The technically interesting part

Sleep and wake is the core. You need to detect idleness reliably, stop a stack without losing state it needs, and on the first request start containers, wait for health checks and then forward the request, all within a cold start users will tolerate. You also need admission control: decide what happens when a fifth preview wakes and memory is full (evict the least recently used? refuse?). Show evaluators cold start timings broken down by phase (container start, app boot, migrations) and the eviction policy under a simulated busy day.

How to evaluate it

  • Density: maximum number of previews (awake plus asleep) a given server supports for a sample app, with and without sleep.
  • Cold start: time from first request to a served page, median and 95th percentile, for two sample stacks.
  • Seeding: time to create a preview database from a template versus a dump restore, for small and medium datasets.
  • Cost: monthly cost of your approach versus a hosted per-branch environment for a typical team's PR volume, with assumptions stated.
  • User study: a small team uses it for three weeks; record review turnaround and the problems they hit.

Suggested plan

  1. Semester 1, weeks 1 to 4: GitHub App, webhook handling and per-PR Compose generation.
  2. Weeks 5 to 9: Traefik routing, wildcard DNS and TLS, PR comments.
  3. Weeks 10 to 14: database templates and seeding; mid-project demo.
  4. Semester 2, weeks 1 to 6: idle detection, sleep and wake, admission control.
  5. Weeks 7 to 10: pilot with a real team.
  6. Weeks 11 to 14: measurements and write-up.

Path to a product

The first customer is a software house building client web apps that reviews work with clients and currently shares a single staging server. Sell a one-time licence per server or a small monthly subscription, and offer set-up as a service. Agencies that demo work to clients before approval feel this pain most, in Pakistan and anywhere else client work is common.

Scope warning

Do not support Kubernetes, multiple Git hosts or arbitrary databases in the first version. PostgreSQL and GitHub are enough. Do not build a general PaaS with app management screens. Keep production data out of previews unless your sanitising step is tested.

Learn what you need on Sefism

Get help with this idea

Bring your sleep and wake design and your admission policy to a mentor before you start coding them. A mentor can help you set the scope, pick a stack you can finish with, and design an evaluation your examiners will respect. The build is yours; the guidance is on scope, stack and evaluation. New here? Create a free account first.

Ideas and guidance, not finished projects

These are project ideas and scoping guidance, published free for students to use as a starting point. I do not build, write, or sell final-year projects, and I do not complete coursework for anyone. Take an idea, make it yours, and build it.

Not sure this one fits you?

I help students pick an idea that matches their skills and their deadline, then scope it down until it is finishable. Guidance only, never done for you.

Discuss this idea
Work with me

Stuck on something specific?

Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.

Book a free sessionSee all services

Follow along

New writing, resources and project ideas land here first.