Required installation content
Put required App rows in tenant migrations, distinguish the host-only initializer lifecycle, and recover through the installer that applies pending migrations.
Ship only the rows your App needs for its first supported operation. Optional starter records belong in Copyable templates; configuration an operator must choose belongs in Contribute Setup tasks.
Add the required data
- Create the App schema with Data Model and Migrations. Expose tenant migration paths through the manifest.
- If operation truly requires a baseline row, put it in a separately named tenant data migration. Use an immutable App-owned unique key and insert only when missing. Preserve customized values, and make retry after partial execution safe.
- Install the App in the target tenant, following Create a Resource. The installer applies pending migrations for the App and its prerequisites before initialization.
packages/expenses/src/ExpensesAppManifest.php exposes the migration directory this way:
public function tenantMigrationPaths(): array
{
return [__DIR__.'/../database/migrations/tenant'];
}This is a migration-path example, not a baseline-row seeder. The initializer interfaces currently live under host App\AppRuntime; an installable App must not implement them or import Core to obtain installation hooks.
Confirm the result
Use a fresh tenant to prove the first supported operation works after migration and installation. Also exercise a tenant with customized existing values: migration must preserve them and must not create duplicates. Check schema/data and installation status separately because these workflows do not share one transaction. Test an App describes the package test context.
Recover the correct workflow
| Operation | What it does |
|---|---|
tenants:migrate | Applies Core and previously installed App migrations, including disabled Apps; does not install new Apps or repair installation state |
nexia-apps:install-tenant-app | Applies pending App migrations, then installation and host initialization |
nexia-apps:repair-tenant-app | Replans installation with prerequisites and applies pending migrations; completed migrations are not replayed |
app/Console/Commands/RepairTenantApp.php delegates to install with --with-prerequisites. app/AppRuntime/TenantAppLifecycleService.php owns host initializer transactions. A successfully initialized current version is not rerun by every repair.
For a missing table or baseline row, fix and apply the migration. For a failed installation, fix its reported cause and then repair. Never edit installation status manually to hide a failed operation. Full command and initializer lifecycle details are in Installation content.
Required content grants no user authority. Do not overwrite tenant-owned template copies, seed demo data, or write a destructive rollback that deletes operator-owned records.
New tenants receive Core schema only. Later tenants:migrate runs include Apps with installation history, including disabled Apps; deactivation retains their tables and data. For an unpublished local App, use nexia-apps:install-dev-app <app-key> --tenant=<tenant ID> --with-prerequisites for installation or recovery. Normal installation and repair continue to enforce distribution policy.