Write administrator guide for organization and license management

[johnproblems]

Task: Write Administrator Guide for Organization and License Management

Description

Create a comprehensive administrator guide documenting the enterprise organization hierarchy system and license management workflows. This guide serves as the primary reference for system administrators, organization admins, and support staff who manage the multi-tenant Coolify Enterprise platform. It covers the complete organizational structure from Top Branch down to End Users, explains license types and feature flags, provides step-by-step procedures for common administrative tasks, and includes troubleshooting guidance for typical scenarios.

The guide addresses the unique challenges of managing a hierarchical multi-tenant system where organizations have parent-child relationships, users belong to multiple organizations with different roles, and license-based feature access controls organizational capabilities. Unlike standard Coolify documentation which focuses on application deployment, this guide explains the enterprise-specific administrative layer that enables white-label reselling, organizational isolation, and tiered feature access.

Key Topics Covered:

1. Organization Hierarchy Concepts - Understanding Top Branch, Master Branch, Sub-User, and End User organization types
2. User Role System - Organization roles (owner, admin, member, viewer) vs global permissions
3. License Management - License types (Starter, Professional, Enterprise, White-Label), activation, validation, feature flags
4. Administrative Workflows - Organization creation, user invitations, role assignments, license upgrades
5. Resource Management - Quotas, usage tracking, capacity planning per organization
6. White-Label Configuration - Enabling white-label features, branding setup, custom domains
7. Troubleshooting - Common issues (license validation failures, permission errors, resource quota exceeded)
8. Best Practices - Security recommendations, organizational structure design, license tier selection

Target Audience:

• Platform Administrators - Manage the entire Coolify Enterprise instance
• Top Branch Admins - Manage their organization hierarchy and reseller network
• Master Branch Admins - Manage sub-users and end-user organizations
• Support Staff - Troubleshoot user issues and assist with administrative tasks

Integration with Existing Documentation:

This guide complements the existing Coolify documentation (.cursor/rules/ directory) by focusing specifically on enterprise multi-tenant administration. It references but doesn't duplicate core deployment workflows, instead concentrating on organizational management, licensing, and hierarchical access control that are unique to the enterprise transformation.

Why This Task Is Important:

Without clear documentation, administrators struggle to understand the hierarchical model, leading to misconfigured organizations, incorrect license assignments, and permission issues. A comprehensive guide reduces support burden by empowering admins to self-serve, ensures consistent organizational setup across customers, and accelerates onboarding of new administrators. For white-label resellers, this guide is critical for understanding how to manage their customer organizations and apply branding configurations effectively.

The guide also serves as a training resource for new support staff, reducing ramp-up time from weeks to days by providing clear procedures for common tasks. It establishes best practices that prevent security issues like cross-organization data leakage or privilege escalation through role misconfiguration.

Acceptance Criteria

• Document covers all four organization types with clear definitions and use cases
• Explains organization hierarchy relationships (parent-child) with visual diagrams
• Documents all user roles (owner, admin, member, viewer) with permission matrices
• Details all license types with feature comparison table
• Provides step-by-step procedures for 15+ common administrative tasks
• Includes troubleshooting section with 10+ common issues and resolutions
• Contains security best practices section with 8+ recommendations
• Includes CLI command reference for administrative operations
• Provides API examples for programmatic organization management
• Contains real-world example scenarios with detailed walkthroughs
• Includes screenshots and diagrams for complex workflows
• Cross-references related Coolify documentation appropriately
• Written in clear, professional language accessible to non-technical admins
• Structured with table of contents and searchable headings
• Includes code examples for automation scripts
• Contains glossary of enterprise-specific terminology
• Provides quick reference cards for common tasks
• Includes version compatibility matrix (Laravel, Coolify versions)

Technical Details

File Paths

Documentation:

• /home/topgun/topgun/docs/enterprise/admin-guide.md (new - primary guide)
• /home/topgun/topgun/docs/enterprise/organization-hierarchy.md (new - hierarchy deep dive)
• /home/topgun/topgun/docs/enterprise/license-management.md (new - licensing deep dive)
• /home/topgun/topgun/docs/enterprise/troubleshooting.md (new - troubleshooting reference)

Supporting Assets:

• /home/topgun/topgun/docs/enterprise/diagrams/org-hierarchy.svg (organization structure diagram)
• /home/topgun/topgun/docs/enterprise/diagrams/license-flow.svg (license validation flowchart)
• /home/topgun/topgun/docs/enterprise/screenshots/ (UI screenshots for procedures)

Code Examples:

• /home/topgun/topgun/docs/enterprise/examples/create-organization.sh (CLI scripts)
• /home/topgun/topgun/docs/enterprise/examples/api-organization-management.php (API examples)

Documentation Structure

