docs(cloud): update deployment guide headings and add comprehensive YAML config details

Co-authored-by: pontusringblom <170570911+pontusringblom@users.noreply.github.com>

Author: Copilot

content/en/cloud/self-hosted/deployment/_index.md

@@ -8,7 +8,7 @@ weight: 2
 
 ## High-level List of Deployment Tasks
 
-## Environment Variables
+## High-level List of Deployment Tasks
 
 ### INIT_CONFIG
 
@@ -32,6 +32,7 @@ export INIT_CONFIG='{"provider": {"name": "my-provider", "settings": {...}}}'
 For Docker deployments:
 
 ```bash
+# example
 docker run -e INIT_CONFIG='{"provider": {"name": "my-provider"}}' layer5/meshery-cloud
 ```
 

content/en/cloud/self-hosted/planning/_index.md

@@ -17,6 +17,106 @@ Before deploying, plan your configuration approach:
 3. **Configuration Management**: Decide how configuration will be managed (environment variables, secrets, config files)
 4. **Update Strategy**: Plan for configuration updates and changes over time
 
+### Provider Admin Organization Initialization
+
+The Provider Admin organization is a special organization identified by the hardcoded UUID `11111111-1111-1111-1111-111111111111`. It represents the root administrative organization for the cloud platform.
+
+#### Configuration Format
+
+The `INIT_CONFIG` environment variable accepts a YAML configuration with the following structure:
+
+```yaml
+organization:
+  name: "Layer5"
+  description: "The uber organization for all things Layer5."
+  country: "United States"
+  region: "North America"
+
+user:
+  first_name: "Admin"
+  last_name: "User"
+  email: "admin@layer5.io"
+  username: "admin@layer5.io"  # Optional, defaults to email if not provided
+  password: "change-me-on-first-login"  # Required
+```
+
+#### Setting the Environment Variable
+
+To enable Provider Admin organization initialization, set the `INIT_CONFIG` environment variable with the entire YAML configuration as its value:
+
+```bash
+INIT_CONFIG='organization:
+  name: "Layer5"
+  description: "The uber organization for all things Layer5."
+  country: "United States"
+  region: "North America"
+
+user:
+  first_name: "Admin"
+  last_name: "User"
+  email: "admin@layer5.io"
+  username: "admin@layer5.io"
+  password: "change-me-on-first-login"'
+```
+
+#### Required and Optional Fields
+
+**Organization:**
+- `name`: Name of the provider organization (required)
+- `description`: Description of the organization (optional)
+- `country`: Country where the organization is located (optional)
+- `region`: Region where the organization is located (optional)
+
+**User:**
+- `first_name`: First name of the provider admin user (required)
+- `last_name`: Last name of the provider admin user (required)
+- `email`: Email address of the provider admin user (required)
+- `username`: Username for the provider admin user (optional, defaults to email)
+- `password`: Password for the provider admin user (required)
+
+#### Initialization Process
+
+When the server starts and `INIT_CONFIG` is set:
+
+1. The YAML configuration is parsed and validated
+2. The system checks if the provider organization already exists (by UUID `11111111-1111-1111-1111-111111111111`)
+3. If the organization exists, initialization is skipped
+4. If the organization does not exist:
+   - Kratos identity is created with password credentials for authentication
+   - Provider admin user is created
+   - Admin and MeshMap roles are assigned to the user
+   - Provider organization is created with the hardcoded UUID
+   - User is added to the provider organization with organization admin role
+
+#### Idempotency
+
+The initialization process is idempotent:
+- Running the server multiple times with the same configuration will not create duplicate organizations
+- If the provider organization already exists, the initialization is skipped
+- No errors are thrown if the organization already exists
+
+#### Error Handling
+
+If initialization fails:
+- Errors are logged using MeshKit logger
+- The server continues to start (non-fatal error)
+- All database operations are wrapped in a transaction for atomicity
+- If any step fails, all changes are rolled back
+
+### Deployment Options
+
+You can set the `INIT_CONFIG` environment variable using several methods:
+
+**Option A (Helm with inline values)**: Include `initConfig` in the Helm `values.yaml` file with the YAML configuration as a multiline string
+
+**Option B (Helm with --set-file flag)**: Use `--set-file` to load configuration from a separate file:
+```bash
+helm install meshery-cloud ./install/kubernetes/helm/layer5-cloud \
+  --set-file env.initConfig=./config/provider-init.yaml.example
+```
+
+**Option C (Direct environment variable)**: Set the `INIT_CONFIG` environment variable with the YAML content as a string
+
 ### Using INIT_CONFIG for Automated Setup
 
 The `INIT_CONFIG` environment variable allows you to pre-configure your provider during deployment, eliminating manual setup steps. This is particularly valuable for:
@@ -25,7 +125,7 @@ The `INIT_CONFIG` environment variable allows you to pre-configure your provider
 - **CI/CD Integration**: Automate deployments with predefined configurations
 - **Infrastructure as Code**: Manage provider configuration alongside your infrastructure
 
-For detailed usage and examples, see the [Deployment Guide](/cloud/self-hosted/deployment/#init_config).
+For detailed configuration options, see the configuration schema below.
 
 {{< alert type="warning" title="Important" >}}
 Plan your INIT_CONFIG carefully as it is only processed during initial startup. Changes require redeployment or manual configuration updates.