From 83d9a81f0fea5aa20d6ef368cd4f408d1e9826ec Mon Sep 17 00:00:00 2001 From: Erriez Date: Wed, 22 Dec 2021 15:00:39 +0100 Subject: [PATCH 1/3] Fix documentation INITIAL_ADMIN_* variables --- docs/compose/setup.rst | 3 +-- docs/configuration.rst | 27 +++++++++++++++++---------- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/compose/setup.rst b/docs/compose/setup.rst index 1f3065c6..5b0de384 100644 --- a/docs/compose/setup.rst +++ b/docs/compose/setup.rst @@ -99,8 +99,7 @@ You may now start Mailu. Move the to the Mailu directory and run: Finally, you need an admin user account. You can have the system create it automatically: -use the environment variables ``INITIAL_ACCOUNT*`` as described in :ref:`admin_account` -You should set ``INITIAL_ADMIN_MODE`` also to either ``update`` or ``ifmissing``. Leaving it with the default value could cause errors when restarting the system. +use the environment variables ``INITIAL_ADMIN_*`` as described in :ref:`admin_account` Else, if you don't go with the automatic way, you need to manually create the admin account now: diff --git a/docs/configuration.rst b/docs/configuration.rst index d6bfb505..cfc12492 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -159,18 +159,25 @@ To create it manually, follow the specific deployment method documentation. To have the account created automatically, you just need to define a few environment variables: +- ``INITIAL_ADMIN_ACCOUNT``: the admin username: The first part of the e-mail address before the @. +- ``INITIAL_ADMIN_DOMAIN``: the domain appendix: Most probably identical to the ``DOMAIN`` variable. +- ``INITIAL_ADMIN_PW``: the admin password. +- ``INITIAL_ADMIN_MODE``: one of the options below how the code should behave when it will try to create the admin user: + + - ``create``: (default) Will try to create user and will raise an exception if present. + - ``ifmissing``: if user exists, nothing happens, else it will be created. + - ``update``: user is created or, if it exists, its password gets updated. + +You should set ``INITIAL_ADMIN_MODE`` also to either ``update`` or ``ifmissing``. Leaving it with the default value could cause errors when restarting the system. + +An example: + .. code-block:: bash - INITIAL_ADMIN_ACCOUNT = ``root`` The first part of the e-mail address (ROOT@example.com) - INITIAL_ADMIN_DOMAIN = ``example.com`` the domain appendix. Most probably identical to the DOMAIN variable - INITIAL_ADMIN_PW = ``password`` the chosen password for the user - -Also, environment variable ``INITIAL_ADMIN_MODE`` defines how the code should behave when it will -try to create the admin user: - -- ``create`` (default) Will try to create user and will raise an exception if present -- ``ifmissing``: if user exists, nothing happens, else it will be created -- ``update``: user is created or, if it exists, its password gets updated + INITIAL_ADMIN_ACCOUNT=me + INITIAL_ADMIN_DOMAIN=example.net + INITIAL_ADMIN_PW=password + INITIAL_ADMIN_MODE=ifmissing Depending on your particular deployment you most probably will want to change the default. From 4c52cf1d6ada37444baea47c8ba7488ecfae84f1 Mon Sep 17 00:00:00 2001 From: Erriez Date: Wed, 22 Dec 2021 18:18:15 +0100 Subject: [PATCH 2/3] Rewording INITIAL_ADMIN_MODE documentation --- docs/configuration.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index cfc12492..84d81011 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -162,13 +162,13 @@ To have the account created automatically, you just need to define a few environ - ``INITIAL_ADMIN_ACCOUNT``: the admin username: The first part of the e-mail address before the @. - ``INITIAL_ADMIN_DOMAIN``: the domain appendix: Most probably identical to the ``DOMAIN`` variable. - ``INITIAL_ADMIN_PW``: the admin password. -- ``INITIAL_ADMIN_MODE``: one of the options below how the code should behave when it will try to create the admin user: +- ``INITIAL_ADMIN_MODE``: use one of the options below for configuring how the admin account must be created: - - ``create``: (default) Will try to create user and will raise an exception if present. - - ``ifmissing``: if user exists, nothing happens, else it will be created. - - ``update``: user is created or, if it exists, its password gets updated. + - ``create``: (default) creates a new admin account and raises an exception when already exists. + - ``ifmissing``: creates a new admin account when the admin account does not exist. + - ``update``: creates a new admin account when it does not exist, or update the password of an existing admin account. -You should set ``INITIAL_ADMIN_MODE`` also to either ``update`` or ``ifmissing``. Leaving it with the default value could cause errors when restarting the system. +Note: It is recommended to set ``INITIAL_ADMIN_MODE`` to either ``update`` or ``ifmissing``. Leaving it with the default value will cause an error when the system is restarted. An example: From 10756cef7be73c1a20c6c835b7d2fe5bb7529ef4 Mon Sep 17 00:00:00 2001 From: Erriez Date: Wed, 22 Dec 2021 19:38:46 +0100 Subject: [PATCH 3/3] Fix typo configuration.rst --- docs/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index 84d81011..27ca8ed8 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -164,7 +164,7 @@ To have the account created automatically, you just need to define a few environ - ``INITIAL_ADMIN_PW``: the admin password. - ``INITIAL_ADMIN_MODE``: use one of the options below for configuring how the admin account must be created: - - ``create``: (default) creates a new admin account and raises an exception when already exists. + - ``create``: (default) creates a new admin account and raises an exception when it already exists. - ``ifmissing``: creates a new admin account when the admin account does not exist. - ``update``: creates a new admin account when it does not exist, or update the password of an existing admin account.