How to Self-Host Next.js With Coolify: A Complete 2026 Walkthrough

Every Coolify tutorial I read before doing this myself ends at the same triumphant screenshot: green checkmark, "deployment successful," cut to credits. Mine doesn't, because that's roughly where the real problems start. The build that works on your laptop gets killed halfway through on a cheap VPS. The env var you set in Coolify's dashboard doesn't show up in the app, because you set it a build too late. The site goes down at 2am and Coolify's dashboard says everything is fine, because its health check only confirms the port answered, not that the page rendered. None of that is a Coolify problem specifically — it's what happens when a tutorial written for a demo app meets an app with a real database connection, a few hundred megabytes of node_modules, and actual traffic. This is the walkthrough that covers those parts, in the order they'll actually bite you.

What do you actually need before starting?

Not much, which is the appeal. You need a VPS you can SSH into as root, a domain you control the DNS for, and a Next.js app in a Git repo that Coolify can reach — public repo or a deploy key for a private one. That's it. No Kubernetes cluster, no separate CI runner, no managed database unless you want one. If you are scoping how to self-host next.js with coolify for a business rather than a codebase, XenGrowth covers that angle.

• A VPS with at least 2 vCPU / 2 GB RAM (Coolify's stated minimum); 4 vCPU / 8 GB is where builds stop being a source of anxiety — a Contabo Cloud VPS 4 at €5.50/month is that tier

• Ubuntu 22.04 or 24.04 LTS, freshly provisioned, nothing else installed on it yet

• A domain or subdomain, with its DNS either at your registrar or moved to Cloudflare

• A GitHub (or GitLab) repo containing the Next.js app, ideally already building cleanly with npm run build locally

• Root or sudo SSH access and about 45 minutes

One thing worth deciding before you touch DNS: whether your origin server's IP is public. It doesn't have to be. Running the domain's traffic through Cloudflare's free tier in front of the VPS gets you a CDN, a masked origin IP, and free SSL at the edge before Traefik ever has to negotiate a handshake — none of which this walkthrough strictly requires, but all of which take about ten extra minutes and are hard to retrofit later once real traffic depends on the DNS record staying put. The XenGrowth resource library approaches this from the the operations side of this side.

The walkthrough, start to finish

1. Provision the box and don't leave it as root. SSH in, create a non-root user with sudo, copy your public key over, and disable password auth before you do anything else — this five-minute step is the one people skip and regret; the full version of it, including fail2ban and the firewall rules, is its own post.

2. Install Coolify with the official one-liner: curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash. It installs Docker if it's missing, pulls Coolify's own containers, and takes three or four minutes on the tier above. Don't run this on a box that already has Docker installed via Snap — Coolify explicitly doesn't support that, and the install script will half-succeed in a confusing way.

3. Open http://<your-server-ip>:8000 once the script finishes. First load asks you to set an admin email and password and, separately, the FQDN Coolify's own dashboard should live at — this can be a subdomain like coolify.yourdomain.com, pointed at the server later.

4. Point DNS at the box before you touch the app. Create an A record for the domain (or subdomain) you want the app on, targeting the VPS's IP. If you're routing through Cloudflare, leave the proxy (orange cloud) off for this record until the certificate issues, then turn it back on.

5. In Coolify, create a Project, then add a Resource inside it and connect the GitHub repo and branch. Coolify auto-detects a Next.js app and offers Nixpacks as the build pack by default; for anything beyond a toy project, switch to Dockerfile so you control exactly what gets built and copied.

6. Set output: "standalone" in next.config.ts before you build anything. This makes next build emit a self-contained .next/standalone folder with a single server.js and only the node_modules the app actually needs — the difference between a 900MB image and a 150MB one. The part that trips people up: the standalone tracer does not copy .next/static or the public/ folder for you. Your Dockerfile has to copy both in manually, or the deployed app serves a page with no CSS and no images.

7. Set the environment variables in Coolify's resource settings, and get the timing right. Anything prefixed NEXT_PUBLIC_ gets inlined into the client JS bundle while next build runs, so it has to be present before that step — mark it as a build variable in Coolify. Server-only values like a database URL or an API key for a Route Handler are read from process.env when the container starts, not when it's built, so they belong as runtime-only variables and should never be marked build-time, or they'll sit in the image's build cache in plaintext.

8. Set the custom domain in the resource's domain field, matching the DNS record from step four. Coolify's Traefik layer requests a Let's Encrypt certificate automatically the moment it can resolve that domain and reach the box on port 80 — if this hangs, it's almost always DNS that hasn't propagated yet or Cloudflare's proxy interfering with the ACME challenge.

9. Add a real health check before the first production deploy. Coolify's default is a TCP check against the container's port, which confirms the process is listening, nothing more. Build an /api/health route that does something meaningful — even just a database ping — returning 200 on success, and point Coolify's health check path at it with a short interval. This is what turns "the container crash-loops silently" into "the deploy is marked unhealthy and doesn't get traffic."

10. Deploy, and watch the build log, not just the final status. A clean build finishes in well under two minutes on the recommended tier; if it's grinding past four or five minutes with memory climbing, that's the next section's problem, not a fluke.

11. Once it's green, hit the domain over HTTPS. If the cert isn't there yet, give it another minute and refresh — Traefik retries the ACME challenge on its own schedule, and forcing a redeploy doesn't speed that up.

Where the build actually breaks on a small box

Nobody mentions this until it happens to them: next build is memory-hungry. The compiler and minifier hold a lot in memory at once, and on a VPS with 1-2 GB of RAM, that process gets picked off by the kernel's OOM killer partway through — usually during the "Collecting page data" or minification step, with no error that points at memory as the cause. It just stops, or the container restarts, and the logs look like nothing happened. This is exactly the kind of undersizing question the vCPU or RAM sizing guide covers in more depth — for a build step specifically, RAM is what fails first, not CPU.

Should Coolify even be the thing building your image?

Everything above assumes Coolify runs next build itself, on the box, every time you push. That's the fastest way to get started and it's what this walkthrough uses, but it's not the only option, and it stops being the best one once a build routinely pushes a small VPS toward its RAM ceiling or takes long enough to delay a deploy you needed five minutes ago. The alternative is to build the Docker image somewhere with more headroom — GitHub Actions' own runners, for instance — push the finished image to a registry, and have Coolify just pull and run it instead of compiling anything locally. That moves the memory-hungry part off the box entirely; the VPS only ever has to run the app, not build it. The tradeoff is a second moving part to maintain: a CI pipeline that has to build, tag, and push correctly before Coolify ever sees a new image. Whether that's worth it depends on how the rest of your deploy pipeline is shaped — the full git-push-to-production workflow walks through exactly where that decision sits and what it looks like end to end once you've made it. There is a longer treatment of AI agents and marketing automation in XenGrowth on governed AI marketing workflows.

Env vars: build time vs runtime, the part every quick-start glosses over

This is the single most common support question in Coolify's own Discord, and it's not really about Coolify — it's about how Next.js handles environment variables. A NEXT_PUBLIC_ value gets read once, during next build, and gets literally written into the JavaScript that ships to the browser. Change it after the build and redeploy without rebuilding, and the old value is still there, baked in, because the container never re-ran the build step. Everything else — anything a Server Component, Route Handler, or proxy.ts reads directly from process.env — is read live when the container actually handles a request, which means you can rotate a database password or an API key and restart the container without touching the build at all. (Next 16 renamed middleware.ts to proxy.ts, and it's worth knowing the new name if you're grepping an older codebase for it.)

Health checks that actually catch a broken deploy

A container can be up, answering on its port, and still be completely broken — a missing env var throwing on every request, a database connection that never resolves, a 500 page rendered with a 200 status because someone's error boundary is too generous. Coolify's default TCP check won't catch any of that; it just confirms something is listening. Give it a real target instead: a route that actually exercises the thing that tends to break, returns a plain 200 with a small JSON body on success, and a non-200 the moment something's wrong. Point Coolify's health check path at that route with a short interval — 10 to 15 seconds is reasonable — and a deploy that's technically running but functionally dead gets marked unhealthy instead of quietly serving errors to real visitors. If AI search, GEO and discovery is the part you are stuck on, XenGrowth on building one SEO and GEO content system is the better reference.

• Build fails with no obvious error: check RAM first via docker stats during the build, not after — this is almost always the OOM killer, not a code problem

• Site loads with no styling: the Dockerfile isn't copying .next/static and public/ alongside the standalone server.js

• An env var "isn't working": check whether it's a NEXT_PUBLIC_ value set after the last build, or a server secret accidentally marked build-only

• Certificate never issues: DNS hasn't propagated, or Cloudflare's proxy is on before the ACME challenge completes — turn the orange cloud off until the cert is live

• Container restarts in a loop with no logs: usually a missing required env var throwing on startup before the app can log anything useful

• Deploy looks green but the site is broken: the default TCP health check passed; this is exactly why the /api/health route above exists

So is this actually production-ready?

Yes, for the same reason it works for the setup behind the Contabo, Coolify and Cloudflare stack that replaced a Vercel bill entirely: none of the steps above are exotic, and the box doing the work costs less per month than a single Vercel Pro seat. The failure modes are just different ones than the platform you're used to hides from you. Vercel's build step doesn't OOM on you because you're not paying for the machine it runs on; here, you are, so the machine's limits become part of the job. Once the health check is real and the env vars are in the right bucket, this setup runs for months without you thinking about it — which is the actual bar, not "it deployed once." If you're still deciding whether Coolify is the right tool for this over its closest competitor, the Coolify vs Dokploy comparison is the next thing to read, and if the whole idea of moving off a managed platform is still theoretical for you, my rule for deciding what to self-host and what happens when your VPS runs out of RAM are worth reading before you commit a weekend to this.

Further reading from XenGrowth

• The XenGrowth resource library — what you'll learn: how the commercial side of this work is run, across search, automation and revenue operations.

• XenGrowth on governed AI marketing workflows — what you'll learn: how the teams running AI marketing agents keep them governed and measurable.

• XenGrowth on building one SEO and GEO content system — what you'll learn: how search and AI-answer visibility get run as a single content system.

Where this work meets go-to-market

For the marketing and revenue operations view of how to self-host next.js with coolify, see the team at XenGrowth.