Setup Console for the First Time
Requires:
- Access to
Console - Access to
Keycloak
Automatic admin promotion does not require backend pod access. Access to the backend pod is required only if you use the manual promotion fallback.
Prerequisites
Configure Keycloak for Console before continuing.
GitLab and Mattermost are optional integrations. If you enable them, follow Setup GitLab for Console and Setup Mattermost for Console.
1. Required Environment Variables
Ensure these variables are set to expected values in the Console deployment configuration before continuing. If Console is already deployed and configured, confirm these settings with the platform engineer responsible for the deployment; you do not need to enter the backend pod to complete automatic admin promotion.
| Environment Variable | Default | Values | Description |
|---|---|---|---|
| CONSOLE_BACKEND_DATABASE | postgres | string | Choose either "postgres" service or "sqlite" in-memory database |
| PG_DB | postgres | string | Name of the PostgreSQL database that console will use. |
| PG_USERNAME | postgres | string | Username console will use to access the PostgreSQL database |
| PG_PASSWORD | postgres | string | Password console will use to access the PostgreSQL database |
| PG_HOST | db | string | Hostname of the PostgreSQL service |
| PG_PORT | 5432 | integer | Port of the PostgreSQL service |
| VALID_HOSTS | None | comma-separated URLs | Expects a comma-separated string of valid hostnames for the console service when making requests to console_backend |
| KEYCLOAK_BASE_URL | None | URL | Hostname of the Keycloak server instance |
| KEYCLOAK_REALM | None | string | The Keycloak realm that the console bot account belongs to. |
| KEYCLOAK_BOT_CLIENT_ID | None | string | Client ID for Keycloak service account used by organization admins for user creation |
| KEYCLOAK_BOT_CLIENT_SECRET | None | string | Client secret for Keycloak service account used by organization admins for user creation |
| KEYCLOAK_AUTHSERVICE_CLIENT_ID | authservice | string | Client ID in Keycloak realm that is set up for authservice operations, specifically redirect URIs |
| LOGOUT_URL | None | URL | Logout URL the user will be directed to |
| CONSOLE_BACKEND_CORS_WHITELIST | http://localhost:3000 | comma-separated URLs | Expects a comma-separated string with external URLs that should be allowed by the CORS policy. Important for accessing the Django admin panel. |
| KUBECONFIG | None | path | Path to the kubeconfig.yaml file. |
2. Optional Environment Variables
These variables should be setup for typical Console service integrations.
Platform Admin Group
KEYCLOAK_PLATFORM_ADMIN_GROUP defaults to _structsureAdmins. Set it to the exact Keycloak group name if your environment uses a different group, such as _smoothglueAdmins. The legacy _structsureAdmins group is also recognized. See first-admin prerequisites for the required permissions.
GitLab
Required for typical GitLab integration with Console.
| Environment Variable | Default | Values | Description |
|---|---|---|---|
| ENABLE_GITLAB | false | [true, false] | Enable the use of the GitLab service by console on behalf of the user. |
| GITLAB_BASE_URL | None | URL | No |
| GITLAB_PERSONAL_ACCESS_TOKEN | None | string | GitLab PAT string required for console to make authorized changes to GitLab |
| GITLAB_CONSOLE_SUPPORT_PROJECT_ID | None | integer | GitLab project ID where Console feedback issues are created. Required when GitLab support issue creation and feedback are enabled. |
| GITLAB_GENERATED_TEMPLATE_TOKEN_UPSTREAM_PROJECT_IDS | None | comma-separated project IDs | Optional GitLab package projects whose CI job-token group allowlists should include generated project subgroups for dependency installs. |
Mattermost
Required for typical Mattermost integration with Console
| Environment Variable | Default | Values | Description |
|---|---|---|---|
| ENABLE_MATTERMOST | None | [true, false] | Enables use of the Mattermost service by console on behalf of the user. |
| MATTERMOST_BASE_URL | None | URL | URL to the Mattermost service |
| MATTERMOST_PERSONAL_ACCESS_TOKEN | None | string | Mattermost PAT required for console to make authorized changes to Mattermost |
3. Create the First Platform Admin
Sign in with a Keycloak account in the configured realm that belongs to the group specified by KEYCLOAK_PLATFORM_ADMIN_GROUP (default: _structsureAdmins). When no Platform Admin role exists in Console, Console automatically adopts and promotes the eligible user, then provisions accounts and admin roles in enabled tools. A regular user signing in first does not prevent this setup.
Follow Create the First Platform Admin User in Console for prerequisites, verification, troubleshooting, and the manual promotion fallback.
4. Create a Django Admin Account
Follow this how-to:
5. Setting Up Grafana
Setting up Grafana requires linking the service (tool) and dashboards: