Migrate a Heroku app to exe.dev

Create the VM#

On your computer, create a VM with room for the database, Heroku's backup of it, and two weeks of nightly backups: about five times the size heroku pg:info shows, plus 10 GB. Pick another name if my-app is taken:

ssh exe.dev new --name=my-app --disk=40GB

Then hand over the app. Everything below runs on the VM, as exedev: ssh my-app.exe.xyz.

Read the hand-over#

~/heroku holds what Heroku said about the app, and ~/app.git its code. config.json, dyno.txt, and db-url.txt hold secrets: read them, but keep their values out of anything you write or say.

• info.json: the stack and generation (cedar or fir), the region, web_url, and the add-ons. An app that deploys a Docker image says container: run it with Docker Compose instead of the build below.
• ps.json and the Procfile: the process types, and how many of each.
• addons.json: each add-on and the config vars it set. Sort them with the add-on table in Where everything goes.
• config.json: the config vars. dyno.txt: the same plus what the buildpacks set, then the language versions Heroku runs.
• domains.json, pg-info.txt (the Postgres version and size), scheduler.txt, and releases.json.

Check the code is the commit Heroku runs: the newest release in releases.json says Deploy 1a2b3c4d, and this should match:

git -C ~/app.git log -1 --format='%h %s' main

Write down where Heroku serves the app, and the pages to compare: /, a page that reads the database, a static file, a missing page. Only pages that just read: the comparison asks Heroku too.

echo https://www.example.com > ~/heroku/source-url
printf '%s\n' / /pricing /static/logo.png /no-such-page > ~/heroku/paths.txt

Use the first custom domain in domains.json, or else web_url from info.json.

Install PostgreSQL and Valkey#

Set up PostgreSQL as the PostgreSQL recipe's "Install by hand" does, on this VM: every step from "Install PostgreSQL 18 and pgvector" to "Test a backup", but skip "Add a web admin", or put Adminer on port 8001 as that step says, since port 8000 is the app's. That gives you PostgreSQL 18 with an en_US.UTF-8 cluster like Heroku's, an app database with its URL in ~/postgres/app.env, and nightly backups of it in ~/postgres/backups. pg_restore 18 reads backups from any Heroku Postgres version, and SSL is on, with a self-signed certificate, so apps that insist on sslmode=require, as many Heroku apps do, connect unchanged.

Then Valkey, the open-source fork of Redis that Heroku Key-Value Store runs too, and the headers that Ruby's and Python's database drivers build against. Skip Valkey if the app has no Key-Value Store or Redis add-on:

sudo apt-get install -y valkey-server build-essential libpq-dev libyaml-dev

Install the language#

Install what the buildpacks in info.json installed, at the versions at the end of dyno.txt:

• Python: nothing to install. The deploy uses uv, which is already here and fetches the Python in .python-version. If the app has no .python-version, set UV_PYTHON in vm.env below to the version Heroku ran.
• Ruby, Node.js, and others: mise installs any version in seconds, from prebuilt binaries. Name each language the app uses, at the version from dyno.txt:

curl -fsSL https://mise.run | sh
~/.local/bin/mise use -g ruby@3.4.9 node@24.22.0

If package.json names an npm version in engines, Heroku installed that npm, so install it once too:

PATH=~/.local/bin:~/.local/share/mise/shims:$PATH npm install -g npm@12

PHP, Go, and Java apps need their own build steps in the deploy hook below; ask the owner before taking them on.

Write the config#

~/app.env holds the config vars, in place of Heroku's. It's made from two files: Heroku's config.json, and ~/heroku/vm.env, the VM's own settings, which win. Write vm.env, with the database URL from ~/postgres/app.env:

cat > ~/heroku/vm.env <<EOF
# The VM's own settings. They win over Heroku's config vars in ~/app.env.
PORT=8000
PATH=/home/exedev/app/.venv/bin:/home/exedev/app/node_modules/.bin:/home/exedev/app/bin:/home/exedev/.local/share/mise/shims:/home/exedev/.local/bin:/usr/local/bin:/usr/bin:/bin
$(cat ~/postgres/app.env)
REDIS_URL=redis://localhost:6379
WEB_CONCURRENCY=$(nproc)
EOF
chmod 600 ~/heroku/vm.env

