Tips

Useful tips and common gotchas when running Laravel applications on Herne.

First Deploy Checklist

<strong>public to web_root migration</strong> — If you are migrating an older site layout, move the existing public/ directory into web_root before switching the document root.

  1. Create the site and run the Setup Wizard to configure the Git repo, .env, and database.
  2. If you are upgrading an older site, move the old /var/www/domain/public directory to /var/www/domain/web_root before switching the document root.
  3. After the first deploy, run php artisan key:generate from the Artisan runner if APP_KEY is empty.
  4. Run storage:link from the Artisan runner if your app uses public disk storage.
  5. Run migrate --force from the Artisan runner or enable the migration step in Deploy Config.

Quick Install Retry

If WebBlocks CMS Quick Install fails, open the app logs, fix the reported database, permission, DNS, or runtime issue, then use Retry Install. The installer cleans safe partial files before retrying and protects finalized installs from being overwritten.

Environment Best Practices

  • Set APP_ENV=production and APP_DEBUG=false in .env for all live sites.
  • After changing .env, run optimize:clear or rebuild caches from the Artisan runner.
  • Set SESSION_DRIVER=file or database — avoid cookie on production.
  • Set QUEUE_CONNECTION=database (or redis) if you use queued jobs — never use sync on production.

DNS and SSL

  • DNS propagation can take time. Keep A record mismatches strict; do not ignore a hostname pointing at the wrong server.
  • Admins can add multiple Hetzner DNS accounts under Admin → DNS Connections. Attach each domain to the connection that owns its zone.
  • If a zone moves to another Hetzner account, update the token or attach the domain to the new connection, then use Reconnect DNS Zone.
  • For migrated external DNS zones, apex NS warnings can be informational when the A record is correct.
  • After adding aliases, use Settings → SSL / HTTPS → Re-sync SSL so Herne checks live certificate coverage.

Correcting the Application Type

If a site was created as Empty / Deploy target or Static site but an operator later deployed Laravel into its canonical web_root with the /public document root, an administrator can open Site → Settings → General → Application Runtime and choose Change to Laravel.

This corrects Herne management metadata only. It does not install Laravel, inspect or repair the application, move files, change Nginx, run migrations, or start a Queue Worker. Verify the deployed application independently before confirming, then run each Laravel-only feature&#039;s own preflight.

Queue Workers

Herne does not manage queue workers. To run queue workers:

  1. Go to Server → Cron Jobs
  2. Add: * * * * * cd /var/www/domain && php artisan queue:work --stop-when-empty >> /dev/null 2>&1

This runs the worker every minute and exits when the queue is empty (safer than a long-running process under cron).

Storage Permissions

If you get permission denied errors on storage/ or bootstrap/cache/, run from the Terminal:

chmod -R 775 storage bootstrap/cache

Slow First Load

After enabling config/route caching via Deploy Config, the first request after a fresh deploy may be slow while OPcache warms up. This is normal.

WebBlocks UI Assets

Herne loads WebBlocks UI through resources/views/partials/_webblocks-assets.blade.php and App\Support\WebBlocksUiAssets. Do not add new references to the removed /public/webblocks-ui asset folder.