Main Guide: docs/enterprise/admin-guide.md

# Coolify Enterprise Administration Guide

## Table of Contents

1. Introduction
   - About Coolify Enterprise
   - Target Audience
   - Prerequisites
   - Documentation Conventions

2. Organization Hierarchy System
   - Understanding Organization Types
   - Hierarchy Relationships
   - Data Isolation and Scoping
   - Organizational Best Practices

3. User Management
   - User Roles and Permissions
   - Inviting Users to Organizations
   - Managing User Access
   - Role-Based Access Control (RBAC)

4. License Management
   - License Types Overview
   - License Activation Process
   - Feature Flags Explained
   - License Upgrades and Downgrades
   - License Validation Troubleshooting

5. Administrative Workflows
   - Creating Organizations
   - Configuring Organizational Settings
   - Managing Resource Quotas
   - Monitoring Organization Usage
   - Enabling White-Label Features

6. Security and Compliance
   - Security Best Practices
   - Audit Logging
   - Data Privacy Considerations
   - Compliance Requirements

7. Troubleshooting
   - Common Issues and Solutions
   - Error Message Reference
   - Support Escalation Process

8. Appendices
   - Glossary
   - API Reference
   - CLI Command Reference
   - Quick Reference Cards

## Chapter 1: Introduction

### About Coolify Enterprise

Coolify Enterprise transforms the open-source Coolify platform into a multi-tenant, hierarchical deployment system designed for white-label resellers, managed service providers, and enterprise organizations. Unlike standard Coolify which manages servers and applications for a single organization, Coolify Enterprise supports complex organizational hierarchies where Top Branch organizations can create Master Branch children, who in turn manage Sub-Users and End Users.

**Key Enterprise Features:**

- **Hierarchical Organizations**: Four-tier structure (Top Branch → Master Branch → Sub-User → End User)
- **License-Based Feature Control**: Starter, Professional, Enterprise, and White-Label tiers
- **White-Label Branding**: Complete UI customization with custom logos, colors, and domains
- **Resource Quotas**: Per-organization limits on servers, applications, deployments
- **Role-Based Access Control**: Organization-scoped roles with granular permissions
- **Terraform Integration**: Automated infrastructure provisioning across cloud providers
- **Advanced Deployment Strategies**: Rolling updates, blue-green, canary deployments

### Target Audience

This guide is intended for:

- **Platform Administrators** - Responsible for the entire Coolify Enterprise installation
- **Top Branch Administrators** - Managing reseller networks and white-label configurations
- **Master Branch Administrators** - Managing customer organizations and resource allocation
- **Support Staff** - Assisting users with organizational and licensing issues

### Prerequisites

Before using this guide, you should have:

- Access to Coolify Enterprise with administrative privileges
- Basic understanding of Laravel/PHP web applications
- Familiarity with Docker and container orchestration
- Knowledge of organizational hierarchy concepts
- Understanding of role-based access control (RBAC)

### Documentation Conventions

