Marketplace & Distribution

This document describes the features for marketplace distribution of Tenanto.

Overview

Tenanto includes infrastructure for commercial distribution:

• Demo Automation - Time-limited demo tenants with automatic cleanup
• License System - Secure license key generation and validation
• Update System - Version checking and update notifications
• Onboarding Wizard - Guided setup for new tenants
• Support Hooks - Extensible support ticket system

Demo Automation

Purpose

Allow potential customers to try Tenanto without manual intervention.

Components

Configuration

// config/demo.php
return [
    'enabled' => env('DEMO_ENABLED', true),
    'expiration_hours' => (int) env('DEMO_EXPIRATION_HOURS', 48),
    'warning_hours_before' => (int) env('DEMO_WARNING_HOURS', 24),
    'max_active_demos' => (int) env('DEMO_MAX_ACTIVE', 100),
    'seed_sample_data' => env('DEMO_SEED_DATA', true),
    'default_password' => env('DEMO_DEFAULT_PASSWORD', 'demo123'),
];

Usage

# Create a demo tenant
php artisan demo:create [email protected] --name="Demo Company"

# Manually trigger cleanup (normally scheduled hourly)
php artisan demo:cleanup --sync

Lifecycle

1. Creation: DemoTenantService::createDemo() creates tenant + owner + sample data
2. Warning: 24 hours before expiration, DemoExpirationWarning notification sent
3. Expiration: CleanupExpiredDemosJob soft-deletes expired demos
4. Conversion: DemoTenantService::convertToPaid() upgrades to full account

License System

Purpose

Protect the software with license keys and enable feature gating by tier.

Components

License Key Format

TENANTO-{TIER}-{HASH12}-{CHECKSUM4}
Example: TENANTO-PRO-A1B2C3D4E5F6-X7Y8

• Prefix: Product identifier
• Tier: SOLO, PRO, TEAM, UNLIMITED
• Hash: 12-character random string
• Checksum: 4-character HMAC verification

License Tiers

Configuration

LICENSE_ENABLED=true
LICENSE_SECRET_KEY=your-very-long-secret-key-here
LICENSE_VALIDATION_MODE=offline
LICENSE_GRACE_DAYS=7

CLI Commands

# Generate a license
php artisan license:generate --tier=pro [email protected] --name="Customer Name"

# Validate a license
php artisan license:validate TENANTO-PRO-A1B2C3D4E5F6-X7Y8 --domain=example.com

# List licenses
php artisan license:list --tier=pro --status=active
php artisan license:list --stats
php artisan license:list --expiring

Validation Modes

• Offline: Validates against local database (default, recommended)
• Online: Validates against remote API endpoint
• Disabled: All licenses pass validation (development only)

Update System

Purpose

Notify administrators when new versions are available.

Components

Configuration

// config/updates.php
return [
    'enabled' => env('UPDATES_ENABLED', true),
    'current_version' => env('APP_VERSION', '1.0.0'),
    'server' => [
        'url' => env('UPDATES_SERVER_URL', ''),
        'timeout' => 10,
    ],
    'check_interval_hours' => 24,
    'cache_duration' => 3600,
    'notifications' => [
        'show_banner' => true,
        'admin_only' => true,
        'email_security_updates' => true,
    ],
];

Usage

Add the update banner to your admin layout:

<livewire:updates.update-banner />

The banner will:

• Show when updates are available
• Highlight security updates in red
• Allow dismissal for 7 days
• Link to changelog/download

Onboarding Wizard

Purpose

Guide new tenant owners through initial setup.

Components

Default Steps

1. Company Profile - Business name, industry, timezone
2. Team Setup - Invite initial team members
3. Preferences - Language, date format, notifications
4. Billing - Select subscription plan

Configuration

// config/onboarding.php
return [
    'enabled' => env('ONBOARDING_ENABLED', true),
    'force_completion' => env('ONBOARDING_FORCE', true),
    'skip_for_demo' => true,
    'steps' => [
        'company_profile' => [
            'title' => 'Company Profile',
            'required' => true,
            'fields' => ['company_name', 'industry', 'size', 'timezone'],
        ],
        // ...
    ],
];

Routes

GET /onboarding  - Show wizard (name: onboarding.wizard)

Middleware

Add EnsureOnboardingComplete to routes that require completed onboarding:

Route::middleware(['auth', 'onboarding'])->group(function () {
    // Protected routes
});

Support Hooks

Purpose

Allow customers to submit support tickets through configurable providers.

Components

Supported Providers

Configuration

// config/support.php
return [
    'enabled' => env('SUPPORT_ENABLED', true),
    'default' => env('SUPPORT_PROVIDER', 'email'),
    'email' => [
        'to' => env('SUPPORT_EMAIL_TO', '[email protected]'),
        'from_name' => env('SUPPORT_EMAIL_FROM', 'Support'),
        'subject_prefix' => '[Support]',
    ],
    'categories' => [
        'general' => 'General Inquiry',
        'technical' => 'Technical Issue',
        'billing' => 'Billing Question',
        'feature' => 'Feature Request',
    ],
    'priorities' => [
        'low' => 'Low',
        'normal' => 'Normal',
        'high' => 'High',
        'urgent' => 'Urgent',
    ],
];

