How to Deploy a Next.js App on Kubana App Platform

Kubana Cloud · November 20, 2026 · Updated November 16, 2026 · 14 min read

Tutorials
How to Deploy a Next.js App on Kubana App Platform
On this page

Introduction

You built a Next.js app and npm run dev works. Now you want it online, with HTTPS, without writing a Dockerfile or managing a Node.js server.

Kubana App Platform runs Next.js in two ways. Pick the one that matches your app:

Next.js SSR (a server) Next.js SPA (a static export)
Use it when your app has Server-side rendering, API routes (app/api), server actions, middleware, a database Only pages that can be built ahead of time (output: 'export')
Kubana runs next build, then next start next build, then serves the out folder
Size From the Small size Can run on the Free size
Extras Post-deployment commands (migrations), cron jobs —

Not sure? Choose Next.js SSR. It runs every Next.js feature. The static export is a cheaper option for sites such as docs, blogs and landing pages.

At a glance

  • Time: about 15 minutes for the first deploy.
  • You need: a Kubana account with App Platform access and a Next.js app on GitHub.
  • You get: your app at https://<your-app>.platform.kubana.app, rebuilt on every push if you want, with build logs, live logs and one-click rollbacks.
  • You don't need: a Dockerfile, a server or a process manager.

Part 1 deploys a Next.js server in seven steps. Part 2 covers cron jobs, deploy on push, your own domain and the static export. Part 3 shows how to do it all by asking your AI assistant.

Note: App Platform is in early access. If you don't see it in the dashboard, open App Platform and choose Request early access.

Before you start

You need:

  • A Kubana Cloud account with App Platform access.
  • A project in the dashboard to hold the app (Projects → New project if you have none).
  • Enough credit for the size you pick. Before the first deploy of a paid size, your balance must cover 72 hours of it. The dashboard shows the exact amount (for the Small size it is well under a dollar).
  • A Next.js app in a GitHub repository, public or private, with package.json at the root.

Check three things in your app:

  1. npm run build works on your computer, from a clean install (npm ci && npm run build).

  2. Your package.json has the usual scripts:

    "scripts": {
      "build": "next build",
      "start": "next start"
    }
  3. Your lock file is committed (package-lock.json, pnpm-lock.yaml or yarn.lock). Kubana installs with the matching package manager. To pin a Node.js version, set engines.node in package.json.

Don't set PORT yourself. Kubana tells your app which port to listen on through the PORT variable, and next start uses it automatically. Setting your own PORT in Environment breaks the connection between Kubana and your app.

Part 1: Deploy a Next.js server

Step 1: Create the app

In the dashboard, open App Platform and choose New app.

App Platform page with the New app button highlighted

Fill in the form (the numbers match the screenshot):

  1. Project: the project the app belongs to.
  2. App name: a short name such as storefront. It becomes part of your address: storefront.platform.kubana.app.
  3. Framework: choose Backends,
  4. then Next.js SSR.
  5. GitHub repository: paste owner/repo, the HTTPS URL or the SSH URL. All three work.
  6. App size: Small is enough to start. If your logs later show memory errors, move to Standard.

New app form with project, name, Backends, Next.js SSR, repository and size filled in, numbered 1 to 6

Choose Review app, check the summary, then Create app and Confirm & create. Nothing is billed yet: billing starts at the first deploy.

Create app confirmation showing Next.js SSR, the repository, the size, price and credit required

Step 2: Let Kubana read your repository

Kubana opens your new app on the Deploy key panel. A deploy key gives Kubana read-only access to this one repository: Kubana can clone your code but can never push to it.

Deploy key panel with Copy key, Open deploy keys and the verify button highlighted

  1. Choose Copy key (1).

  2. Choose Open deploy keys (2). It opens your repository's Settings → Deploy keys page on GitHub. Choose Add deploy key.

  3. Paste the key, give it a title such as Kubana, and leave Allow write access unchecked. Save.

    GitHub Add deploy key form with the Kubana key pasted and Allow write access unchecked

  4. Back in Kubana, choose I've added the key, verify access (3).

After a few seconds the status changes to Ready, and the next thing to do shows up in the menu as Set branch · Required.

App page after verification: status Ready and the Set branch item marked Required

If verification fails: check that you added the key to the same repository you entered in Step 1 and that you saved it on GitHub. Read-only access is enough.

Step 3: Pick the branch to deploy

Open Set branch. Choose Load branches, select the branch Kubana should deploy (1, usually main) and choose Save branch (2).

Git branch list loaded from GitHub with main selected and Save branch highlighted

Kubana only deploys this branch. Pushes to other branches are ignored.

Step 4: Add your environment variables

Open Environment → Add variables → Paste .env, paste your production values (1), then create them (2):

