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 buildCheck three things about the build:
resources/js/admin.tsxis in the Viteinputlist. Otherwise@vite(['resources/js/admin.tsx'])inadmin.blade.phphas nothing in the manifest and the panel returns a server error.- Tailwind scans your PHP.
resources/css/admin.csscarries@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 whereapp/is present. - No
public/hotfile on the server. If one is left over fromnpm run dev, Laravel serves assets from the dev server URL instead ofpublic/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.
Migrate, and link storage
php artisan migrate --force
php artisan storage:linkThe 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:
| Profile | Size | Kind |
|---|---|---|
thumb | fits inside 320×320 | box |
sm | 640 wide | responsive |
md | 1024 wide | responsive |
lg | 1600 wide | responsive |
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:
'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-regenerateThe command reads each stored original and writes the variants it lacks. It skips SVGs and items whose original is missing.
--profile=sm --profile=mdlimits it to the named profiles. An unknown name stops the command before it writes anything.--forcerebuilds 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:cacheis safe.config/tbtop-admin.phpholds only class names and scalars.route:cacheis 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:cacheWhy 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 optimizedoes not build it, andoptimize:cleardoes not remove it. Runtbtop:cache-pagesexplicitly, and beforeoptimizeif 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-pagesleaves 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:clearRestart 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 OctaneProduction checklist
- The Inertia middleware is in the
webgroup (see Install). - Guests are redirected to the panel's login page with
redirectGuestsTo()(see Authentication). - The user model's
$hiddencovers every attribute that must not reach the browser, because the panel shares the signed-in user astbtop.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_hostsinconfig/tbtop-admin.phpis 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-regeneratehas run once, so older media has the new variants (see Regenerate variants). media.acceptandmedia.max_sizematch what editors should be able to upload.max_sizeis in kilobytes. Uploaded SVGs are sanitized on the server, and HTML files are always refused.
Generate a resource
make:tbtop-resource reads a model's table and writes its list, create and edit pages, which you then own and edit.
Versioning and upgrades
What a tbtop/admin version number promises: which releases can break a host, what counts as public API, how deprecated APIs are retired, and where the changelog and upgrade steps live.