Skip to content
WebShield Docs

Publish a Laravel website

Build Laravel with Vite, connect Postgres and publish over HTTPS, with working forms, persistent sessions, updates and rollback.

Laravel needs a PHP server, a database and a stable application key. Keeping SQLite and sessions on the container filesystem can lose data when the container is replaced.

Deploy Laravel 12 through WebShield Apps: the build installs PHP dependencies, builds Vite assets and starts an HTTP server. Store sessions in Postgres.

Result: a greeting form at app.example.com, with a session counter that survives deployment. You need: a WebShield account, an unused hostname on your domain, a terminal, PHP 8.4 with Composer and pdo_pgsql, Node.js 22 with npm, and the WebShield CLI. Time: about 40 minutes, excluding DNS propagation.

Terminal window
composer create-project laravel/laravel laravel-hello "^12.0"
cd laravel-hello
composer require 'php:^8.4' 'ext-pdo_pgsql:*'
npm install

Set the PHP version in composer.json requirements: config.platform alone does not select the server runtime. Keep composer.lock and package-lock.json to pin dependencies. Declaring ext-pdo_pgsql also tells the builder to install the Postgres driver.

Replace routes/web.php:

<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::get('/', function (Request $request) {
$name = $request->query('name', 'мир');
abort_unless(is_string($name), 422);
// Счётчик хранится в серверной сессии, имя экранирует шаблон Blade.
$visits = (int) $request->session()->get('visits', 0) + 1;
$request->session()->put('visits', $visits);
return view('hello', [
'name' => mb_substr($name, 0, 100),
'visits' => $visits,
]);
});
Route::post('/hello', function (Request $request) {
$data = $request->validate(['name' => ['required', 'string', 'max:100']]);
return redirect('/?'.http_build_query(['name' => $data['name']]));
});

Create resources/views/hello.blade.php:

<!doctype html>
<html lang="ru">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Laravel в WebShield</title>
@vite(['resources/css/app.css', 'resources/js/app.js'])
<h1>Здравствуйте, {{ $name }}!</h1>
<p>Посещений в этой сессии: {{ $visits }}</p>
<form method="post" action="{{ url('/hello') }}">
@csrf
<label>Ваше имя <input name="name" maxlength="100" required></label>
<button type="submit">Поздороваться</button>
</form>
</html>

The example displays Russian greetings. Blade escapes visitor input with {{ }}; do not replace this with {!! !!}. @csrf protects the form and @vite loads built assets.

For Laravel 12, replace bootstrap/app.php:

<?php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
return Application::configure(basePath: dirname(__DIR__))
->withRouting(
web: __DIR__.'/../routes/web.php',
commands: __DIR__.'/../routes/console.php',
health: '/up',
)
->withMiddleware(function (Middleware $middleware): void {
// Входящие запросы доступны только через прокси платформы.
$middleware->trustProxies(at: '*', headers:
\Illuminate\Http\Request::HEADER_X_FORWARDED_FOR |
\Illuminate\Http\Request::HEADER_X_FORWARDED_HOST |
\Illuminate\Http\Request::HEADER_X_FORWARDED_PORT |
\Illuminate\Http\Request::HEADER_X_FORWARDED_PROTO
);
})
->withExceptions(function (Exceptions $exceptions): void {
})->create();

This lets Laravel generate URLs with your public hostname and HTTPS. Trusting all proxies here relies on WebShield Apps having no direct public access to the container. On a server with an exposed port, trust only your proxy addresses. See Laravel trusted proxies.

Create Caddyfile in the project root. Serve only public, listen on the platform port and keep request headers out of debug logging.

{
admin off
persist_config off
auto_https off
frankenphp
log {
format json
output stderr
level INFO
}
}
:{$PORT:8080} {
root * /app/public
encode gzip
php_server
}

Create start-container.sh alongside it:

#!/bin/bash
set -euo pipefail
# Сначала снимаем кеш сборки: ключ и подключение к базе приходят только при запуске.
php artisan config:clear
php artisan package:discover --ansi
php artisan config:cache
php artisan migrate --force
php artisan route:cache
php artisan view:cache
exec docker-php-entrypoint --config /Caddyfile --adapter caddyfile

Clear the build-time configuration cache before migrations, then rebuild it with runtime variables. This starts the builder’s production server; keep php artisan serve for local development. No Dockerfile is needed for this example. See the PHP builder documentation.

Startup migrations suit this first, single-instance example. For production, plan a separately controlled migration process and schema compatibility with the previous code. Scaling and restarts can run migrations concurrently; the dashboard has no dedicated migration job.

Terminal window
npm run build
php artisan migrate
php artisan serve