**Code Blocks:**
```bash
# Shell commands prefixed with $
$ php artisan organization:create --type=master_branch

# Output shown without prefix
Organization created successfully: ID 42

UI Elements:

• Menu items and buttons shown in bold: Click Settings → Organizations
• Field names shown in italics: Enter organization name in the Organization Name field
• Keyboard shortcuts shown in code: Press Ctrl+S to save

Notes and Warnings:

Note: Informational callouts appear in blockquotes with Note prefix

Warning: Critical information that could cause data loss or security issues

Tip: Helpful suggestions and best practices

Chapter 2: Organization Hierarchy System

Understanding Organization Types

Coolify Enterprise implements a four-tier organizational hierarchy designed to support white-label resellers and multi-level customer relationships. Each tier has specific capabilities and restrictions:

1. Top Branch Organization

Definition: The highest level in the organizational hierarchy, typically representing a white-label reseller, managed service provider, or large enterprise.

Capabilities:

• Create and manage Master Branch child organizations
• Configure global settings inherited by children
• Apply white-label branding visible to all descendants
• Allocate resource quotas to child organizations
• Manage organization-wide billing and subscriptions
• Access consolidated usage reports across all descendants

Restrictions:

• Cannot have a parent organization
• Requires Enterprise or White-Label license tier
• Limited to one Top Branch per Coolify Enterprise instance

Use Cases:

• White-label reseller selling Coolify under their own brand
• Managed service provider managing multiple customer organizations
• Large enterprise with multiple departments or subsidiaries

Example Configuration:

// Creating a Top Branch organization
Organization::create([
    'name' => 'Acme Cloud Platform',
    'type' => 'top_branch',
    'parent_organization_id' => null,
    'slug' => 'acme-cloud',
    'settings' => [
        'white_label_enabled' => true,
        'can_create_children' => true,
        'max_child_organizations' => 100,
    ],
]);

2. Master Branch Organization

Definition: Mid-level organizations created by Top Branch, representing individual customers or business units.

Capabilities:

• Create Sub-User and End User child organizations
• Manage their own users and permissions
• Configure organization-specific settings
• View usage reports for their hierarchy
• Allocate resources to child organizations
• Inherit white-label branding from parent

Restrictions:

• Must have a Top Branch parent
• Cannot modify parent's white-label configuration
• Resource quotas limited by parent allocation
• Requires Professional, Enterprise, or White-Label license

Use Cases:

• Customer of a white-label reseller
• Department within a large enterprise
• Business unit with independent management

Example Configuration:

Organization::create([
    'name' => 'TechCorp Solutions',
    'type' => 'master_branch',
    'parent_organization_id' => $topBranchId,
    'slug' => 'techcorp',
    'settings' => [
        'inherit_branding' => true,
        'can_create_children' => true,
        'max_child_organizations' => 25,
    ],
]);

3. Sub-User Organization

Definition: Organizations created by Master Branch for delegated management, typically representing teams or projects.

Capabilities:

• Manage applications and servers within allocated resources
• Invite users with limited roles
• View organization-specific dashboards
• Create End User child organizations (if permitted)
• Configure application-level settings

Restrictions:

• Cannot create additional Sub-User siblings
• Limited administrative capabilities
• Must operate within parent's resource quotas
• Requires Starter or higher license tier

Use Cases:

• Development team within a customer organization
• Project-specific resource allocation
• Geographic regional subdivision

4. End User Organization

Definition: Leaf-level organizations with no children, representing individual users or smallest organizational units.

Capabilities:

• Deploy and manage applications
• Configure application settings
• Monitor application performance
• Manage team members (if licensed)

Restrictions:

• Cannot create child organizations
• Minimal administrative features
• Operates within strict resource quotas
• Starter license sufficient for basic usage

Use Cases:

• Individual developer or small team
• Single project or application
• Trial/evaluation accounts

Hierarchy Relationships

Parent-Child Data Flow:

Top Branch (Acme Cloud Platform)
│
├─ Master Branch (TechCorp Solutions) [inherits branding]
│  │
│  ├─ Sub-User (Engineering Team) [inherits quotas]
│  │  │
│  │  └─ End User (DevOps Project) [isolated resources]
│  │
│  └─ Sub-User (Marketing Team)
│
└─ Master Branch (StartupXYZ) [separate hierarchy]
   │
   └─ End User (Production Environment)

Key Principles:

1. Inheritance: Children inherit branding, settings, and quota limits from parents
2. Isolation: Resources are scoped to organization hierarchy, preventing cross-contamination
3. Aggregation: Parent organizations see aggregated usage from all descendants
4. Delegation: Parents can delegate specific permissions to children

Data Isolation and Scoping

Every database query in Coolify Enterprise is automatically scoped to the user's organizational context using Laravel global scopes:

Automatic Scoping Example:

// User belongs to organization ID 42
Auth::user()->currentOrganization; // Organization #42

// All queries automatically scoped
Server::all(); // Returns only servers owned by org #42
Application::all(); // Returns only apps owned by org #42

// Manual scope override (admin only)
Server::withoutGlobalScope(OrganizationScope::class)->get(); // All servers

Cross-Organization Access:

• Prohibited by Default: Users cannot access resources from other organizations
• Parent Access: Parents can view (read-only) descendant resources
• Admin Override: Platform admins can bypass scoping for support tasks

Security Implementation:

// Middleware ensures organization context
class EnsureOrganizationContext
{
    public function handle($request, Closure $next)
    {
        if (!auth()->user()->currentOrganization) {
            return redirect()->route('organization.select');
        }

        // Set global organization context
        app()->instance('current_organization', auth()->user()->currentOrganization);

        return $next($request);
    }
}

Organizational Best Practices

1. Structure Design

Flat vs Hierarchical:

• Flat: Single Top Branch with many Master Branch children (simpler, less overhead)
• Hierarchical: Deep nesting for complex business structures (more control, more complexity)

Recommendation: Start flat, add hierarchy only when organizational separation is required

2. Naming Conventions

• Slugs: Use URL-friendly identifiers (acme-cloud, not Acme Cloud Platform)
• Display Names: Use full business names for clarity
• Consistency: Maintain naming patterns across hierarchy levels

Example:

Top Branch: acme-cloud (Acme Cloud Platform)
├─ Master: acme-techcorp (TechCorp Solutions)
│  └─ Sub-User: acme-techcorp-eng (Engineering Team)
└─ Master: acme-startupxyz (StartupXYZ)

3. Resource Allocation

Quota Planning:

• Top Branch: Allocate 80% of total resources to children, reserve 20% for overhead
• Master Branch: Distribute quotas based on customer tier/contract
• Sub-User: Provide just enough for team needs, avoid over-provisioning

Monitoring:

• Set up alerts at 75% quota utilization
• Review usage weekly for optimization opportunities
• Plan capacity increases before hitting limits

Chapter 3: User Management

User Roles and Permissions

Coolify Enterprise implements organization-scoped roles where a single user can have different roles across multiple organizations.

Role Hierarchy (highest to lowest privilege):

1. Owner - Full control, cannot be removed by others
2. Admin - Nearly full control, can manage users and settings
3. Member - Standard access, can deploy applications
4. Viewer - Read-only access, cannot make changes

Permission Matrix:

Action	Owner	Admin	Member	Viewer
View resources	✅	✅	✅	✅
Deploy applications	✅	✅	✅	❌
Manage servers	✅	✅	⚠️ Limited	❌
Invite users	✅	✅	❌	❌
Modify settings	✅	✅	❌	❌
Manage billing	✅	⚠️ View only	❌	❌
Delete organization	✅	❌	❌	❌
Manage white-label	✅	✅	❌	❌
Create child orgs	✅	✅	❌	❌

Role Assignment Examples:

// User has different roles in different organizations
$user->organizations->map(fn($org) => [
    'organization' => $org->name,
    'role' => $org->pivot->role,
]);

// Output:
[
    ['organization' => 'Acme Cloud Platform', 'role' => 'owner'],
    ['organization' => 'TechCorp Solutions', 'role' => 'admin'],
    ['organization' => 'Engineering Team', 'role' => 'member'],
]

Inviting Users to Organizations

Invitation Workflow:

1. Admin generates invitation link or email
2. User receives invitation with organization context
3. User accepts invitation (creates account if needed)
4. System assigns specified role in organization
5. User can now access organization resources

Via UI:

1. Navigate to Settings → Organizations → [Organization Name] → Team
2. Click Invite User
3. Enter email address
4. Select role from dropdown
5. Optionally add custom message
6. Click Send Invitation

Via Artisan Command:

$ php artisan organization:invite \
    --organization=acme-cloud \
    --email=john@example.com \
    --role=admin \
    --message="Welcome to Acme Cloud Platform"

Invitation sent successfully to john@example.com
Invitation link: https://coolify.acme.com/invite/a1b2c3d4

Via API:

POST /api/v1/organizations/{organization}/invitations
Content-Type: application/json
Authorization: Bearer {api_token}

{
    "email": "john@example.com",
    "role": "admin",
    "message": "Welcome to Acme Cloud Platform",
    "expires_in_days": 7
}

// Response
{
    "success": true,
    "invitation": {
        "id": 123,
        "email": "john@example.com",
        "role": "admin",
        "token": "a1b2c3d4e5f6",
        "expires_at": "2025-01-20T12:00:00Z",
        "invitation_url": "https://coolify.acme.com/invite/a1b2c3d4"
    }
}

Managing User Access

Changing User Roles:

# Via Artisan
$ php artisan organization:change-role \
    --organization=acme-cloud \
    --user=john@example.com \
    --role=member

Role updated successfully

Removing Users:

# Via Artisan
$ php artisan organization:remove-user \
    --organization=acme-cloud \
    --user=john@example.com \
    --confirm

User john@example.com removed from organization 'Acme Cloud Platform'

Via API:

// Update role
PUT /api/v1/organizations/{organization}/users/{user}
{
    "role": "member"
}

// Remove user
DELETE /api/v1/organizations/{organization}/users/{user}

Role-Based Access Control (RBAC)

Laravel Policy Implementation:

// OrganizationPolicy.php
public function update(User $user, Organization $organization): bool
{
    return $user->hasRoleInOrganization($organization, ['owner', 'admin']);
}

public function delete(User $user, Organization $organization): bool
{
    return $user->hasRoleInOrganization($organization, 'owner');
}

// Usage in controllers
$this->authorize('update', $organization);

Blade Directives:

@can('update', $organization)
    <button>Edit Organization</button>
@endcan

@canany(['owner', 'admin'], $organization)
    <a href="{{ route('organization.settings', $organization) }}">Settings</a>
@endcanany

Chapter 4: License Management

License Types Overview

Coolify Enterprise offers four license tiers with progressively more features:

1. Starter License

Target Audience: Individual developers, small teams, evaluation users

Key Features:

• 1 organization
• Up to 5 servers
• Up to 10 applications
• 50 deployments/month
• Standard deployment strategies
• Email support

Restrictions:

• ❌ No white-label branding
• ❌ No child organizations
• ❌ No Terraform provisioning
• ❌ No advanced deployment strategies
• ❌ No priority support

Pricing: $29/month