Update

Keep your Kompass installation current. Update the Composer package, then run the built-in kompass:update command, which republishes assets, runs migrations, and clears caches for you.

Don't run the installer to update

php artisan kompass:install is for first-time setup only — it can offer to drop all your tables for a fresh install. To update an existing project, use kompass:update instead.

Overview

A Kompass update is two steps:

1. Update the package with Composer.
2. Run php artisan kompass:update — it republishes assets, runs migrations, clears caches, and can rebuild your frontend.

Always back up first

Before updating in production, back up your database and have a tested rollback (a tagged commit or deployment snapshot). Migrations can change your schema.

Step 1: Update the Package

Pull the latest release within the version constraint in your composer.json:

composer update secondnetwork/kompass

To move to a new major version, bump the constraint first, then update — for example:

composer require secondnetwork/kompass:^1.8

Step 2: Run the Updater

php artisan kompass:update

This runs the whole post-update routine for you:

1. Republishes vendor assets — it removes public/vendor/kompass and force-publishes the new version's assets and migrations, so nothing stale is left behind.
2. Runs migrations — copies the latest seeders into database/seeders and runs php artisan migrate.
3. Clears caches — runs php artisan optimize:clear so cached menus, config, routes, and views are rebuilt.
4. Optionally rebuilds the frontend — it asks whether to rebuild and, if you say yes, which package manager to use (bun, yarn, npm, or pnpm), then runs the build for you.

The command is interactive

kompass:update prompts you about the frontend rebuild, so run it from a terminal. For non-interactive environments (CI/CD), use the manual steps below instead.

Manual Update (CI / Non-Interactive)

If you can't run the interactive command — for example in a deploy pipeline — run the equivalent steps yourself:

composer update secondnetwork/kompass
php artisan vendor:publish --tag=kompass.assets --force
php artisan migrate
php artisan optimize:clear
npm run build   # only if you use the frontend build pipeline

Automate asset publishing

Add the publish command to the post-update-cmd hook in your composer.json so assets refresh automatically after every composer update:

"scripts": {
    "post-update-cmd": [
        "@php artisan vendor:publish --tag=kompass.assets --force"
    ]
}

This is also recommended during installation.

Review Config and Changelog

A few things are intentionally left under your control and may need a manual look after a major update:

• Config — config/kompass.php is published once and is never force-overwritten, so your settings are preserved. After a major update, compare it against the package's config/kompass.php and merge any new keys you want.
• Stubs — published files like app/Models/User.php are yours; review the package stubs after a major version bump if the upgrade notes mention changes.
• Changelog — check the Changelog for new features, deprecations, and any breaking changes before deploying.