From 94c3703acad1dae35ce7fddace217684cef7e203 Mon Sep 17 00:00:00 2001 From: Michael Barz Date: Fri, 4 Jul 2025 10:33:01 +0200 Subject: [PATCH] change: increase importance of setting a custom admin password --- .env.example | 17 ++++++------ README.md | 65 ++++++++++++++++++++++++++++++---------------- docker-compose.yml | 2 ++ 3 files changed, 52 insertions(+), 32 deletions(-) diff --git a/.env.example b/.env.example index 3150014..39e3f32 100644 --- a/.env.example +++ b/.env.example @@ -80,6 +80,14 @@ OC_DOMAIN= # If demo users is set to "true", the following user accounts are created automatically: # alan, mary, margaret, dennis and lynn - the password is 'demo' for all. DEMO_USERS= +# Admin Password for the OpenCloud admin user. +# NOTE: This is only needed when using the built-in LDAP server (idm). +# If you are using an external LDAP server, the admin password is managed by the LDAP server. +# NOTE: This variable needs to be set before the first start of OpenCloud. Changes to this variable after the first start will be IGNORED. +# If not set, opencloud will not work properly. The container will be restarting. +# After the first initialization, the admin password can only be changed via the OpenCloud User Settings UI or by using the OpenCloud CLI. +# Documentation: https://docs.opencloud.eu/docs/admin/resources/common-issues#-change-admin-password-set-in-env +INITIAL_ADMIN_PASSWORD= # Define the openCloud loglevel used. # LOG_LEVEL= @@ -101,15 +109,6 @@ LOG_LEVEL= # NOTE: you need to restart the openCloud container to load the new extensions. # OC_APPS_DIR=/your/local/opencloud/apps -## OpenCloud Admin Password ## -# The password for the OpenCloud admin user. -# The admin user password is randomly generated on the first start of OpenCloud. -# It will be printed to the console. You can access it by running the following command: -# `docker compose logs opencloud | grep -B 1 -A 4 "generated OpenCloud Config"` -# The password is stored in the OpenCloud configuration file. -# It can only be changed via the OpenCloud User Settings UI or by using the OpenCloud CLI. -# https://docs.opencloud.eu/docs/admin/resources/common-issues#-change-admin-password-set-in-env - # S3 Storage configuration - optional # OpenCloud supports S3 storage as primary storage. diff --git a/README.md b/README.md index 9cba3e3..52e391c 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,7 @@ OpenCloud Compose offers a modular approach to deploying OpenCloud with several 5. **Access OpenCloud**: - URL: https://cloud.opencloud.test - Username: `admin` - - Password: is randomly generated on the first start of OpenCloud. - It will be printed to the console. You can access it by running the following command: - `docker compose logs opencloud | grep -B 1 -A 4 "generated OpenCloud Config"` + - Password: Set via `INITIAL_ADMIN_PASSWORD` environment variable in your `.env` file ### Production Deployment @@ -309,29 +307,50 @@ The configuration is managed through environment variables in the `.env` file: Key variables: -| Variable | Description | Default | -|------------------------------------|-------------------------------------------------------|------------------------------| -| `COMPOSE_FILE` | Colon-separated list of compose files to use | (commented out) | -| `OC_DOMAIN` | OpenCloud domain | cloud.opencloud.test | -| `OC_DOCKER_TAG` | OpenCloud image tag | latest | -| `OC_CONFIG_DIR` | Config directory path | (Docker volume) | -| `OC_DATA_DIR` | Data directory path | (Docker volume) | -| `INSECURE` | Skip certificate validation | true | -| `COLLABORA_DOMAIN` | Collabora domain | collabora.opencloud.test | -| `WOPISERVER_DOMAIN` | WOPI server domain | wopiserver.opencloud.test | -| `TIKA_IMAGE` | Apache Tika image tag | apache/tika:latest-full | -| `KEYCLOAK_DOMAIN` | Keycloak domain | keycloak.opencloud.test | -| `KEYCLOAK_ADMIN` | Keycloak admin username | kcadmin | -| `KEYCLOAK_ADMIN_PASSWORD` | Keycloak admin password | admin | -| `LDAP_BIND_PASSWORD` | LDAP password for the bind user | admin | -| `KC_DB_USERNAME` | Database user for keycloak | keycloak | -| `KC_DB_PASSWORD` | Database password for keycloak | keycloak | -| `TRAEFIK_LETSENCRYPT_EMAIL` | Email Address for the Let's Encrypt ACME challenge | example@example.org | -| `TRAEFIK_SERVICES_TLS_CONFIG` | Tell traefik and the services which TLS config to use | tls.certresolver=letsencrypt | -| `TRAEFIK_CERTS_DIR` | Directory for custom certificates. | ./certs | +| Variable | Description | Default | +|-------------------------------|-------------------------------------------------------|------------------------------| +| `COMPOSE_FILE` | Colon-separated list of compose files to use | (commented out) | +| `OC_DOMAIN` | OpenCloud domain | cloud.opencloud.test | +| `INITIAL_ADMIN_PASSWORD ` | OpenCloud password for the admin user | (no value) | +| `OC_DOCKER_TAG` | OpenCloud image tag | latest | +| `OC_CONFIG_DIR` | Config directory path | (Docker volume) | +| `OC_DATA_DIR` | Data directory path | (Docker volume) | +| `INSECURE` | Skip certificate validation | true | +| `COLLABORA_DOMAIN` | Collabora domain | collabora.opencloud.test | +| `WOPISERVER_DOMAIN` | WOPI server domain | wopiserver.opencloud.test | +| `TIKA_IMAGE` | Apache Tika image tag | apache/tika:latest-full | +| `KEYCLOAK_DOMAIN` | Keycloak domain | keycloak.opencloud.test | +| `KEYCLOAK_ADMIN` | Keycloak admin username | kcadmin | +| `KEYCLOAK_ADMIN_PASSWORD` | Keycloak admin password | admin | +| `LDAP_BIND_PASSWORD` | LDAP password for the bind user | admin | +| `KC_DB_USERNAME` | Database user for keycloak | keycloak | +| `KC_DB_PASSWORD` | Database password for keycloak | keycloak | +| `TRAEFIK_LETSENCRYPT_EMAIL` | Email Address for the Let's Encrypt ACME challenge | example@example.org | +| `TRAEFIK_SERVICES_TLS_CONFIG` | Tell traefik and the services which TLS config to use | tls.certresolver=letsencrypt | +| `TRAEFIK_CERTS_DIR` | Directory for custom certificates. | ./certs | See `.env.example` for all available options and their documentation. +### Admin Password Configuration + +The `INITIAL_ADMIN_PASSWORD` environment variable is **required** for OpenCloud to work properly: + +- **Only needed when using the built-in LDAP server (idm)** +- **Must be set before the first start of OpenCloud. Changes in the ENV variable after the first startup will be ignored.** +- If not set, OpenCloud will not work properly and the container will keep restarting +- After first initialization, the admin password can only be changed via: + - OpenCloud User Settings UI + - OpenCloud CLI + +For external LDAP servers, the admin password is managed by the LDAP server itself. + +**Important**: Set this variable in your `.env` file before starting OpenCloud for the first time: +``` +INITIAL_ADMIN_PASSWORD=your-secure-password-here +``` + +For more details, see the [OpenCloud documentation](https://docs.opencloud.eu/docs/admin/resources/common-issues#-change-admin-password-set-in-env). + ### Persistent Storage For production, configure persistent storage: diff --git a/docker-compose.yml b/docker-compose.yml index 02b187b..e6846e9 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -27,6 +27,8 @@ services: PROXY_ENABLE_BASIC_AUTH: "${PROXY_ENABLE_BASIC_AUTH:-false}" # demo users IDM_CREATE_DEMO_USERS: "${DEMO_USERS:-false}" + # admin password + IDM_ADMIN_PASSWORD: "${INITIAL_ADMIN_PASSWORD}" # email server (if configured) NOTIFICATIONS_SMTP_HOST: "${SMTP_HOST}" NOTIFICATIONS_SMTP_PORT: "${SMTP_PORT}"