Improve LD_SETUP Environment Variables Documentation #159
Description
Problem
Current documentation for LD_SETUP environment variables is misleading customers into thinking it's an "all or nothing" configuration. This creates confusion for teams who want to use only specific setup features (like admin assignment and email domain restrictions) without configuring project-related variables.
Current Issue
- Documentation at https://docs.lightdash.com/self-host/customize-deployment/environment-variables#initialize-instance appears to suggest all variables are needed together
- Customers are unclear which variables are required vs optional
- No clear guidance on which variables can be skipped for specific use cases
Customer Impact
- Support tickets asking for clarification (like Josh's case where they use CircleCI for deployments but want admin/domain setup)
- Potential over-configuration of environments
- Confusion about minimal setup requirements
Requested Improvements
1. Clear categorization of variables:
- Required:
LD_SETUP_ADMIN_EMAIL,LD_SETUP_PROJECT_PAT - Optional - Admin Setup:
LD_SETUP_ADMIN_NAME,LD_SETUP_ADMIN_API_KEY - Optional - Organization:
LD_SETUP_ORGANIZATION_EMAIL_DOMAIN,LD_SETUP_ORGANIZATION_DEFAULT_ROLE - Optional - Project Setup: All
LD_SETUP_PROJECT_*,LD_SETUP_GITHUB_*,LD_SETUP_DBT_*
2. Use case examples showing:
- Minimal setup (admin only)
- Admin + organization controls (no project setup)
- Full automated setup
3. Clear statement that project-related variables can be skipped if using external CI/CD
Reference
Logic can be found in parseConfig.ts -> getInitialSetupConfig
This would prevent similar support requests and make self-hosting setup much clearer for different deployment scenarios.