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.
1. Create a Laravel project
Section titled “1. Create a Laravel project”composer create-project laravel/laravel laravel-hello "^12.0"cd laravel-hellocomposer require 'php:^8.4' 'ext-pdo_pgsql:*'npm installSet 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.
2. Add a greeting form
Section titled “2. Add a greeting form”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.
3. Configure the HTTPS proxy
Section titled “3. Configure the HTTPS proxy”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.
4. Configure startup
Section titled “4. Configure startup”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/bashset -euo pipefail
# Сначала снимаем кеш сборки: ключ и подключение к базе приходят только при запуске.php artisan config:clearphp artisan package:discover --ansiphp artisan config:cachephp artisan migrate --forcephp artisan route:cachephp artisan view:cache
exec docker-php-entrypoint --config /Caddyfile --adapter caddyfileClear 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.
5. Check locally
Section titled “5. Check locally”npm run buildphp artisan migratephp artisan serveOpen 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.
6. Create the app and database
Section titled “6. Create the app and database”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.
7. Set environment variables
Section titled “7. Set environment variables”Run locally:
php artisan key:generate --showStore 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.
8. Upload the source
Section titled “8. Upload the source”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/*.phpKeep 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:
webshield auth loginwebshield apps deployPaste 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.
9. Connect a hostname
Section titled “9. Connect a hostname”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.
10. Update and check persistence
Section titled “10. Update and check persistence”Change Поздороваться to Отправить привет in the template, then run:
webshield apps deployRefresh 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.
Verify
Section titled “Verify”/and/uprespond over HTTPS./upchecks 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
200for/build/assets/files. - The same browser’s counter keeps increasing after redeploy and rollback.
webshield apps logsshows 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.
Supported features and separate setup
Section titled “Supported features and separate setup”| 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. |
Troubleshooting
Section titled “Troubleshooting”| 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. |
Next steps
Section titled “Next steps”- Apps — variables, sleep, logs and pricing.
- Postgres — backups and recovery.
- Deploy from a private repository — CI publishing.