Deploying
Nevela is two apps. Deploy each the way you would deploy any Laravel or Next.js app. On Laravel Cloud, follow Deploying to Laravel Cloud, which goes through both step by step. On a host that runs the app in one container from a start command (Sevalla, Railway, Fly.io, Render), see also Deploying to a container host.
The Laravel app
Section titled “The Laravel app”- Use a production database rather than the SQLite file, and run
php artisan migrate --forceon each deploy. - Commit the generated code. Nothing is generated at deploy time, so the server does not need the web app’s folder.
- Check who holds which role. A generated policy asks for a permission; in an app from before 0.5.0 the policies still allow any signed-in user until you change them.
- Install with
composer install --no-dev --optimize-autoloader. A new app has Composer’s optimized autoloader turned off, because building it made creating an app take minutes longer; production should have it, and the flag turns it on. - If you ever change
APP_KEY, keep the old one inAPP_PREVIOUS_KEYS. Beside what Laravel itself needs it for, it is what keeps blocked emails blocked. - Run
php artisan config:cacheandphp artisan route:cache(orphp artisan optimize) as usual. Nevela’s routes are cached with the rest. On 0.33.0 and earlier, leave outroute:cache: with routes cached, sign-in and public routes failed. - Keep
bootstrap/cachewritable, as Laravel needs it to be. Nevela keeps a note there of the tables and columns it has found (nevela-schema.json), so it doesn’t ask the database again on every request. Migrations clear it. If you ever remove a table or column without a migration, runphp artisan optimize:clear. - Add Laravel’s scheduler to cron:
* * * * * cd /path/to/api && php artisan schedule:run >> /dev/null 2>&1. It is what empties the trash of records past their 30 days each night. Without it they go the next time someone opens the Trash page. The same run removes files visitors uploaded through a public form and never sent, and people who joined a list and never confirmed their address. The scheduler also sends the hourly digest of form notices that were held back, and removes sign-ins that have ended. On a host with no cron, runphp artisan schedule:workbeside the web server instead: see the scheduler on a container host.
Faster, with Octane
Section titled “Faster, with Octane”Octane serves the Laravel app from workers that start it once and keep it, where PHP-FPM starts it for every request. In the benchmark that made Nevela’s API 1.4 to 1.8 times as fast on the same CPU, most for single records, least for pages of many.
Nevela works on it as it is. What Nevela keeps for one request (whose roles grant what, the files a page looked up, which tables and columns are there) is let go of when the next one starts, and the same happens at the start of each queued job. To try it with FrankenPHP:
cd apps/apicomposer require laravel/octanephp artisan octane:install --server=frankenphpphp artisan octane:start --server=frankenphp --workers=8- After each deploy, run
php artisan octane:reload, so the workers load the new code. A migration needs nothing more: Nevela reads its note of the tables again on every request, so a column a migration removed is asked about again. - Your own code follows Octane’s rules: nothing about one request kept in a static property or a singleton, because the next request finds it there. The Octane docs list what to look out for.
- Workers are replaced after 500 requests by default (
--max-requests), which keeps a slow leak from growing. The benchmark ran with that default.
The web app
Section titled “The web app”The web app needs one setting: NEVELA_API_URL, the address of the Laravel API including its prefix, for example https://api.example.com/api. The Next.js server must be able to reach that address; visitors’ browsers do not need to.
A host such as Laravel Cloud gives you the bare address, https://your-api.laravel.cloud. Add /api to it. Without it, every sign-in fails with “The dashboard can’t find the API’s sign-in”. The web app checks the address and NEVELA_PROXY_SECRET once when it starts. It writes what is wrong to its log, with the value to use, and in development shows it on the sign-in page.
In production the token cookie is marked Secure, so the web app must be served over HTTPS.
If the app has public pages, two more things:
- Caching. What
laravelPublic()reads is kept in Next’s data cache and revalidated when the dashboard changes a record. That cache has to be shared by every instance of the web app, or one instance will go on showing a page another has revalidated. On one server it is the default; on several, or on a serverless host, give Next a shared cache handler. NEVELA_PROXY_SECRET, the same value in both apps. It is how Laravel tells visitors apart when every request reaches it from the web app’s server. Without it one busy visitor uses up everyone’s allowance.NEVELA_TRUSTED_PROXIESin the web app, if there isn’t exactly one proxy in front of it. See Throttling.TURNSTILE_SECRET_KEYin the Laravel app andNEXT_PUBLIC_TURNSTILE_SITE_KEYin the web app, if a form asks for the robot check. Without the secret a form that asks for it answers 503 in production. The site key is built in, so set it before building the web app. A check counts only if it was solved on the siteNEVELA_WEB_URLnames, so that has to be the site’s real address (or list the names inTURNSTILE_HOSTNAMES).- A queue worker (
php artisan queue:work) for the Laravel app, if a form sends mail throughPublicMailor confirms an address. That mail is queued.
Checklist
Section titled “Checklist”Run php artisan nevela:deploy:check on the server after each deploy. It checks most of this list for you, and the dashboard as well. See nevela deploy:check.
- Roles and policies reviewed, and the sample users deleted, then removed for good under Deleted accounts
-
NEVELA_API_URLpoints at the production API, with its prefix - Both apps served over HTTPS
-
NEVELA_PROXY_SECRETset to the same value in both, if anything is public -
nevela statusrun on the server: it is red where a form’s robot check has no secret key - With Google or GitHub sign-in on: the production callback address registered with each provider, and
php artisan config:clearafter changingSOCIAL_AUTH_ENABLEDon a server that caches its config -
routes/nevela-public.phpread through: it lists everything that is open without signing in - At least one user created on the server with
php artisan nevela:user. The starteradmin@example.comaccount is not there, and should not be