Then add to vm.env what the buildpack set on Heroku: the lines of dyno.txt that aren't config vars, such as SECRET_KEY_BASE (Ruby's buildpack made one if you didn't, and it signs sessions), RAILS_ENV, NODE_ENV, LANG, PYTHONUNBUFFERED, and FORWARDED_ALLOW_IPS=*, without which gunicorn ignores X-Forwarded-Proto. Leave out Heroku's own: HOME, PATH, PORT, DYNO, PS1, WEB_CONCURRENCY, and paths into /app.

This writes ~/app.env, with the URLs of Heroku's Postgres and Key-Value Store pointing at the VM's own:

cat > ~/heroku/make-env <<'EOF'
#!/usr/bin/env python3
# ~/heroku/make-env: write ~/app.env from Heroku's config vars (~/heroku/config.json),
# then the VM's own settings (~/heroku/vm.env), which win. The URLs of Heroku's
# Postgres and Key-Value Store point at the VM's own instead.
import json, os, re
home = os.path.expanduser("~")
config = json.load(open(f"{home}/heroku/config.json"))
vm = {}
for line in open(f"{home}/heroku/vm.env"):
    if "=" in line and not line.startswith("#"):
        k, v = line.rstrip("\n").split("=", 1)
        vm[k] = v
env, moved = dict(config), []
for k in config:
    if re.fullmatch(r"DATABASE_URL|HEROKU_POSTGRESQL_\w+_URL", k):
        env[k] = vm["DATABASE_URL"]; moved.append(k)
    elif re.fullmatch(r"REDIS_URL|REDIS_TLS_URL|HEROKU_REDIS_\w+_URL|HEROKU_REDIS_\w+_TLS_URL", k):
        env[k] = vm["REDIS_URL"]; moved.append(k)
env.update(vm)
quote = lambda v: '"' + v.replace("\\", "\\\\").replace('"', '\\"') + '"'
fd = os.open(f"{home}/app.env", os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w") as f:
    f.write("# Heroku's config vars, then the VM's own (heroku/vm.env).\n"
            "# Edit freely, then: ~/app.git/hooks/pre-receive main\n")
    f.writelines(f"{k}={quote(v)}\n" for k, v in env.items())
print(f"Wrote ~/app.env: {len(env)} vars. Now on the VM: {', '.join(moved) or 'nothing'}")
EOF
chmod +x ~/heroku/make-env && ~/heroku/make-env

The services set DYNO, as Heroku did, so code that checks for Heroku that way, to trust its proxy or force HTTPS, behaves as it did there. Every other config var stays as it was, so the app here uses the same mail, storage, and monitoring services as on Heroku.

Run like a dyno#

Two small commands stand in for Heroku's dyno manager. app-run runs a command the way heroku run did, and procfile-run starts a Procfile line, for the services:

sudo tee /usr/local/bin/app-run > /dev/null <<'EOF'
#!/bin/bash
# app-run: what `heroku run` did. Runs a command in ~/app as exedev with
# ~/app.env loaded exactly the way the app*.service units load it.
#   app-run bash      app-run python manage.py shell      app-run bin/rails console
tty=--pipe; [ -t 0 ] && [ -t 1 ] && tty=--pty
exec sudo systemd-run --quiet --collect --wait "$tty" --uid=exedev --gid=exedev \
  -p WorkingDirectory=-/home/exedev/app -p EnvironmentFile=/home/exedev/app.env \
  -E HOME=/home/exedev -E DYNO=run.1 -- /usr/bin/env "$@"   # env: find "$@" on app.env's PATH
EOF
sudo tee /usr/local/bin/procfile-run > /dev/null <<'EOF'
#!/bin/bash
# procfile-run TYPE: start the Procfile's TYPE line the way a dyno does
cmd=$(sed -n "s/^$1:[[:space:]]*//p" /home/exedev/app/Procfile)
[ -n "$cmd" ] || { echo "Procfile has no '$1:' line" >&2; exit 1; }
exec bash -c "$cmd"
EOF
sudo chmod +x /usr/local/bin/app-run /usr/local/bin/procfile-run

The deploy hook#

git push exe main runs this hook, which does what Heroku's build and release did, before Git accepts the push. Like Heroku, it rejects the push if any step fails, so main is always what runs. Each deploy builds in a new directory under ~/releases, and ~/app points at the one that runs. Until the first deploy below, pushes only store the code:

cat > ~/app.git/hooks/pre-receive <<'EOF'
#!/usr/bin/env bash
# ~/app.git/hooks/pre-receive: what `git push heroku main` did. Builds the
# commit in ~/releases/<time>-<commit> as the buildpacks did, runs the
# Procfile's release: line, points ~/app at it, restarts the app*.service
# units and checks the web process answers. If anything fails, it puts the
# previous release back and rejects the push, so main is what runs.
# Redeploy by hand (after editing ~/app.env, say): ~/app.git/hooks/pre-receive main
set -euo pipefail
export GIT_DIR=$HOME/app.git
rev='' head=''
if [ $# -gt 0 ]; then
  rev=$(git rev-parse --verify "$1^{commit}")
else
  while read -r old new ref; do
    case $ref in refs/heads/main|refs/heads/master) rev=$new base=$old head=$ref ;; esac
  done
  [ -n "$rev" ] || { echo "Not deployed: push main (or master) to deploy."; exit 0; }
  case $rev in *[!0]*) ;; *) echo "Refusing to delete the deployed branch."; exit 1 ;; esac
  [ -L "$HOME/app" ] || { echo "Stored ${rev:0:7}. Not deployed: no first deploy yet."; exit 0; }
