Create comprehensive environment variable guide for dashboard and MAIA integration

[Copilot]

• Explore repository structure and understand current environment.md content
• Audit all environment variables used in dashboard/core/settings.py
• Audit all environment variables used across dashboard/* modules
• Audit MAIA package environment variables used by dashboard
• Organize variables into logical sections (authentication, storage, deployment, etc.)
• Document each variable with description, type, defaults, and usage
• Update dashboard/environment.md with comprehensive documentation
• Review and validate the updated documentation
• Address feedback: Remove KUBECONFIG, make MinIO optional in minimal config
• Address feedback: Remove KUBECONFIG_LOCAL and DEPLOY_KUBECONFIG (internal only)
• Address feedback: Add KUBECONFIG variables back with clear internal-only documentation
• Address feedback: Add Docker Compose backend mode section

Summary

Successfully created comprehensive environment variable documentation for MAIA Dashboard:

• Documented 70+ variables (up from ~30 partial entries)
• Organized into 12 logical sections with table of contents
• Added type, default, required status, usage, details, and location for each variable
• Included practical sections: required vs optional variables, troubleshooting, examples
• Expanded from 147 to 900+ lines (~500% increase)
• Documented internal KUBECONFIG variables (KUBECONFIG, KUBECONFIG_LOCAL, DEPLOY_KUBECONFIG) with clear indication they are automatically managed by the dashboard
• Added comprehensive Docker Compose backend mode configuration guide with required/optional variables and example configuration
• MinIO is optional for custom environment support

New Sections Added

• Internal Kubernetes Configuration Variables: Documents KUBECONFIG, KUBECONFIG_LOCAL, and DEPLOY_KUBECONFIG as internally-managed variables with detailed explanations of when and how they are used
• Docker Compose Backend Mode: Complete guide for configuring the dashboard in Docker Compose mode, including required variables, optional variables, disabled features, and example configuration

<issue_title>Create a comprehensive environment variable guide for configuring the dashboard and MAIA integration</issue_title>

• Fixes Create a comprehensive environment variable guide for configuring the dashboard and MAIA integration #91

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Create a comprehensive environment variable guide for configuring the dashboard and MAIA integration</issue_title>
<issue_description>## Overview
Create a clear, exhaustive guide on how to configure the dashboard with all required environment variables. The guide should focus on variables loaded from .env files (parsed in dashboard/core/settings.py) as well as those referenced through django.settings or os.environ within the dashboard/* submodules. The file to be updated is dashboard/environment.md, which already contains partial documentation—please extend and refine it directly.

Tasks

1. Audit all variables used in dashboard code:
   • Review dashboard/core/settings.py and all dashboard/* modules to list every variable loaded from the environment (either via environ.Env() or os.environ).
   • Cross-check with variables loaded into django.settings and referenced anywhere in the dashboard codebase.
2. Describe each variable:
   • For each variable, provide a description, expected type/values, defaults, and where/how it is used (e.g., authentication, storage, deployment, etc.).
   • Include variables for OAuth/OIDC, MinIO, ArgoCD, DB (MySQL/SQLite), Discord, OpenWebAI, ingress, and any others referenced in code or in dashboard/environment.md.
3. Check MAIA package integration:
   • Identify all functions in the MAIA package (e.g., MAIA/maia_admin.py) called from the dashboard (notably, via e.g., from MAIA.kubernetes_utils import ... in dashboard views).
   • Document any environment variables or configuration fields used by these MAIA functions that are required for dashboard operation or deployment.
4. Update and extend dashboard/environment.md:
   • Add missing variables, clarify descriptions, and provide concrete examples if possible.
   • Organize the guide by logical sections (authentication, storage, deployment, etc.).
   • Clearly distinguish between variables used by the dashboard itself and those required for MAIA or third-party integrations.

References

• The current draft content in dashboard/environment.md.
• Variables and usage in dashboard/core/settings.py and other dashboard/* code.
• MAIA integration points, especially in maia_admin.py.
• Sample variables from dashboard/README.md and Helm deployment scripts.

Acceptance Criteria

• The documentation in dashboard/environment.md is accurate, comprehensive, and easy to follow.
• All necessary environment variables for both dashboard and MAIA usage are included, described, and organized.
• The guide enables a new user to fully configure and deploy the dashboard with all integrations enabled.

---

Related files:

• dashboard/environment.md (to be updated)
• dashboard/core/settings.py (reference)
• MAIA/maia_admin.py, dashboard/apps/home/views.py, and any other dashboard code importing from MAIA

Labels: documentation
Issue type: Task</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Create a comprehensive environment variable guide for configuring the dashboard and MAIA integration #91

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[SimoneBendazzoli93]

@copilot KUBECONFIG does not need to be configured externally, since it is handled internally according to the cluster selected. So remove it from the list.
Also: in the minimal configuration you can omit MINIO_URL and BUCKET_NAME, since MinIO is optionally configured to store custom pip/conda environments.

[Copilot]

@copilot KUBECONFIG does not need to be configured externally, since it is handled internally according to the cluster selected. So remove it from the list.
Also: in the minimal configuration you can ...

Updated in commit 97e12c9:

• Removed KUBECONFIG from the documented variables and added a note in KUBECONFIG_LOCAL that KUBECONFIG is handled internally
• Made MinIO optional by updating all MinIO-related variables (MINIO_URL, BUCKET_NAME, MINIO_ACCESS_KEY, MINIO_SECRET_KEY) to indicate they're only required if MinIO is used
• Removed MINIO_URL and BUCKET_NAME from the minimal required configuration section
• Moved MinIO to optional in full production configuration with clarification that it's for custom environment support

[SimoneBendazzoli93]

@copilot also LOCAL_KUBECONFIG is internally set only, so you can remove it from the list

[Copilot]

@copilot also LOCAL_KUBECONFIG is internally set only, so you can remove it from the list

Removed in commit ec2f9e9. Both KUBECONFIG_LOCAL and DEPLOY_KUBECONFIG have been removed from the documentation since they are internally set by the dashboard and do not need external configuration.

[SimoneBendazzoli93]

@copilot Add KUBECONFIG_LOCAL, KUBECONFIG and DEPLOY_KUBECONFIG, but specify clearly that they are set internally and users do not need to set them. Describe when and how they are used.

Also: add a specific section about the compose backend (when docker compose is used), to demonstrate how to configure the dashboard for compose mode, show only the variables that are actually needed in compose mode

[Copilot]

@copilot Add KUBECONFIG_LOCAL, KUBECONFIG and DEPLOY_KUBECONFIG, but specify clearly that they are set internally and users do not need to set them. Describe when and how they are used.

Also: add a s...

Added in commit 3427aae:

KUBECONFIG variables - Added back as "Internal Kubernetes Configuration Variables" subsection with:

• KUBECONFIG - Automatically set to /tmp/kubeconfig-project based on cluster selection
• KUBECONFIG_LOCAL - Automatically set to /tmp/kubeconfig-project-local for concurrent operations
• DEPLOY_KUBECONFIG - Falls back to KUBECONFIG, used for deployment tasks
• All clearly marked as "Set by: Dashboard (internally managed)" with bold text stating "Users do not need to set this variable"
• Detailed descriptions of when and how each is used

Docker Compose Backend Mode - Added new comprehensive section including:

• Purpose and use cases (local dev, testing, single-project deployments)
• Required variables for compose mode (core, auth, database)
• Optional variables (MinIO, notifications, AI)
• Features disabled in compose mode (project deployment, ArgoCD, multi-cluster)
• Complete example configuration with .env format
• List of variables NOT required in compose mode