Tenant Settings — Production Guide

Deploy checklist

1. Run migrations (adds type / group on tenant_settings, plus task_digest_deliveries for durable daily task digest send state).
2. Configure object storage: local FILESYSTEM_DISK=public + php artisan storage:link, or production FILESYSTEM_DISK=s3. Keep tenant branding + user avatars on local public storage (FILESYSTEM_BRANDING_DISK=public; avatars default FILESYSTEM_AVATAR_DISK=public) and persist storage/app/public across zero-downtime deploys (see object-storage.md).
3. Ensure settings.list / settings.update exist in config/tenant-permissions.php and default role maps. New workspaces receive them via TenantAuthorizationProvisioningService during provisioning. Existing workspaces that need newly added settings permissions receive them via an additive permission data migration — not production seeders and not login-time sync.
4. Confirm APP_KEY is stable — SMTP passwords are encrypted with Laravel Crypt.
5. For daily task digests: scheduler must run (schedule:run every minute) and an emails queue worker must be listening. Shared cache is required for onOneServer() schedule locks.

Security

Concern	Control
Isolation	Settings scoped by tenant_id; API requires tenancy + tenant auth
Cross-tenant	Branding files live under tenants/{uuid}/…
Secrets	mail_password encrypted at rest; API returns ********
Central leakage	Tenant API never exposes Central-only keys (registration, maintenance, billing)

Ops signals

• Unexpected Central branding on a tenant SPA usually means no tenant override + public bootstrap fell back correctly.
• Mail from Central From-address on a tenant that expected custom SMTP → check whether mail_host is set for that workspace.
• Unexpected assignment / follow-up / meeting emails → check tenant email_notifications (Settings → Notifications); defaults are all off. Digests and auth mail ignore that setting.
• 403 on /api/tenant/v1/settings → missing settings.list / settings.update on the role.

Rollback

Clearing a tenant override (empty optional branding/mail fields, or deleting the tenant_settings row) restores Central defaults immediately after cache forget (handled by the service).