fi

exec 9>"$HOME/.deploy.lock" && flock 9  # one deploy at a time
if [ -n "$head" ]; then
  now=$(git rev-parse -q --verify "$head" || true)
  [ "${now:-$base}" = "$base" ] || { echo "Another push deployed first: pull, then push again."; exit 1; }
fi
release=$HOME/releases/$(date -u +%Y%m%d-%H%M%S)-${rev:0:7}
previous=$(readlink "$HOME/app" || true)
units=$(systemctl list-unit-files --state=enabled --plain --no-legend 'app*.service' | cut -d' ' -f1)
restart() {  # reset-failed: a unit that just crash-looped refuses restarts for 10s
  for unit in $units; do sudo systemctl reset-failed "$unit"; sudo systemctl restart "$unit"; done
}
fail() {  # put the previous release back, and reject the push
  trap - ERR
  echo "-----> Deploy FAILED${1:+: $1}. Running: ${previous:-nothing}"
  if [ -n "$previous" ] && [ "$(readlink "$HOME/app")" != "$previous" ]; then
    ln -sfn "$previous" "$HOME/app.new" && mv -T "$HOME/app.new" "$HOME/app"
    restart
  fi
  rm -rf "$release"
  exit 1
}
trap fail ERR

echo "-----> Building ${rev:0:7} in $release"
mkdir -p "$release"
git archive "$rev" | tar -x -C "$release"
app-run bash -euo pipefail -s "$release" <<'BUILD'
cd "$1"
export PATH=$PWD/.venv/bin:$PWD/node_modules/.bin:$PWD/bin:$PATH
if command -v mise >/dev/null; then mise install --quiet; fi  # ~/.config/mise/config.toml
if [ -f package.json ]; then                      # what heroku/nodejs did
  npm ci --include=dev
  if grep -q '"heroku-postbuild"' package.json; then npm run heroku-postbuild
  else npm run --if-present build; fi
  npm prune --omit=dev
fi
if [ -f Gemfile.lock ]; then                      # what heroku/ruby did
  bundle config set --local deployment true
  bundle config set --local without development:test
  bundle config set --local path "$HOME/.gems"
  bundle install --quiet
  if bundle exec rake -P 2>/dev/null | grep -q '^rake assets:precompile'; then
    bundle exec rake assets:precompile
  fi
fi
if [ -f requirements.txt ] || [ -f uv.lock ]; then  # what heroku/python did
  uv venv --quiet .venv
  if [ -f uv.lock ]; then uv sync --quiet --locked --no-dev
  else uv pip install --quiet -r requirements.txt; fi
  if [ -f manage.py ] && [ -z "${DISABLE_COLLECTSTATIC:-}" ]; then
    python manage.py collectstatic --noinput
  fi