Environment tab with NEXT_PUBLIC_SITE_NAME, DATABASE_URL and STRIPE_SECRET_KEY pasted and the create button highlighted

Next.js treats variables in two ways:

  • NEXT_PUBLIC_… variables are written into the JavaScript sent to browsers when the app is built. Use them only for public values, such as your site's name or a public API address. A change needs a new deploy.
  • All other variables (DATABASE_URL, API secrets…) stay on the server. Only your server code, route handlers and server actions can read them, and visitors never see them.

New variables show as pending until the next deploy:

Environment list with the three variables marked as pending

Your database must run outside the app, for example a managed PostgreSQL or MySQL service, or one on your own Kubana server. Keys named GIT_SSH_KEY_B64 or starting with KUBANA_ are reserved.

Step 5: Run your migrations on every deploy (optional)

If you use an ORM with migrations, add the command in Configuration → Post-deployment commands, then Save commands. For Prisma:

Post-deployment commands with npx prisma migrate deploy and Save commands highlighted

For Drizzle, use npx drizzle-kit migrate. Commands run in order after each successful deploy, and Kubana never runs migrations on its own.

Step 6: Deploy

Choose Deploy at the top right of the app page and confirm.

Deploy confirmation dialog with the monthly price and the credit required

The status changes to Deploying. Under Deployments you can see the commit being built. A first Next.js deploy usually takes two to four minutes, and the page refreshes by itself.

Deployments tab with one deployment In Progress for commit c4e81b9

Behind the scenes Kubana clones your branch, installs your packages, runs npm run build, starts your app with npm run start, switches traffic to it, then runs your post-deployment commands.

Step 7: Open your app

When the status is Active, your public address appears next to the repository name. Choose Open app, or copy the address.

App overview: status Active, public address storefront.platform.kubana.app highlighted, live commit c4e81b9

Your app is live. The overview also shows the live commit, which is the exact version that is running.

Note: On a brand new app, the HTTPS certificate can take a few minutes to be issued. If your browser warns about the certificate, wait a moment and reload.

Where to look when something is off

  • Deployments → Logs shows the build log: the install, next build with your routes, and the start of the server.

    Build log of a successful Next.js deployment: npm ci, next build with the route list, next start and prisma migrate deploy

  • Logs shows what your running server prints: requests, errors and your own console.log output.

    Runtime logs with the Next.js startup lines and incoming requests

Part 2: Make it a real app

Each section below is optional and stands on its own.

Run a script on a schedule (cron jobs)

To send reminder emails every hour or clean up old data every night, open Configuration → Cron jobs → Add cron job:

Add cron job form: name, node scripts/abandoned-carts.js, schedule in plain words and time limit

  • Command: for example node scripts/abandoned-carts.js. It runs in your app's folder, with your environment variables.
  • When should it run? Pick it in plain words (every hour, every day at 02:00…) or type a cron expression. Times are in UTC, and the form shows your local time next to them.
  • Time limit: a run that takes longer is stopped (5 minutes by default).

On a running app, a new cron job starts right away.

Deploy automatically on every push

  1. On Configuration → Auto-deploy, turn the switch on and confirm.

  2. Choose Show GitHub webhook details, and copy the Payload URL and the Secret.

  3. In GitHub, open your repository → Settings → Webhooks → Add webhook. Paste the payload URL, set Content type to application/json, paste the secret, and choose Just the push event. Save.

    GitHub Add webhook form with the payload URL, application/json and the push event

From now on, git push to your branch starts a deployment, labelled Auto deploy in Deployments.

Use your own domain

Every app gets a *.platform.kubana.app address. You can also attach up to five of your own domains, and HTTPS is set up for you.

  1. First, at your DNS provider (or in Kubana DNS Management), point the domain at Kubana:

    Type Host Value Required
    A @ or your subdomain, e.g. shop 62.238.7.246 Yes
    AAAA @ or your subdomain 2a01:4f9:c015:ef6::1 Optional (IPv6)
  2. Then, in Domains, choose Add domain, enter the hostname (for example shop.example.rw) and attach it. Kubana checks the DNS records, then issues the certificate within a few minutes.

  3. Optionally make it the primary domain. If your app uses its own address (Auth.js AUTH_URL, a NEXT_PUBLIC_SITE_URL…), update it in Environment and redeploy.

Extra A or AAAA records that point somewhere else make verification fail. Remove them first.

Or: deploy a static export (can be free)