Open http://127.0.0.1:8000/, submit Анна & Борис and refresh. The name should appear as text and the counter should increase. The local database is not uploaded. Stop the server with Ctrl+C.

In the dashboard, open Services → Apps, review usage-based billing and create project laravel-demo. Create app web: kind App, port 8080, Maximum instances 1.

In the same project, create a 1 GB Postgres database named db, without a replica. Wait until it is ready. This is a new database, separate from local SQLite.

Run locally:

Terminal window
php artisan key:generate --show

Store the generated key securely. In app web, open Environment variables and set:

Name Value
APP_NAME Laravel Demo
APP_ENV production
APP_DEBUG false
APP_KEY the complete generated key, including base64:
APP_URL https://app.example.com, using your hostname
DB_CONNECTION pgsql
DB_URL ${{db.url}}
SESSION_DRIVER database
SESSION_SECURE_COOKIE true
CACHE_STORE database
QUEUE_CONNECTION sync
LOG_CHANNEL stderr
LOG_LEVEL info

Laravel 12 reads the connection string from DB_URL. WebShield resolves ${{db.url}} on deployment, so you do not need to copy a database password.

Keep APP_KEY unchanged across restarts, updates and rollbacks. Replacing it prevents decryption of existing encrypted data and cookies. When moving an existing website, reuse its key.

Create .webshieldignore to exclude secrets, local dependencies and cached settings:

.env
.env.*
!.env.example
/vendor/
/node_modules/
/public/build/
/public/hot
/auth.json
/database/*.sqlite*
/storage/logs/*
/bootstrap/cache/*.php

Keep composer.json, both lock files, package.json and Vite source files in the upload. The build recreates public/build.

Create webshield.toml:

[app]
project = "laravel-demo"
name = "web"

Issue a CI token in the project card, then run:

Terminal window
webshield auth login
webshield apps deploy

Paste the token at the login prompt; never put it in the project files. Wait for Running. If it fails, open Build log: PHP and Laravel should be detected, dependencies installed and vite build completed.

Under Names, add an unused app.example.com on your domain. Connect the domain first if it is not in your account. With WebShield DNS, records and the certificate are created automatically. With another DNS provider, follow connection without changing nameservers.

Open https://app.example.com/ and submit a name. The form should return to your HTTPS hostname, display the greeting and increase the counter.

Change Поздороваться to Отправить привет in the template, then run:

Terminal window
webshield apps deploy

Refresh in the same browser: the button changes and the counter continues increasing. Under Deployments, select Restore this version on the first successful deployment. The old button returns and the session remains.

Rollback restores code. It does not undo migrations or restore the database; use Postgres recovery for data recovery.

  • / and /up respond over HTTPS. /up checks Laravel booting, not data persistence.
  • The form accepts Анна & Борис, returns to your hostname and preserves the session.
  • <script>alert(1)</script> is blocked by the WAF or displayed as text without execution.
  • Browser network tools show 200 for /build/assets/ files.
  • The same browser’s counter keeps increasing after redeploy and rollback.
  • webshield apps logs shows startup and migrations without secrets.

When finished, revoke the tutorial CI token, detach the hostname and delete the tutorial app and its database. Running resources are billed by usage.

Feature Setup
PHP, Composer, Laravel, Vite, HTTPS Build and run as above. This example targets Laravel 12.
Persistent data and sessions Use Postgres, not the app filesystem.
Redis-compatible cache Connect Valkey and a PHP Redis client; see Valkey. This example uses database caching.
Queues This example uses sync, running jobs inside requests. The dashboard has no separate non-HTTP service type; queue:work cannot be the web app’s only command. Horizon requires separate setup.
schedule:run Not started automatically. Configure a separate scheduling mechanism; app sleep is not a scheduler.
Uploaded files Use a Laravel S3 disk with object storage. storage:link does not make container storage persistent.
Mail and Reverb Require separate configuration and testing; deploying the website does not configure them.
Symptom Cause and fix
could not find driver Add ext-pdo_pgsql to composer.json requirements, update the lock file and rebuild.
MissingAppKeyException or SQLite used instead of Postgres Check variables and ensure startup runs config:clear before config:cache and migrations.
Form returns 419 or redirects to HTTP Check trusted proxies, APP_URL, HTTPS and cookies. Redeploy after changing variables.
Vite manifest not found Upload package.json, the lock file and source files. Check that npm run build succeeds.
Session resets on update Keep APP_KEY stable, use SESSION_DRIVER=database and check Postgres and the standard sessions migration.
Startup never completes Read the app log: migrations must complete before the HTTP server starts. Keep APP_DEBUG disabled publicly.