fi
BUILD
if grep -q '^release:' "$release/Procfile"; then
  echo "-----> Release phase"
  app-run bash -euo pipefail -s "$release" <<'RELEASE'
cd "$1"
export PATH=$PWD/.venv/bin:$PWD/node_modules/.bin:$PWD/bin:$PATH
exec bash -c "$(sed -n 's/^release:[[:space:]]*//p' Procfile)"
RELEASE
fi

echo "-----> Starting the new release"
ln -sfn "$release" "$HOME/app.new" && mv -T "$HOME/app.new" "$HOME/app"
restart
code=none
if grep -q '^web:' "$release/Procfile"; then
  for _ in $(seq 60); do
    code=$(curl -s -o /dev/null -m 10 -w '%{http_code}' http://localhost:8000/ || true)
    case $code in 000|5??) sleep 1 ;; *) break ;; esac
  done
fi
case $code in 000|5??) fail "it answers HTTP $code (journalctl -u app -n 50)" ;; esac
trap - ERR
ls -1d "$HOME"/releases/*/ | head -n -3 | xargs -r rm -rf  # keep 3
echo "-----> Deployed ${rev:0:7}: HTTP $code on port 8000"
EOF
chmod +x ~/app.git/hooks/pre-receive

The build steps follow the buildpacks: npm ci with dev dependencies, then heroku-postbuild or build, then pruning; bundle install and assets:precompile; a virtualenv from uv.lock or requirements.txt, and Django's collectstatic. Apps that use Poetry or Pipenv need uv pip install . or pipenv in its place. If the app has build hooks (bin/post_compile, heroku-prebuild, heroku-cleanup), add them to the build where the buildpack ran them. If the app relies on a buildpack beyond its language's, such as Apt or Chrome, install what it installed here, once.

The services#

Each Procfile line but release becomes a systemd service: web is app.service, the others app-<type>.service. This is web; for a worker, change the description, DYNO=worker.1, and procfile-run worker:

sudo tee /etc/systemd/system/app.service > /dev/null <<'EOF'
[Unit]
Description=Procfile web
After=network.target postgresql.service valkey-server.service

[Service]
User=exedev
WorkingDirectory=/home/exedev/app
EnvironmentFile=/home/exedev/app.env
Environment=DYNO=web.1
ExecStart=/usr/local/bin/procfile-run web
Restart=always

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable app

Heroku Scheduler's jobs become timers. For each line in scheduler.txt, write app-<job>.service and app-<job>.timer, with OnCalendar=*:0/10 for every 10 minutes, *:15 for hourly at :15, or *-*-* 03:00 UTC for daily at 03:00. Heroku stopped a job when its next one was due; TimeoutStartSec, set to the interval, does the same:

sudo tee /etc/systemd/system/app-report.service > /dev/null <<'EOF'
[Unit]
Description=Scheduler job: python manage.py report

[Service]
Type=oneshot
User=exedev
WorkingDirectory=/home/exedev/app
EnvironmentFile=/home/exedev/app.env
Environment=DYNO=scheduler.1
ExecStart=/bin/bash -c 'python manage.py report'
TimeoutStartSec=10min
EOF
sudo tee /etc/systemd/system/app-report.timer > /dev/null <<'EOF'
[Unit]
Description=Every 10 minutes, like Heroku Scheduler

[Timer]
OnCalendar=*:0/10

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload

Workers and timers stay off until the move, so jobs don't run twice and the VM doesn't pull from Heroku's queues. List them in ~/heroku/held, one per line, for move to start:

printf '%s\n' app-worker.service app-report.timer > ~/heroku/held

Want more than one of a process, as ps.json may show? Raise WEB_CONCURRENCY for web. For workers, most queue libraries take a concurrency setting; or copy the unit to app-worker2.service.

Restore the database#

This restores a Heroku Postgres backup into the app's database: from the link in db-url.txt, a file, or a postgres:// URL to dump from. It runs the PostgreSQL recipe's restore as one command, for the move: into an empty app database, as the app role made superuser for the duration, since Heroku's dumps create extensions in a heroku_ext schema, which it then keeps on the search path, as Heroku did. It stops at the first error and stops the app while it works:

cat > ~/heroku/restore-db <<'EOF'
#!/bin/bash
# ~/heroku/restore-db SOURCE: replace the app database with a pg_dump -Fc backup,
# in the PostgreSQL recipe's restore order (/deploy/postgres#restore-it), app stopped.
# SOURCE is a file (heroku pg:backups:download, ~/postgres/backups/*/app.dump), the
# https URL from heroku pg:backups:url, or a postgres:// URL to dump from, read-only.
set -euo pipefail
src=${1:?usage: restore-db FILE|https-URL|postgres-URL}
db=app dump=$src
case $src in
  http*)
    dump=$HOME/heroku/latest.dump
    echo "Downloading the backup..."
    curl -fsS --retry 3 -o "$dump" "$src" ;;
  postgres*)
    dump=$HOME/heroku/latest.dump
    echo "Dumping the database, read-only..."
    PGOPTIONS='-c default_transaction_read_only=on' \
      pg_dump --format=custom --no-owner --no-privileges --dbname="$src" --file="$dump" ;;