Usage

use App\Domain\Support\Services\SupportService;
use App\Domain\Support\ValueObjects\SupportTicket;

$service = app(SupportService::class);

// Create ticket from array
$ticketId = $service->createTicket([
    'subject' => 'Issue with billing',
    'description' => 'Cannot update payment method...',
    'requester_email' => '[email protected]',
    'requester_name' => 'John Doe',
    'category' => 'billing',
    'priority' => 'high',
]);

// Or from object
$ticket = new SupportTicket(
    subject: 'Issue with billing',
    description: 'Cannot update payment method...',
    requesterEmail: '[email protected]',
    requesterName: 'John Doe',
    category: 'billing',
    priority: 'high',
);

$ticketId = $service->createTicketFromObject($ticket);

Custom Provider

Implement SupportProviderContract for custom integrations:

class FreshdeskSupportProvider implements SupportProviderContract
{
    public function createTicket(SupportTicket $ticket): string|int { /* ... */ }
    public function getTicket(string|int $ticketId): ?SupportTicket { /* ... */ }
    public function updateTicket(string|int $ticketId, SupportTicket $ticket): bool { /* ... */ }
    public function addReply(string|int $ticketId, TicketReply $reply): bool { /* ... */ }
    public function closeTicket(string|int $ticketId): bool { /* ... */ }
    public function getName(): string { return 'freshdesk'; }
    public function isConfigured(): bool { /* ... */ }
}

// Register in config/support.php
'providers' => [
    'freshdesk' => FreshdeskSupportProvider::class,
],

Environment Variables

Add these to .env.example:

# Demo Automation
DEMO_ENABLED=true
DEMO_EXPIRATION_HOURS=48
DEMO_WARNING_HOURS=24
DEMO_MAX_ACTIVE=100
DEMO_DEFAULT_PASSWORD=demo123

# Licensing
LICENSE_ENABLED=false
LICENSE_SECRET_KEY=your-secret-key-change-in-production
LICENSE_VALIDATION_MODE=offline
LICENSE_GRACE_DAYS=7

# Updates
UPDATES_ENABLED=true
APP_VERSION=1.0.0
UPDATES_SERVER_URL=
UPDATES_SHOW_BANNER=true

# Onboarding
ONBOARDING_ENABLED=true
ONBOARDING_FORCE=true

# Support
SUPPORT_ENABLED=true
SUPPORT_PROVIDER=email
[email protected]

Database Migrations

The marketplace features include the following migrations:

1. 2025_11_29_210000_add_demo_columns_to_tenants_table.php

   • Adds is_demo, demo_expires_at, demo_warning_sent_at to tenants

2. 2025_11_29_220000_create_licenses_table.php

   • Creates licenses table for license management

3. 2025_11_29_230000_create_onboarding_progress_table.php

   • Creates onboarding_progress table
   • Adds onboarding_completed_at to tenants

Run migrations:

php artisan migrate

Testing

Tenanto includes comprehensive test coverage with 1,091 tests total:

PHP Unit & Feature Tests (607 tests)

• LicenseKeyGeneratorTest - Key generation and validation
• LicenseServiceTest - License lifecycle operations
• VersionInfoTest - Version value object
• VersionServiceTest - Update checking
• SupportServiceTest - Support ticket operations
• Plus 600+ additional tests for all core features

php artisan test --filter="Licensing\|Updates\|Support"

Playwright E2E Tests (484 tests)

Full browser-based end-to-end testing covering all critical user journeys:

# Run all E2E tests
npx playwright test

# Run specific category
npx playwright test e2e/admin/
npx playwright test e2e/isolation/

# Interactive mode
npx playwright test --ui

Test Configuration

E2E tests are configured in playwright.config.ts:

• 5 browser projects (Chromium, Firefox, WebKit, Mobile Chrome, Mobile Safari)
• Automatic retries for flaky tests
• HTML reports with screenshots and videos on failure

Security Considerations

License Keys

• HMAC-SHA256 checksums prevent tampering
• Secret key must be kept secure
• Grace period limits unauthorized use

Email Security

• All user content sanitized before email inclusion
• Prevents header injection attacks
• In-memory storage is NOT production-ready

Demo Tenants

• Automatic cleanup prevents resource exhaustion
• Rate limiting recommended on creation endpoint
• Sample data isolated to demo tenant

Related Documentation

• Multi-Tenancy Architecture - Tenant model and isolation
• Deployment Guide - Production configuration
• Security Guide - Security best practices

Future Enhancements

• Database-backed support ticket storage
• Freshdesk/Zendesk provider implementations
• License usage analytics
• Automated demo-to-paid conversion flow
• Multi-language onboarding steps