Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

How the Heroku Platform Works

Follow a request through the Heroku router to your dynos, see how code becomes a slug, and learn the twelve-factor habits that make an app fit the platform.

Before you deploy anything, it pays to know what happens between a visitor typing your address and your code answering. Heroku has a small number of moving parts, and nearly every surprising behavior (a restart wiping a file, a request timing out after 30 seconds, an app that works locally but fails to bind a port) comes from one of them.

This lesson draws the whole picture: the life of a request, the life of a deploy, and the style of application, called twelve-factor, that the platform is designed to run.

The life of a request

Your app's address, such as demo-shop-1234.herokuapp.com or your own custom domain, points at Heroku's routers, not at your dynos. A router is a shared piece of infrastructure that receives the request, finds the dynos of the right app, and forwards the request to one of the web dynos.

flowchart LR
  U["Browser"] --> R["Heroku router<br/>(TLS, routing)"]
  R --> W1["web.1 dyno"]
  R --> W2["web.2 dyno"]
  W1 --> D[("Postgres add-on")]
  W2 --> D
  Q["worker.1 dyno"] --> D

A request enters through the router and is handed to a web dyno. Worker dynos receive no HTTP traffic.

Three facts follow from this design:

  1. TLS ends at the router. Your app receives plain HTTP from the router. The original protocol is available in the X-Forwarded-Proto header, and your framework needs to be told to trust it (for example when redirecting to HTTPS).
  2. Only web dynos get traffic. A dyno receives HTTP only if its process type is named web. Worker and other process types are never routed to.
  3. Your app must listen on the port Heroku gives it. The router connects to the port stored in the PORT environment variable, which changes from dyno to dyno. Hard-coding 3000 or 8000 makes the dyno fail to start properly: Heroku waits 60 seconds for it to bind $PORT and reports a boot timeout (error R10) if it never does.

The router also enforces a 30-second limit on a single request: if your app has not started sending a response within 30 seconds, the router gives up with an H12 error. Long work belongs in a background worker, not in a web request.

The life of a deploy

Deploying turns source code into running dynos in a few stages:

From code to running app

Push Your code arrives at Heroku.
Build Buildpacks install dependencies.
Slug The result is compressed.
Release A new version is created.

Old dynos are replaced by new ones.

1 / 2

The build runs in a temporary environment: a buildpack detects your language, installs dependencies, and compiles anything that needs compiling. The output is the slug, a compressed archive of your app, its dependencies and its runtime (limited to 500 MB after compression). A release combines that slug with the current config vars and add-ons, and Heroku starts new dynos from it. When the new dynos are up, the old ones are shut down.

Because the slug is immutable, anything your app writes to disk afterward is not part of it, which is why the filesystem is ephemeral.

Twelve-factor, in plain words

Heroku's founders described a style of application, the twelve-factor app, that runs well on a platform like this. You do not need to memorize all twelve to benefit. The habits that matter most in day-to-day work are:

  • Codebase. One repository per app, deployed many times (staging, production).
  • Dependencies. Declared in a file (package.json, requirements.txt, Gemfile), never assumed to exist on the machine.
  • Config. Stored in the environment, not in code. This is what config vars are.
  • Backing services. A database or queue is attached by URL; swapping one for another is a config change.
  • Build, release, run. Three separate stages, which are exactly what happens on every deploy.
  • Processes. Apps are stateless; anything that must last goes into a backing service.
  • Port binding. The app creates its own web server and listens on $PORT.
  • Concurrency. You scale by running more processes, not bigger ones.
  • Disposability. Processes start fast and stop gracefully; they can be killed at any time.
  • Dev/prod parity, logs and admin processes. Keep environments similar, write logs to standard output, and run one-off tasks in the same environment as the app.

Stand-in: a router that spreads requests

The real router chooses dynos using its own algorithm, and you should not rely on any particular order. This stand-in uses simple round-robin to show what "more dynos share the load" means.

Python Stand-in: round-robin routing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Ten requests over three dynos cannot divide evenly; the first dyno gets one extra. A real router balances in a similar spirit, but you should write your app so that any dyno can answer any request.

Stand-in: a twelve-factor self-check

The checklist below turns a few of the habits above into questions a tool could answer about a project. It is a teaching model, not an official Heroku checker.

Python Stand-in: a tiny twelve-factor scorecard

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Each failing line points to a lesson in this course: secrets belong in config vars, $PORT is explained in deploying your first app, and uploads need a place other than the dyno's disk.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which part of the platform receives the visitor's request first?

    Requests reach the router, which terminates TLS and forwards the request to one of the app's web dynos.
  2. 2. Why must a web process listen on the PORT environment variable?

    The port differs between dynos, and the platform tells your process which one to use through $PORT. If the process never binds it, the dyno fails to boot.
  3. 3. What is a slug?

    The build stage produces a slug containing the app, its dependencies and runtime. Releases combine a slug with config.
  4. 4. Which twelve-factor habit explains why settings should not live in your source code?

    Keeping config in the environment lets the same code run in staging and production with different settings.
  5. 5. A request takes 45 seconds to produce its first byte. What will the router do?

    The router enforces a 30-second limit; slow work should be moved to a background worker.

Summary

  • Requests flow browser, then router, then a web dyno; TLS ends at the router and the app must bind $PORT.
  • Deploys flow code, build, slug, release, new dynos; a slug is an immutable build.
  • Twelve-factor habits (config in the environment, stateless processes, logs to stdout) are what the platform expects.
  • The router allows about 30 seconds before the first response byte, so long jobs go to workers.

Next: Install the CLI and log in