How to Deploy a Laravel App on Kubana App Platform

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

Tutorials
How to Deploy a Laravel App on Kubana App Platform
On this page

Introduction

You built a Laravel app and it runs on your laptop. Now you want it on the internet, with HTTPS, without setting up a server, configuring Nginx and PHP-FPM, or writing a Dockerfile.

Kubana App Platform does that. You point it at a GitHub repository and pick your Laravel and PHP versions. Kubana builds your app for you: it installs your Composer packages, builds your frontend assets with Vite, and runs Laravel on FrankenPHP, a fast modern PHP server. You press Deploy and get a public HTTPS address.

At a glance

  • Time: about 15 minutes for the first deploy.
  • You need: a Kubana account with App Platform access, a Laravel app on GitHub, a database, and a few dollars of credit.
  • 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, Nginx, PHP-FPM or Supervisor.

The guide has three parts. Part 1 takes you to a live URL in eight steps. Part 2 covers what most Laravel apps need next: queue workers and the scheduler, cron jobs, deploy on push and your own domain. Part 3 shows how to do all of it 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, your balance must cover 72 hours of that size. The dashboard shows the exact amount when you pick a size (for the Small size it is well under a dollar).
  • A Laravel app in a GitHub repository, public or private.
  • A database that runs outside the app, such as a managed MySQL or PostgreSQL service, or one on your own Kubana server. App Platform doesn't create one for you.

Check that your app is ready