esac
pg_restore --list "$dump" > /dev/null    # is it a pg_dump -Fc file?
echo "Stopping the app while the database is replaced..."
sudo systemctl stop 'app*.service' 2>/dev/null || true
dropdb --if-exists --force $db
createdb --owner=$db $db
echo "Restoring..."
psql -X -q -d postgres -c "ALTER ROLE $db SUPERUSER"
trap 'psql -X -q -d postgres -c "ALTER ROLE $db NOSUPERUSER"' EXIT
pg_restore --dbname=$db --role=$db --no-owner --no-privileges --exit-on-error --jobs=2 "$dump"
psql -X -q -d postgres -c "ALTER ROLE $db NOSUPERUSER"
trap - EXIT
psql -X -q -d $db -c 'SET client_min_messages = warning; CREATE EXTENSION IF NOT EXISTS vector'
if [ -n "$(psql -X -At -d $db -c "SELECT 1 FROM pg_namespace WHERE nspname = 'heroku_ext'")" ]; then
  psql -X -q -d postgres -c "ALTER DATABASE $db SET search_path = \"\$user\", public, heroku_ext"
fi
vacuumdb --analyze-only --quiet --dbname=$db
for unit in $(systemctl list-unit-files --state=enabled --plain --no-legend 'app*.service' | cut -d' ' -f1); do
  sudo systemctl start "$unit"
done
echo "Restored the database from ${dump##*/}"
EOF
chmod +x ~/heroku/restore-db
~/heroku/restore-db "$(cat ~/heroku/db-url.txt)" && rm ~/heroku/db-url.txt

The link lasts an hour. If it's expired, ask the owner to run heroku pg:backups:url -a my-heroku-app | ssh my-app.exe.xyz 'cat > heroku/db-url.txt'. On Heroku Postgres Advanced, which has no pg:backups, pass the DATABASE_URL from config.json instead: restore-db only reads from it. For a database that has an extension Ubuntu's PostgreSQL lacks, such as PostGIS, install it first: sudo apt-get install -y postgresql-18-postgis-3.

First deploy#

The owner's push only stored the code, so deploy it now. It takes a few minutes the first time, as Heroku's first build did:

~/app.git/hooks/pre-receive main

It ends Deployed 1a2b3c4: HTTP 200 on port 8000, or a redirect. Then open https://my-app.exe.xyz/. exe.dev's proxy sends X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-For, as Heroku's router did, so an app that trusted Heroku's proxy trusts this one. It also has to accept the VM's name: add my-app.exe.xyz where the app lists its hosts (Django's ALLOWED_HOSTS, Rails' config.hosts), through a config var if it reads one.

Back up every night#

Heroku Postgres took backups for you. Here the PostgreSQL steps above already back up every database each night into ~/postgres/backups, keeping 14. Take one now, with Heroku's data in it, and restore it the way heroku pg:backups:restore did, to prove both work:

latest=$(~/postgres/backup.sh)
~/heroku/restore-db "$latest/app.dump"