If your whole site can be built ahead of time (no server-side rendering on request, no API routes, no server actions), you can deploy it as static files instead. It can then run on the Free size.

  1. Turn on the static export in next.config.js (or next.config.ts), then check that npm run build creates an out folder:

    const nextConfig = {
      output: 'export',
    }
    
    module.exports = nextConfig
  2. Create the app as in Step 1, but choose Frontends → Next.js SPA:

    Frontends framework list: Static, Vue, React and Next.js SPA

    The Free size is preselected:

    New app form for a static Next.js site with Frontends, Next.js SPA and the Free size

  3. Add the deploy key and pick the branch as in Steps 2 and 3.

  4. Set the build directory to /out (1) and Save build directory (2):

    Build directory with /out selected and Save build directory highlighted

  5. Deploy.

With a static export, every variable you use must start with NEXT_PUBLIC_, because there is no server to read the others. Dynamic routes such as /blog/[slug] need generateStaticParams, so Next.js knows which pages to build.

Part 3: Do it all by asking your AI assistant

Everything in this guide can also be done by asking an AI assistant. Kubana runs an App Platform MCP server: connect it once to Claude, ChatGPT, Claude Code, Codex, Cursor or VS Code, and your assistant can create, configure, deploy and debug your apps for you, with your account's permissions.

Connect it (about one minute)

  1. In your assistant, add a custom connector (or MCP server) with this URL:

    https://api.kubana.cloud/mcp/app-platform

    Claude users can also install it from the Claude directory. Setup steps for each assistant are on the MCP page.

  2. Your browser opens Kubana. Sign in, then choose Authorize. You don't need an API key.

Then just ask

Create a Next.js SSR app called storefront from github.com/acme/storefront, Small size, in my Storefront project.

The assistant creates the app and gives you the deploy key. Add it on GitHub as in Step 2, then:

I've added the key. Use the main branch, add the variables from this .env, run npx prisma migrate deploy after each deploy, then deploy it.

More ideas:

  • "Run node scripts/abandoned-carts.js every hour."
  • "Turn on auto-deploy for storefront." The assistant gives you the webhook URL and secret to paste in GitHub.
  • "Attach shop.example.rw and make it the primary domain."
  • "My last deploy failed. Read the build log and tell me why."
  • "Show me the errors in storefront's logs from the last few minutes."

You stay in control

  • Risky actions ask you first. Actions that cost money, take an app offline or touch secrets need a 6-digit code that Kubana emails you. Choose which actions need a code under MCP Servers → Approval policy. See approval codes.
  • GitHub stays yours. The assistant can't touch your GitHub account, so you add the deploy key and the webhook yourself.
  • Same prices, same limits. Connecting is free.
  • Revoke at any time under MCP Servers → Connections.

Updating and rolling back

  • New code: push to your branch (with auto-deploy) or choose Redeploy.
  • New environment variables, branch or post-deployment commands: save them, then Redeploy. Saving alone doesn't change the live app.
  • Something broke? In Deployments, open an earlier deployment and choose Redeploy this version. Kubana rebuilds that exact commit. Your Git history is untouched, so fix the code, then push again.

Troubleshooting

What you see Why it happens What to do
Verification of the deploy key fails The key is on another repository, or wasn't saved Add it to the repository you entered at creation. Read-only is fine.
The deploy fails during next build A type or lint error, a missing variable at build time, or a lock file that doesn't install Run npm ci && npm run build on your computer. Read the build log for the exact message.
Bad gateway after a successful build The app doesn't listen on the port Kubana gives it Remove any PORT variable you set, keep "start": "next start", and don't hard-code a port.
A NEXT_PUBLIC_… value is empty or old It is fixed at build time Check the name starts with NEXT_PUBLIC_, then redeploy.
The server crashes or restarts under load Not enough memory for your app Move to the Standard size.
Cached pages or uploads disappear after a deploy The app's disk is replaced on every deploy Keep uploads in S3-compatible storage and data in your database.
Static export: next build fails with Page … is missing generateStaticParams() A dynamic route without its list of pages Add generateStaticParams, or deploy with Next.js SSR instead.
Static export: the site shows a default page or 404s The build directory isn't /out Set Build directory to /out and redeploy.
The deploy is refused for insufficient credit Your balance doesn't cover 72 hours of the size Top up your credits, then deploy again.

Costs at a glance

  • Next.js SSR: billed hourly from your credit from the first deploy, from the Small size. The price is locked at that moment.
  • Next.js SPA (static export): can use the Free size, never billed, up to 2 free apps per account.
  • A stopped paid app is still billed. A terminated app is not.

Conclusion

You took a Next.js app from GitHub to a live HTTPS address without a Dockerfile or a server: Kubana installed your packages, built your app, started it and ran your migrations. From here you can schedule cron jobs, deploy on every push, use your own domain, ship a static site for free, or let your AI assistant do it for you.

Next steps:

If a deploy fails and the logs don't explain why, contact support from the dashboard. We read every message.

Attachments

Back to all articles
Newsletter

Stay in the loop

Product updates, infrastructure insights, and platform news delivered to your inbox.