Kubana handles a standard Laravel app as it is. Check these points:

  1. artisan and composer.json are at the root of the repository. Apps in a subfolder aren't supported.

  2. Your Laravel and PHP versions are supported:

    Laravel PHP
    13 8.3, 8.4, 8.5
    12 8.2, 8.3, 8.4, 8.5
    11 8.2, 8.3, 8.4
    10 8.2
  3. On Laravel 11 and later, keep the /up health route (it's in bootstrap/app.php by default). Kubana calls it before sending traffic to a new version, so a broken release never replaces a working one.

  4. Your PHP extensions are available. Kubana installs pcntl, pdo_mysql, pdo_pgsql, redis, intl, zip, gd, bcmath and opcache. Apps that need another extension (for example imagick) aren't supported yet.

  5. You don't use Composer path repositories (local packages inside the repository). They aren't supported yet.

Don't use SQLite, and don't keep uploads on the app's disk. Your app runs in a container that is replaced on every deploy and restart, so anything written to its disk is lost: a database.sqlite file, files in storage/app, file-based sessions and cache. Use an external database, database or redis for sessions and cache, and S3-compatible object storage for uploads.

Part 1: From GitHub to a live URL

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 bookstore. It becomes part of your address: bookstore.platform.kubana.app.
  3. Framework: choose Backends,
  4. then Laravel. (Laravel Worker & Scheduler is for queues and the scheduler, see Part 2.)
  5. GitHub repository: paste owner/repo, the HTTPS URL or the SSH URL. All three work.
  6. App size: CPU, memory and disk. Small is plenty to start, and you can pick a bigger size later.

New app form with project, name, Backends, Laravel, 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 the app, framework, repository, size, price and the 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 versions · Required.

App page after verification: status Ready and the Set versions 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: Choose your Laravel and PHP versions

Open Set versions. Pick the Laravel major version your app uses (1), then a PHP version (2). Only the PHP versions that work with that Laravel version are offered. Choose Save versions (3).

Laravel and PHP version picker with Laravel 12 and PHP 8.4 selected and Save versions highlighted

Not sure which Laravel version you have? Look for laravel/framework in your composer.json: "^12.0" means Laravel 12.

Step 4: 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

When you save, Kubana checks the branch: that artisan is at the root, and that composer.json requires the Laravel version you picked in Step 3. If they don't match, the dashboard says so: change the version in Step 3 or update composer.json, then save again.

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

Step 5: Add your environment variables

Your .env settings belong in Environment, not in your repository. Open Environment → Add variables → Paste .env, paste your production values (1), check the preview, then choose Create … variables (2):

Environment tab with a production .env pasted and the create button highlighted

A good starting set:

APP_NAME=Bookstore
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:your-generated-key
APP_URL=https://bookstore.platform.kubana.app

LOG_CHANNEL=stderr

DB_CONNECTION=mysql
DB_HOST=your-database-host
DB_PORT=3306
DB_DATABASE=bookstore
DB_USERNAME=bookstore
DB_PASSWORD=your-password

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database
  • APP_KEY: generate one on your computer with php artisan key:generate --show and paste the result.
  • APP_URL: your app's address. It is https://<app-name>.platform.kubana.app until you add your own domain.
  • LOG_CHANNEL=stderr: sends Laravel's logs to the Logs tab. With the default stack channel they go to a file you can't see.
  • Sessions, cache and queue: database (or redis) keeps them working across deploys. file doesn't. On Laravel 10, the cache setting is called CACHE_DRIVER instead of CACHE_STORE.

New variables show as pending until the next deploy:

Environment list with the Laravel variables marked as pending changes

About VITE_* variables: variables are available when your app runs, not while Kubana builds your assets. A VITE_* value (for example for Pusher or Reverb) is empty in the built JavaScript for now. Keys named GIT_SSH_KEY_B64 or starting with KUBANA_ are reserved.

Step 6: Run your migrations on every deploy

Kubana never runs migrations on its own. In Configuration → Post-deployment commands, click the suggested php artisan migrate --force (1). Add php artisan optimize too (2): it caches your config, routes and views so the app answers faster. Then Save commands (3).

Post-deployment commands with php artisan migrate --force and php artisan optimize, and Save commands highlighted

The commands run in order after each successful deploy. If one fails, the ones after it don't run.

Step 7: 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 Laravel deploy usually takes three to five minutes, and the page refreshes by itself.

Deployments tab with one deployment In Progress for commit 7c1e9a4

Behind the scenes Kubana clones your branch, runs composer install, builds your assets with npm run build (or pnpm or Yarn, from your lock file), starts FrankenPHP, waits for /up to answer, switches traffic, then runs your post-deployment commands.

Step 8: 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 bookstore.platform.kubana.app highlighted, live commit 7c1e9a4

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 of a deployment: Composer, the asset build, the health check and your migrations.

    Build log of a successful deployment: composer install, npm run build, health check on /up and migrations

  • Logs shows what your running app prints: requests, and Laravel's own log when LOG_CHANNEL=stderr.

    Runtime logs with FrankenPHP startup lines, requests and a Laravel log line

Part 2: Make it a real app

Each section below is optional and stands on its own.

Run queue workers and the scheduler

A Laravel app on App Platform answers web requests. Queued jobs and the scheduler (schedule:run) need a second app of the type Laravel Worker & Scheduler. It runs php artisan queue:work and php artisan schedule:work for you, and restarts them if they crash.

  1. Create a new app from the same repository. Choose Backends → Laravel Worker & Scheduler:

    New app form with Backends and Laravel Worker & Scheduler selected for the same repository

  2. Add its deploy key on GitHub (each app has its own key), as in Step 2.

  3. Choose the same Laravel and PHP versions and the same branch as your web app.

  4. Give it the same environment variables as your web app: at least APP_KEY, the DB_* values and QUEUE_CONNECTION. The easiest way is to paste the same .env block.

  5. Deploy it.

The worker app overview: Active, no public address, running the queue worker and the scheduler

Good to know:

  • A worker has no public address and no domains. It is billed like any app, from its first deploy.
  • Run only one worker per project. With two, every scheduled task runs twice.
  • Keep php artisan migrate --force on the web app only.
  • In Logs, scheduler lines start with [sched].

Run a command on a schedule (cron jobs)

If you only need one or two scheduled commands and no queue, you can skip the worker and use a cron job. Open Configuration → Cron jobs → Add cron job:

Add cron job form: name, php artisan reports:send, schedule in plain words and time limit

  • Command: for example php artisan reports:send. It runs in your app's folder, with your environment variables.
  • When should it run? Pick it in plain words (every day at 02:00, every Monday…) 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. If you already use Laravel's scheduler with several tasks, use the worker above instead of one cron job per task.

Deploy automatically on every push

To deploy every time you push to your branch:

  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.

    Auto-deploy turned on with the webhook payload URL and 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. If you have a worker, turn auto-deploy on for it too, so both run the same code.

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 with the records shown in the Domains tab:

    Type Host Value Required
    A @ or your subdomain, e.g. books 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 books.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, so it becomes the app's main address.

  4. Set APP_URL to the new address in Environment, then redeploy, so Laravel's links, emails and cookies use it.

Domains tab with bookstore.platform.kubana.app and the custom domain books.example.rw attached

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

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. If you already write your Laravel code with an assistant, you don't have to leave your editor to ship it.

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 Laravel app called bookstore from github.com/acme/bookstore, Small size, in my Bookstore 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 Laravel 12 with PHP 8.4 and the main branch, add the variables from this .env, run migrations and optimize after each deploy, then deploy it.

Part 2 works the same way:

  • "Create a Laravel worker for bookstore with the same versions, branch and variables."
  • "Run php artisan reports:send every Monday at 8 am my time."
  • "Turn on auto-deploy." The assistant gives you the webhook URL and secret to paste in GitHub.
  • "Attach books.example.rw, make it the primary domain and update APP_URL."

And it makes problems easier to solve:

  • "My last deploy failed. Read the build log and tell me why."
  • "Show me the errors in bookstore's logs from the last few minutes."
  • "Roll back bookstore to the previous deployment."

You stay in control

  • Risky actions ask you first. Anything that costs money, takes an app offline or touches secrets (creating an app, the first deploy, changing variables…) needs 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 keys and the webhook yourself.
  • Same prices, same limits. Connecting is free. A deploy started by your assistant costs exactly what it costs from the dashboard.
  • 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 running app.
  • New Laravel or PHP version: save the versions, then Redeploy. Kubana rebuilds the app from scratch on that deploy, so it is briefly unavailable.
  • 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.
Saving the branch fails with a version mismatch composer.json requires another Laravel version than the one you picked Pick the right version in Set versions, or update composer.json.
The deploy fails at composer install A missing PHP extension, a Composer path repository, or a lock file that doesn't install Check the build log. Run composer install --no-dev locally on the same branch.
The deploy fails at the health check The app crashes at startup, or /up was removed Open Logs. A missing APP_KEY or a database that can't be reached are the usual causes. Keep the /up route.
500 Server Error and nothing in Logs Laravel writes its log to a file Set LOG_CHANNEL=stderr and redeploy.
php artisan migrate --force fails The database can't be reached, or a migration fails Check the DB_* variables, and that your database accepts connections from outside.
Pages load, but links, redirects or forms use http:// Laravel doesn't trust the HTTPS proxy in front of it In bootstrap/app.php, add $middleware->trustProxies(at: '*'); and check APP_URL starts with https://.
Frontend values such as a Pusher key are empty VITE_* variables aren't available while assets are built Known limitation for now. Read the value at runtime instead, for example from a Blade <meta> tag.
Users get logged out, or uploads disappear, after a deploy Sessions or files were stored on the app's disk Use SESSION_DRIVER=database (or redis) and S3-compatible storage for files.
Queued jobs never run, or scheduled tasks run twice No worker, or more than one Run exactly one Laravel Worker & Scheduler per project, with the same variables.
The repository could not be reached The deploy key was removed from GitHub, or the branch was deleted Add the key back (the app page shows it again) or restore the branch, then deploy.
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

  • Billing is hourly from your credit and starts at the first deploy. The price is locked at that moment.
  • A stopped app is still billed. A terminated app is not.
  • A worker is a separate app and is billed separately.
  • The dashboard always shows the live price before you create an app.

When you no longer need an app, go to Sensitive → Terminate, then Delete if you want to remove it completely.

Conclusion

You took a Laravel app from GitHub to a live HTTPS address without a Dockerfile or a server: Kubana built your Composer packages and Vite assets, ran Laravel on FrankenPHP, checked /up and ran your migrations. From here you can add a queue worker and the scheduler, schedule cron jobs, deploy on every push, serve it on your own domain, 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.