From ce026301e42cd5435d95b58f8fc484ba5ad3cba5 Mon Sep 17 00:00:00 2001 From: Jakob Scheumann Date: Wed, 20 Sep 2023 13:40:01 +0200 Subject: [PATCH 1/5] Move configuration variables from docker-compose.yaml into a dedicated file. --- .env | 1 + README.md | 10 ++++++---- docker-compose.yaml | 26 ++++++++++++++++---------- mailman.cfg | 22 ++++++++++++++++++++++ 4 files changed, 45 insertions(+), 14 deletions(-) create mode 120000 .env create mode 100644 mailman.cfg diff --git a/.env b/.env new file mode 120000 index 00000000..f75e150d --- /dev/null +++ b/.env @@ -0,0 +1 @@ +mailman.cfg \ No newline at end of file diff --git a/README.md b/README.md index c5988de6..ed377912 100644 --- a/README.md +++ b/README.md @@ -121,8 +121,10 @@ For other systems, you can read the official Docker documentation to install ## Configuration -Most of the common configuration is handled through environment variables in the -`docker-compose.yaml`. However, there is need for some extra configuration that +Most of the common configuration is defined in `mailman.cfg`. Further custom +environment variables should be set via a newly created docker-compose.override.yaml. + +Additionally, there is need for some extra configuration that interacts directly with the application. There are two configuration files on the host that interact directly with Mailman's settings. These files exist on the host running the containers and are imported at runtime in the containers. @@ -151,7 +153,7 @@ mounted inside the containers. container. ### Mailman-web -These are the settings that you MUST change in your docker-compose.yaml before deploying: +These are the settings that you MUST change in your mailman.cfg before deploying: - `SERVE_FROM_DOMAIN`: The domain name from which Django will be served. To be added to `ALLOWED_HOSTS` in django settings. Default value is not set. This @@ -190,7 +192,7 @@ For more details on how to configure this image, please look at ### Mailman-Core -These are the variables that you MUST change in your docker-compose.yaml before deploying: +These are the variables that you MUST change in your mailman.cfg before deploying: - `HYPERKITTY_API_KEY`: Hyperkitty's API Key, should be set to the same value as set for the mailman-web. Skip the variable in case of non-Hyperkitty deployment. diff --git a/docker-compose.yaml b/docker-compose.yaml index 58d1d786..a15c049d 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -13,10 +13,11 @@ services: depends_on: - database environment: - - DATABASE_URL=postgresql://mailman:mailmanpass@database/mailmandb - - DATABASE_TYPE=postgres - - DATABASE_CLASS=mailman.database.postgresql.PostgreSQLDatabase - - HYPERKITTY_API_KEY=someapikey + - DATABASE_URL=${DATABASE_URL_SCHEMA}://${POSTGRES_USER}:${POSTGRES_PASSWORD}@database/${POSTGRES_DB} + - DATABASE_TYPE=${DATABASE_TYPE} + - DATABASE_CLASS=${DATABASE_CLASS} + - HYPERKITTY_API_KEY=${HYPERKITTY_API_KEY} + - TZ=${TZ} ports: - "127.0.0.1:8001:8001" # API - "127.0.0.1:8024:8024" # LMTP - incoming emails @@ -35,9 +36,14 @@ services: volumes: - /opt/mailman/web:/opt/mailman-web-data environment: - - DATABASE_TYPE=postgres - - DATABASE_URL=postgresql://mailman:mailmanpass@database/mailmandb - - HYPERKITTY_API_KEY=someapikey + - DATABASE_URL=${DATABASE_URL_SCHEMA}://${POSTGRES_USER}:${POSTGRES_PASSWORD}@database/${POSTGRES_DB} + - DATABASE_TYPE=${DATABASE_TYPE} + - HYPERKITTY_API_KEY=${HYPERKITTY_API_KEY} + - SECRET_KEY=${DJANGO_SECRET_KEY} + - TZ=${TZ} + - SERVE_FROM_DOMAIN=${SERVE_FROM_DOMAIN} + - MAILMAN_ADMIN_USER=${MAILMAN_ADMIN_USER} + - MAILMAN_ADMIN_EMAIL=${MAILMAN_ADMIN_EMAIL} ports: - "127.0.0.1:8000:8000" # HTTP - "127.0.0.1:8080:8080" # uwsgi @@ -46,9 +52,9 @@ services: database: environment: - - POSTGRES_DB=mailmandb - - POSTGRES_USER=mailman - - POSTGRES_PASSWORD=mailmanpass + - POSTGRES_DB=${POSTGRES_DB} + - POSTGRES_USER=${POSTGRES_USER} + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} image: postgres:11-alpine volumes: - /opt/mailman/database:/var/lib/postgresql/data diff --git a/mailman.cfg b/mailman.cfg new file mode 100644 index 00000000..79316696 --- /dev/null +++ b/mailman.cfg @@ -0,0 +1,22 @@ +# Please set these as explained in README.md +SERVE_FROM_DOMAIN= +MAILMAN_ADMIN_USER= +MAILMAN_ADMIN_EMAIL= + +# only use URL safe characters for the secrets, else you will break at least the DATABASE_URL +# i.e. do not use blanks ; / ? : @ = & < > # % { } | \ ^ ~ [ ] ` +# you can use a commandline like `openssl rand -hex 24` to generate pseudo-random values for these secrets +HYPERKITTY_API_KEY= +POSTGRES_PASSWORD= +DJANGO_SECRET_KEY= + +# you might want to change the timezone to your local one +TZ=UTC + +# likely, you don't need to change these: +DATABASE_URL_SCHEMA=postgresql +DATABASE_TYPE=postgres +DATABASE_CLASS=mailman.database.postgresql.PostgreSQLDatabase +POSTGRES_DB=mailmandb +POSTGRES_USER=mailman + From 69e0a726cbe797ca24e674c8db4e65bd24be2244 Mon Sep 17 00:00:00 2001 From: Jakob Scheumann Date: Mon, 13 Nov 2023 12:41:57 +0100 Subject: [PATCH 2/5] Use a plain .env file --- .env | 23 ++++++++++++++++++++++- README.md | 6 +++--- mailman.cfg | 22 ---------------------- 3 files changed, 25 insertions(+), 26 deletions(-) mode change 120000 => 100644 .env delete mode 100644 mailman.cfg diff --git a/.env b/.env deleted file mode 120000 index f75e150d..00000000 --- a/.env +++ /dev/null @@ -1 +0,0 @@ -mailman.cfg \ No newline at end of file diff --git a/.env b/.env new file mode 100644 index 00000000..79316696 --- /dev/null +++ b/.env @@ -0,0 +1,22 @@ +# Please set these as explained in README.md +SERVE_FROM_DOMAIN= +MAILMAN_ADMIN_USER= +MAILMAN_ADMIN_EMAIL= + +# only use URL safe characters for the secrets, else you will break at least the DATABASE_URL +# i.e. do not use blanks ; / ? : @ = & < > # % { } | \ ^ ~ [ ] ` +# you can use a commandline like `openssl rand -hex 24` to generate pseudo-random values for these secrets +HYPERKITTY_API_KEY= +POSTGRES_PASSWORD= +DJANGO_SECRET_KEY= + +# you might want to change the timezone to your local one +TZ=UTC + +# likely, you don't need to change these: +DATABASE_URL_SCHEMA=postgresql +DATABASE_TYPE=postgres +DATABASE_CLASS=mailman.database.postgresql.PostgreSQLDatabase +POSTGRES_DB=mailmandb +POSTGRES_USER=mailman + diff --git a/README.md b/README.md index ed377912..b1a851c5 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ For other systems, you can read the official Docker documentation to install ## Configuration -Most of the common configuration is defined in `mailman.cfg`. Further custom +Most of the common configuration is defined in `.env`. Further custom environment variables should be set via a newly created docker-compose.override.yaml. Additionally, there is need for some extra configuration that @@ -153,7 +153,7 @@ mounted inside the containers. container. ### Mailman-web -These are the settings that you MUST change in your mailman.cfg before deploying: +These are the settings that you MUST change in your `.env` before deploying: - `SERVE_FROM_DOMAIN`: The domain name from which Django will be served. To be added to `ALLOWED_HOSTS` in django settings. Default value is not set. This @@ -192,7 +192,7 @@ For more details on how to configure this image, please look at ### Mailman-Core -These are the variables that you MUST change in your mailman.cfg before deploying: +These are the variables that you MUST change in your `.env` before deploying: - `HYPERKITTY_API_KEY`: Hyperkitty's API Key, should be set to the same value as set for the mailman-web. Skip the variable in case of non-Hyperkitty deployment. diff --git a/mailman.cfg b/mailman.cfg deleted file mode 100644 index 79316696..00000000 --- a/mailman.cfg +++ /dev/null @@ -1,22 +0,0 @@ -# Please set these as explained in README.md -SERVE_FROM_DOMAIN= -MAILMAN_ADMIN_USER= -MAILMAN_ADMIN_EMAIL= - -# only use URL safe characters for the secrets, else you will break at least the DATABASE_URL -# i.e. do not use blanks ; / ? : @ = & < > # % { } | \ ^ ~ [ ] ` -# you can use a commandline like `openssl rand -hex 24` to generate pseudo-random values for these secrets -HYPERKITTY_API_KEY= -POSTGRES_PASSWORD= -DJANGO_SECRET_KEY= - -# you might want to change the timezone to your local one -TZ=UTC - -# likely, you don't need to change these: -DATABASE_URL_SCHEMA=postgresql -DATABASE_TYPE=postgres -DATABASE_CLASS=mailman.database.postgresql.PostgreSQLDatabase -POSTGRES_DB=mailmandb -POSTGRES_USER=mailman - From fe035c501438e1ed0c4fa5514b9315799338d02d Mon Sep 17 00:00:00 2001 From: Jakob Scheumann Date: Mon, 13 Nov 2023 13:43:24 +0100 Subject: [PATCH 3/5] Refactor variable names to be database_type independent --- .env | 10 +++------- docker-compose-mysql.yaml | 20 +++++++++++--------- docker-compose-postorius.yaml | 16 +++++++++------- docker-compose.yaml | 16 ++++++++-------- 4 files changed, 31 insertions(+), 31 deletions(-) diff --git a/.env b/.env index 79316696..28e8b603 100644 --- a/.env +++ b/.env @@ -7,16 +7,12 @@ MAILMAN_ADMIN_EMAIL= # i.e. do not use blanks ; / ? : @ = & < > # % { } | \ ^ ~ [ ] ` # you can use a commandline like `openssl rand -hex 24` to generate pseudo-random values for these secrets HYPERKITTY_API_KEY= -POSTGRES_PASSWORD= +DATABASE_PASSWORD= DJANGO_SECRET_KEY= # you might want to change the timezone to your local one TZ=UTC # likely, you don't need to change these: -DATABASE_URL_SCHEMA=postgresql -DATABASE_TYPE=postgres -DATABASE_CLASS=mailman.database.postgresql.PostgreSQLDatabase -POSTGRES_DB=mailmandb -POSTGRES_USER=mailman - +DATABASE_NAME=mailmandb +DATABASE_USER=mailman diff --git a/docker-compose-mysql.yaml b/docker-compose-mysql.yaml index 269cd72d..25dad312 100644 --- a/docker-compose-mysql.yaml +++ b/docker-compose-mysql.yaml @@ -12,10 +12,11 @@ services: - database:database depends_on: - database - environment: - - DATABASE_URL=mysql+pymysql://mailman:mailmanpass@database/mailmandb?charset=utf8mb4&use_unicode=1 # Do use mysql+pymysql:// here + environment: # + - DATABASE_URL=mysql+pymysql://${DATABASE_USER}:${DATABASE_PASSWORD}@database/${DATABASE_NAME}?charset=utf8mb4&use_unicode=1 # Do use mysql+pymysql:// here - DATABASE_TYPE=mysql - - HYPERKITTY_API_KEY=someapikey + - HYPERKITTY_API_KEY=${HYPERKITTY_API_KEY} + - TZ=${TZ} ports: - "127.0.0.1:8001:8001" # API - "127.0.0.1:8024:8024" # LMTP - incoming emails @@ -35,10 +36,11 @@ services: - /opt/mailman/web:/opt/mailman-web-data environment: - DATABASE_TYPE=mysql - - DATABASE_URL=mysql://mailman:mailmanpass@database/mailmandb?charset=utf8mb4 # Do use mysql:// here - - HYPERKITTY_API_KEY=someapikey - - SECRET_KEY=thisisaverysecretkey + - mysql+pymysql://${DATABASE_USER}:${DATABASE_PASSWORD}@database/${DATABASE_NAME}?charset=utf8mb4 # Do use mysql:// here + - HYPERKITTY_API_KEY=${HYPERKITTY_API_KEY} + - SECRET_KEY=${DJANGO_SECRET_KEY} - DYLD_LIBRARY_PATH=/usr/local/mysql/lib/ + - TZ=${TZ} ports: - "127.0.0.1:8000:8000" # HTTP - "127.0.0.1:8080:8080" # uwsgi @@ -47,9 +49,9 @@ services: database: environment: - MYSQL_DATABASE: mailmandb - MYSQL_USER: mailman - MYSQL_PASSWORD: mailmanpass + MYSQL_DATABASE: ${DATABASE_NAME} + MYSQL_USER: ${DATABASE_USER} + MYSQL_PASSWORD: ${DATABASE_PASSWORD} MYSQL_RANDOM_ROOT_PASSWORD: "yes" image: mariadb:10.5 command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci diff --git a/docker-compose-postorius.yaml b/docker-compose-postorius.yaml index 3bcfff7a..f3f4b2b5 100644 --- a/docker-compose-postorius.yaml +++ b/docker-compose-postorius.yaml @@ -13,9 +13,10 @@ services: depends_on: - database environment: - - DATABASE_URL=postgres://mailman:mailmanpass@database/mailmandb + - DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@database/${DATABASE_NAME} - DATABASE_TYPE=postgres - DATABASE_CLASS=mailman.database.postgresql.PostgreSQLDatabase + - TZ=${TZ} ports: - "127.0.0.1:8001:8001" # API - "127.0.0.1:8024:8024" # LMTP - incoming emails @@ -34,10 +35,11 @@ services: volumes: - /opt/mailman/web:/opt/mailman-web-data environment: + - DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@database/${DATABASE_NAME} - DATABASE_TYPE=postgres - - DATABASE_URL=postgres://mailman:mailmanpass@database/mailmandb - - SECRET_KEY=ksjdbaksdba - - UWSGI_STATIC_MAP=/static=/opt/mailman-web-data/static + - SECRET_KEY=${DJANGO_SECRET_KEY} + - UWSGI_STATIC_MAP=/static=/opt/mailman-web-data/static + - TZ=${TZ} ports: - "127.0.0.1:8000:8000" # HTTP - "127.0.0.1:8080:8080" # uwsgi @@ -46,9 +48,9 @@ services: database: environment: - POSTGRES_DB: mailmandb - POSTGRES_USER: mailman - POSTGRES_PASSWORD: mailmanpass + - POSTGRES_DB=${DATABASE_NAME} + - POSTGRES_USER=${DATABASE_USER} + - POSTGRES_PASSWORD=${DATABASE_PASSWORD} restart: always image: postgres:9.6-alpine volumes: diff --git a/docker-compose.yaml b/docker-compose.yaml index a15c049d..52d4af26 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -13,9 +13,9 @@ services: depends_on: - database environment: - - DATABASE_URL=${DATABASE_URL_SCHEMA}://${POSTGRES_USER}:${POSTGRES_PASSWORD}@database/${POSTGRES_DB} - - DATABASE_TYPE=${DATABASE_TYPE} - - DATABASE_CLASS=${DATABASE_CLASS} + - DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@database/${DATABASE_NAME} + - DATABASE_TYPE=postgres + - DATABASE_CLASS=mailman.database.postgresql.PostgreSQLDatabase - HYPERKITTY_API_KEY=${HYPERKITTY_API_KEY} - TZ=${TZ} ports: @@ -36,8 +36,8 @@ services: volumes: - /opt/mailman/web:/opt/mailman-web-data environment: - - DATABASE_URL=${DATABASE_URL_SCHEMA}://${POSTGRES_USER}:${POSTGRES_PASSWORD}@database/${POSTGRES_DB} - - DATABASE_TYPE=${DATABASE_TYPE} + - DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@database/${DATABASE_NAME} + - DATABASE_TYPE=postgres - HYPERKITTY_API_KEY=${HYPERKITTY_API_KEY} - SECRET_KEY=${DJANGO_SECRET_KEY} - TZ=${TZ} @@ -52,9 +52,9 @@ services: database: environment: - - POSTGRES_DB=${POSTGRES_DB} - - POSTGRES_USER=${POSTGRES_USER} - - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} + - POSTGRES_DB=${DATABASE_NAME} + - POSTGRES_USER=${DATABASE_USER} + - POSTGRES_PASSWORD=${DATABASE_PASSWORD} image: postgres:11-alpine volumes: - /opt/mailman/database:/var/lib/postgresql/data From f5e08c2a90e1559d04ac3f99466b7211e514aa82 Mon Sep 17 00:00:00 2001 From: Jakob Scheumann Date: Mon, 13 Nov 2023 14:43:11 +0100 Subject: [PATCH 4/5] Keep env vars and secrets out of git --- .env => .env.example | 0 .gitignore | 1 + 2 files changed, 1 insertion(+) rename .env => .env.example (100%) diff --git a/.env b/.env.example similarity index 100% rename from .env rename to .env.example diff --git a/.gitignore b/.gitignore index feb8f08d..8eb0a3ab 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.env */.sass-cache/* *.log *.log From a0bbf3650d435863b9449055e6d63e218ba465ea Mon Sep 17 00:00:00 2001 From: Jakob Scheumann Date: Mon, 13 Nov 2023 14:46:41 +0100 Subject: [PATCH 5/5] Update README with .env.example templating info --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b1a851c5..c3d947ad 100644 --- a/README.md +++ b/README.md @@ -121,8 +121,9 @@ For other systems, you can read the official Docker documentation to install ## Configuration -Most of the common configuration is defined in `.env`. Further custom -environment variables should be set via a newly created docker-compose.override.yaml. +Most of the common configuration is defined in `.env`. Please copy the content of `.env.example` +into a fresh `.env` file (i.e. by running `cp -a .env.example .env`) and customise it there. +Further custom environment variables should be set via a newly created docker-compose.override.yaml. Additionally, there is need for some extra configuration that interacts directly with the application. There are two configuration files on