They're on this VM's disk, so they don't survive losing the VM: copy them somewhere else too, as the PostgreSQL recipe shows.

Check#

This asks Heroku and the VM for each page in paths.txt and compares the status, redirect, and page title. It saves Heroku's answers for after the move, when Heroku shows its maintenance page:

cat > ~/heroku/check <<'EOF'
#!/bin/bash
# ~/heroku/check: ask Heroku and the VM the same questions and compare the answers.
#   ~/heroku/check          live Heroku vs the VM; saves Heroku's answers
#   ~/heroku/check --saved  the VM vs the answers saved last time (Heroku in maintenance)
# Questions are the paths in ~/heroku/paths.txt; an answer is "<status> <redirect> | <title>".
set -uo pipefail
cd ~/heroku
src=$(cat source-url)                  # where the app is served today, e.g. https://www.example.com
host=${src#*://}; host=${host%%/*}
answer() {
  local body head
  body=$(mktemp)
  head=$(curl -s -o "$body" -m 20 -w '%{http_code} %{redirect_url}' "$@")
  echo "$head | $(tr -d '\r\n' < "$body" | grep -o -i -m1 '<title>[^<]*' | head -1 | sed 's/^<title>[[:space:]]*//I')"
  rm -f "$body"
}
for _ in $(seq 30); do curl -s -o /dev/null -m 5 http://localhost:8000/ && break; sleep 1; done  # app starting?
different=0
[ "${1:-}" = --saved ] || : > answers.txt
while read -r path; do
  [ -n "$path" ] || continue
  if [ "${1:-}" = --saved ]; then
    heroku=$(awk -F'\t' -v p="$path" '$1 == p { print $2 }' answers.txt)
  else
    heroku=$(answer "$src$path")
    printf '%s\t%s\n' "$path" "$heroku" >> answers.txt
  fi
  vm=$(answer "http://localhost:8000$path" -H "Host: $host" -H "X-Forwarded-Host: $host" \
       -H "X-Forwarded-Proto: https" -H "X-Forwarded-For: 203.0.113.7")
  if [ "$heroku" = "$vm" ]; then
    echo "same       $path  $vm"
  else
    echo "DIFFERENT  $path"; echo "    Heroku: $heroku"; echo "    VM:     $vm"
    different=$((different + 1))
  fi
done < paths.txt
if [ "$different" = 0 ]; then echo "same: the VM answers like Heroku"; else echo "$different DIFFERENT"; exit 1; fi
EOF
chmod +x ~/heroku/check && ~/heroku/check

DIFFERENT lines show both answers. Fix what's different here, never on Heroku, until every line says same.

Get ready for the move#

move is the owner's: it checks Heroku is in maintenance mode, restores the last backup, starts the held workers and timers, and checks again:

cat > ~/heroku/move <<'EOF'
#!/bin/bash
# ~/heroku/move: the VM takes over from Heroku. The owner runs it after
# `heroku maintenance:on` and scaling the other processes to 0, with the URL
# of a fresh backup:
#   heroku pg:backups:url -a my-heroku-app | ssh my-app.exe.xyz heroku/move
# To give the app back to Heroku, before DNS changes:
#   ssh my-app.exe.xyz heroku/move undo
set -euo pipefail
cd ~/heroku
app=$(python3 -c 'import json; print(json.load(open("info.json"))["app"]["name"])')
src=$(cat source-url)
held=$(grep -v '^#' held || true)   # the workers and timers that wait for the move
if [ "${1:-}" = undo ]; then
  [ -z "$held" ] || sudo systemctl disable --now $held
  scale=$(python3 -c 'import collections, json; print(" ".join(f"{t}={n}" for t, n in collections.Counter(d["type"] for d in json.load(open("ps.json"))).items() if t != "web"))')
  echo "Workers and timers are off here. To bring Heroku back, on your computer:"
  echo "  heroku maintenance:off -a $app"
  [ -z "$scale" ] || echo "  heroku ps:scale $scale -a $app"
  echo "and add the Scheduler jobs back, from ~/heroku/scheduler.txt."
  exit
fi
code=$(curl -s -o /dev/null -m 20 -w '%{http_code}' "$src/" || true)
if [ "$code" != 503 ] && [ "${1:-}" != --anyway ]; then
  echo "Heroku still answers HTTP $code at $src. First: heroku maintenance:on -a $app"
  exit 1
fi
url=
[ -t 0 ] || read -r url || true
if [ -n "$url" ]; then
  ~/heroku/restore-db "$url"
elif grep -q '"DATABASE_URL"' config.json; then
  echo "Pipe in the backup's URL: heroku pg:backups:url -a $app | ssh $(hostname).exe.xyz heroku/move"
  exit 1
fi
[ -z "$held" ] || sudo systemctl enable --now $held
~/heroku/check --saved || echo "Look into the DIFFERENT answers before you change DNS."
vm=$(hostname)
domains=$(python3 -c 'import json; print(" ".join(d["hostname"] for d in json.load(open("domains.json")) if d["kind"] == "custom"))')
echo
echo "The VM has Heroku's data and runs everything. Next, on your computer:"
echo "point your domains at $vm.exe.xyz, then"
for d in $domains; do echo "  ssh exe.dev domain add $vm $d"; done
echo "  ssh exe.dev share set-public $vm"
echo "Changed your mind before the DNS change? Run: ssh $vm.exe.xyz heroku/move undo"
EOF
chmod +x ~/heroku/move

Last, write ~/heroku/report.md for the owner, without secrets:

• What moved: the processes, timers, runtimes and versions, the database (its size, and how long the restore took), and the config vars by name.
• What changed for exe.dev: each line of vm.env, and any change to the build or the app's settings.
• The add-ons: each one, and where it goes, from the table in Where everything goes. Say which keep working through their config vars until the Heroku app is deleted.
• What didn't move, and what to do instead.
• The move: the process types to scale to 0, the Scheduler jobs to delete, each domain with its DNS record now (from domains.json) and the one it needs, and the commands from Make the move with this VM's name and the Heroku app's.

That's the rehearsal. Open https://my-app.exe.xyz/ and look around.

• git push says src refspec main does not match any: your branch is master. Push it as main: git push exe master:main.
• The deploy stops on a missing header or library, such as pg_config or vips.h: Heroku's stack had it installed. Install the Ubuntu package (libpq-dev, libvips-dev) and push again.
• Your Ruby version is 3.4.9, but your Gemfile specified 3.4.11: run mise use -g ruby@3.4.11 on the VM, then push again.
• mv: cannot overwrite directory: ~/app is a directory, not the link to a release. Move it aside (mv ~/app ~/app.old) and deploy again.
• The push ends pre-receive hook declined: the deploy failed, and the lines above say where. The previous release still runs and main on the VM still names it. Deploy FAILED: it answers HTTP 000 means the web process didn't start, or listens somewhere other than $PORT: see journalctl -u app -n 50.
• A 502 at https://my-app.exe.xyz/: the same: the web process isn't answering on port 8000.
• 400 Bad Request or Blocked host: add the VM's name or your domain to ALLOWED_HOSTS or config.hosts.
• Too many redirects: the app redirects to HTTPS without trusting X-Forwarded-Proto. Django needs SECURE_PROXY_SSL_HEADER; Rails, config.assume_ssl.
• restore-db stops with an error: the PostgreSQL recipe's list covers the usual ones. For extension "..." is not available, install its package, such as postgresql-18-postgis-3, and restore again. The app stays stopped until a restore succeeds.
• curl: (22) ... 403 downloading the backup: the link expired after an hour. Ask for a fresh one.
• Connecting to Valkey: SSL or certificate errors: the app still forces TLS for Heroku Key-Value Store's rediss:// URL. Valkey here is plain redis:// on localhost; drop the TLS options.
• Config changes don't show: units read ~/app.env when they start. Redeploy (~/app.git/hooks/pre-receive main) or restart the units.
• npm: install scripts blocked because they are not covered by allowScripts: npm 12 runs a package's install scripts only when allowScripts in package.json allows them. Allow the ones the app needs with npm install-scripts approve <package>, commit, and push.
• A worker restarts over and over: journalctl -u app-worker -n 50. It keeps restarting until the problem is fixed, as dynos did.