How it works
Prepare your application
Read the port from process.env.PORT
Do not hard-code the port. Listen on 0.0.0.0, never on localhost. If ignored: The router delivers traffic to the declared port and nobody answers. Visitors get a 502 while the container is healthy.
Run migrations at startup, not during the build
Run migrate deploy before starting the server. There is no database to connect to while the image is being built. If ignored: The database ends up with zero tables and the app errors on the first query. This was the most common failure in real migrations.
Fail loudly when a migration fails
If migrate fails, the process must exit with the message in the log — not start anyway. If ignored: The app stays online serving errors, the dashboard shows green, and nobody notices until a customer complains.
NEXT_PUBLIC_* variables are build arguments
In Next.js they are written into the bundle during the build. Declare each one as ARG and promote it to ENV before the build line. If ignored: The development value is baked in forever. The production site keeps calling localhost.
Nothing important on the container disk
Uploads, images, attachments: send them to S3 storage. The container disk is wiped when the copy is recreated. If ignored: Files disappear on the next deploy, with no warning and no way to recover them.
Do not keep state only in process memory
Sessions, queues, shared cache: put them in the database or Redis. With more than one copy, each process has its own memory. If ignored: Users lose their session whenever a request lands on another copy, and writes vanish without any error.
A built-in scheduler needs a single copy
If the app has an internal cron, tell whoever deploys it. The alternative is to move the job to its own service. If ignored: Double charges, messages sent twice, customers blocked by mistake.
Answer something on /
Any response below 500 works — including a redirect to the login page. That is how the platform knows the app is alive. If ignored: The app is considered down and the owner gets an outage alert for an outage that does not exist.
Log to stdout, not to a file
Write to standard output. Do not open a log file inside the container. If ignored: The log is stuck on a disk nobody can reach, exactly when you need it.
Every secret comes from the environment
API keys, token secrets, third-party credentials: only from environment variables. Never committed, never with a default value that works. If ignored: The secret leaks in the repository and works for anyone who clones the code.
Monorepo: one service per program, in the same project
A site and an API from the same repository become two services of the same project, each with its own Dockerfile and port. Do not create two projects. If ignored: With two projects, secrets must be copied by hand from one to the other — and the day one changes and the other does not, the token stops being accepted and nobody knows why.
Dockerfile: give the path, keep the context at the root
In a monorepo, enter the full path of the service’s Dockerfile. The context stays at the root so the shared lockfile is found. If ignored: The build dies with "open Dockerfile: no such file or directory" in a repository that has a Dockerfile.