TabletopDOCS
Getting started

Deploy

What a production deploy of a tbtop/admin app needs: matching package versions, the asset build, migrations, storage, and the page-discovery cache in the right order.

Deploying a Tabletop panel is a normal Laravel deploy with a few additions. The package runs no queued jobs and needs no scheduler, cache store or long-running process of its own. What it does need is a front-end build that includes the admin entry, its media tables and storage (plus Laravel's notifications table if the header shows the notification bell), and, if you use page discovery, a cached page index built before the route cache.

Before you ship: pin both packages together

tbtop/admin and @tbtop/inertia-admin are released together and share one wire format. A server running one version while the browser runs another produces pages that render wrong or not at all, often with no clear error. Lock both to the same release:

// package.json
"@tbtop/inertia-admin": "0.8.3"
// composer.json
"tbtop/admin": "0.8.3"

With ^0.8.3 instead, a later composer update can move PHP to a newer patch of the same minor line while npm stays on 0.8.3. Install covers both options. Commit composer.lock and package-lock.json, and install from them on the server (composer install, npm ci). When you upgrade, bump both in the same commit.

Build the assets

npm ci
npm run build

Check three things about the build:

  • resources/js/admin.tsx is in the Vite input list. Otherwise @vite(['resources/js/admin.tsx']) in admin.blade.php has nothing in the manifest and the panel returns a server error.
  • Tailwind scans your PHP. resources/css/admin.css carries @source '../../app/**/*.php', because pages write Tailwind classes from PHP. If you build the assets somewhere without the PHP source (a separate CI job or a slim Docker stage), those classes are missing from the CSS and the affected blocks render unstyled. Build where app/ is present.
  • No public/hot file on the server. If one is left over from npm run dev, Laravel serves assets from the dev server URL instead of public/build.

After a deploy, browsers still on an old bundle reload themselves on their next navigation. Inertia's default asset version is a hash of public/build/manifest.json, so it changes with every build that changes the output. You need no extra step for this.

php artisan migrate --force
php artisan storage:link

The package's media-library migrations load from the vendor directory and run with yours. The media library stores files on the disk named in config/tbtop-admin.php under media.disk, which is public by default. For those files to have working URLs, public/storage has to link to that disk, which is what storage:link does. On a symlinked-release deploy (Forge, Envoyer, Deployer), keep storage/ shared between releases so uploads survive a deploy.

Image variants

Every raster image uploaded to the media library gets resized variants, one per profile under media.profiles in config/tbtop-admin.php. The defaults:

ProfileSizeKind
thumbfits inside 320×320box
sm640 wideresponsive
md1024 wideresponsive
lg1600 wideresponsive

Variants are encoded as webp by default (media.conversions.format) and never upscaled. A profile without a height, such as 'sm' => [640], is a width-only responsive variant for a srcset; it is skipped for an image no wider than it, so a small image gets fewer variants. A profile can also set its own format and quality:

config/tbtop-admin.php
'profiles' => [
    'thumb' => [320, 320],
    'sm' => [640],
    'md' => [1024],
    'lg' => [1600],
    'og' => ['width' => 1200, 'height' => 630, 'format' => 'jpeg', 'quality' => 85],
],

If you published config/tbtop-admin.php before v0.7.2, your copy still lists only thumb, and only thumb is generated. Copy the sm, md and lg lines from the package's config to get the responsive variants.

Each variant is recorded in the media item's sizes, and the library's JSON returns it there with its URL, width, height and MIME type. SVGs get no variants.

Generating variants needs the PHP GD extension. Without GD, uploads still work, but no variants are generated.

Regenerate variants for existing media

Profiles apply at upload time. Media uploaded before a profile existed, such as everything stored before you added sm, md and lg, does not have it until you regenerate:

php artisan tbtop:media-regenerate

The command reads each stored original and writes the variants it lacks. It skips SVGs and items whose original is missing.

  • --profile=sm --profile=md limits it to the named profiles. An unknown name stops the command before it writes anything.
  • --force rebuilds variants that already exist, which you need after changing a profile's size or format. It also deletes variant files the new set no longer uses.
  • A failing item is reported and skipped. The command processes the rest, then exits with a failure code.

Run it once after deploying a release or config change that adds profiles. On a large library it decodes every original, so run it outside the request path, for example in a one-off job on the server.

Cache in the right order

Laravel's usual caches work with the package:

  • config:cache is safe. config/tbtop-admin.php holds only class names and scalars.
  • route:cache is safe. Every package route points at a controller class, and the panel-root redirect is built so it can be cached.

If a panel uses discoverPages(), build the discovery index before the route cache:

php artisan tbtop:cache-pages
php artisan config:cache
php artisan route:cache
php artisan view:cache

Why the index matters even with cached routes: the panel reads its page list on every request, to build the menu and the breadcrumbs. Without the index, each request walks the discovery directories on disk. tbtop:cache-pages writes that list to bootstrap/cache/tbtop-pages.php once.

Facts about the index worth knowing:

  • php artisan optimize does not build it, and optimize:clear does not remove it. Run tbtop:cache-pages explicitly, and before optimize if you use that.
  • Rebuild it on every deploy that adds, moves, renames or removes a page, or that changes a page's isDiscovered(). The simplest rule is to run it on every deploy. A new page missing from a stale index is not routed.
  • It survives symlinked releases. Paths inside the app are stored relative to the project root, so an index built in one release directory still applies after the symlink moves.
  • A stale index degrades instead of failing. If the index names a class that no longer exists, it is ignored and the directories are scanned again. The rebuild is also atomic: a failed tbtop:cache-pages leaves the previous index in place.
  • It holds class names only. Gates, middleware and page output are evaluated live on every request.

Panels that list pages only through pages() have no index to build, and tbtop:cache-pages has nothing to do for them.

The route cache freezes each panel's prefix, middleware and page paths. Any change to a panel class, or to the panels list in the config, needs a fresh route:cache to take effect.

To go back to uncached behaviour, for example while debugging on a server:

php artisan tbtop:clear-cached-pages
php artisan route:clear

Restart workers

If you run Octane or another long-lived PHP process, restart it after each deploy. A worker keeps the page list it loaded at boot. Queue workers need the usual queue:restart if your own handlers dispatch jobs, but the package does not queue anything itself.

A deploy script

Put together, for a panel with page discovery:

composer install --no-dev --optimize-autoloader
npm ci
npm run build

php artisan migrate --force
php artisan storage:link        # once per server; harmless to repeat

php artisan tbtop:cache-pages   # before route:cache
php artisan config:cache
php artisan route:cache
php artisan view:cache

php artisan octane:reload       # only if you run Octane

Production checklist

  • The Inertia middleware is in the web group (see Install).
  • Guests are redirected to the panel's login page with redirectGuestsTo() (see Authentication).
  • The user model's $hidden covers every attribute that must not reach the browser, because the panel shares the signed-in user as tbtop.user.
  • The panel is limited to staff, not merely to signed-in users. See access control.
  • If you wrote your own login page instead of publishing the package's, its submit handler is rate-limited with Laravel's RateLimiter. The published pages throttle for you.
  • media.url_import.allowed_hosts in config/tbtop-admin.php is set if editors should import media only from known hosts. Empty means any host that passes the built-in SSRF guard.
  • After adding or changing media.profiles, php artisan tbtop:media-regenerate has run once, so older media has the new variants (see Regenerate variants).
  • media.accept and media.max_size match what editors should be able to upload. max_size is in kilobytes. Uploaded SVGs are sanitized on the server, and HTML files are always refused.

On this page