Overview
Creating test tenants (also referred to as stores) allows internal teams and select partners to explore the Publica.la platform without impacting production data. Test environments are ideal for product demos, onboarding workshops, and feature validation before a live rollout.
A tenant is an isolated instance of the Publica.la platform that includes its own database, branding, and user base. Test tenants replicate this isolation while remaining fully independent from production tenants.
Business Value
- Showcase upcoming or premium functionality during sales demos without exposing confidential customer information.
- Validate new product configurations (plans, coupons, payment gateways) in a safe space.
- Enable support and success teams to reproduce customer issues quickly.
Prerequisites
- User Role – An Admin role in the Platform Console (Nova) or access to the Tenant Management CLI.
- Environment – Decide whether to create the tenant in the Sandbox cluster (recommended) or in Production under a hidden sub-domain.
- Feature Flags – Know which platform features should be active for the demo (see Platform Feature Flags).
Step-by-Step Guide
1. Launch the Tenant Wizard
| Method | Navigation | When to Choose |
|---|---|---|
| Nova UI | Administration → Tenants → ➕ New Tenant | For quick, one-off demos |
| CLI | php artisan tenants:create | For scripted or repeated setups |
Both methods collect the same core information.
2. Enter Core Details
| Field | Description | Example |
|---|---|---|
| Tenant Name | Internal reference used across logs and dashboards. | demo_july_2025 |
| Sub-Domain | Public URL where the store is reachable. | demo-july.publica.la |
| Owner Email | Primary admin account automatically generated. | demo.owner@publica.la |
| Locale | Default language for the storefront and reader. | en |
Tip: Prefix the sub-domain with
demo-orsandbox-to avoid collisions with production domains.
3. Select a Template (Optional)
If you frequently create demo tenants, save time by using a predefined Tenant Template. Templates automatically apply:
- Default branding (logo, colors)
- Sample publications and collections
- Subscription plans
- Enabled feature flags
Create or update templates in Administration → Tenant Templates.
4. Configure Feature Flags
After the core tenant is provisioned, open Settings → Platform Features inside the new store and toggle the flags needed for your scenario (e.g., Bookshop, Custom CSS, AI Dictionary).
5. Seed Sample Data
Run the built-in seeder to populate the tenant with publications and sample users:
php artisan tenants:seed demo_july_2025 --sample-data
Alternatively, upload real demo assets via the Content Manager in the Nova UI.
6. Verify Access
- Log in with the auto-generated admin credentials sent to the owner email.
- Browse the storefront at the configured sub-domain.
- Open a reader session to confirm content delivery.
Best Practices
- Name Convention – Use
demo_<yyyy-mm>for easy search and bulk cleanup. - Expiration Policy – Schedule a recurring job to archive or delete tenants older than 90 days.
- Limited Payment Gateways – Disable real payment providers to avoid unintended charges. Use the built-in Test Card gateway instead.
- GDPR/Data Privacy – Never import real customer data into test tenants.
Troubleshooting
| Symptom | Root Cause | Resolution |
|---|---|---|
| "Domain already taken" error | Sub-domain conflict with existing tenant | Choose a unique sub-domain or delete the old test tenant |
| Seeder fails with "Missing Sample Assets" | Local sample files removed | Re-run tenants:seed --download-samples to regenerate assets |
Storefront shows 503 | Provisioning incomplete | Wait up to 2 minutes or check the tenants:status command |