From 078082fac9211f867a99c2f8429f87388b90fd0f Mon Sep 17 00:00:00 2001 From: cristi Date: Tue, 21 May 2019 21:06:25 +0300 Subject: [PATCH] Hopefully improved documentation around initial admin account creation. --- docs/compose/setup.rst | 8 +++++++- docs/configuration.rst | 25 +++++++++++++++++++++++++ docs/kubernetes/mailu/index.rst | 31 +++++++++++-------------------- 3 files changed, 43 insertions(+), 21 deletions(-) diff --git a/docs/compose/setup.rst b/docs/compose/setup.rst index c1a620e6..2352f16e 100644 --- a/docs/compose/setup.rst +++ b/docs/compose/setup.rst @@ -96,7 +96,13 @@ You may now start Mailu. Move the to the Mailu directory and run: docker-compose up -d -Finally, you must create the initial admin user account: +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. + +Else, if you don't go with the automatic way, you need to manually create the admin account now: .. code-block:: bash diff --git a/docs/configuration.rst b/docs/configuration.rst index e7dfa2af..4e38f109 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -91,6 +91,31 @@ Both ``SITENAME`` and ``WEBSITE`` are customization options for the panel menu in the admin interface, while ``SITENAME`` is a customization option for every Web interface. +.. _admin_account: + +Admin account - automatic creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +For administrative tasks, an admin user account will be needed. You can create it manually, +after deploying the system, or automatically. +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: + +.. 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 + +Depending on your particular deployment you most probably will want to change the default. + Advanced settings ----------------- diff --git a/docs/kubernetes/mailu/index.rst b/docs/kubernetes/mailu/index.rst index 13943606..ab5f3ca4 100644 --- a/docs/kubernetes/mailu/index.rst +++ b/docs/kubernetes/mailu/index.rst @@ -117,7 +117,17 @@ Create the first admin account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When the cluster is online you need to create you master user to access https://mail.example.com/admin -Enter the main ``admin`` pod to create the root account: + +You can create it now manually, or have the system create it automatically. + +If you want the system to create the admin user account automatically, see :ref:`admin_account` +about the environment variables needed (``INITIAL_ADMIN_*``). +Also, important, taking into consideration that a pod in Kubernetes can be stopped/rescheduled at +any time, you should set ``INITIAL_ADMIN_MODE`` to either ``update`` or ``ifmissing`` - depending on what you +want to happen to its password. + + +To create the admin user account manually, enter the main ``admin`` pod: .. code-block:: bash @@ -139,25 +149,6 @@ And in the pod run the following command. The command uses following entries: Now you should be able to login on the mail account: https://mail.example.com/admin -Create the first admin account - automatically -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to have your user created automatically, you need to edit the Deployment descriptor and add -a few environment variables: - -.. 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 -- INITIAL_ADMIN_PW = ``password`` the chosen password for the user - - -Optionally, you can add the environment ``INITIAL_ADMIN_MODE`` with the value ``update`` if you want to -code to *always* update the password whenever container is started. Which could mean anytime, -so you probably do not want this :-) - -Now you should be able to login on the mail account: https://mail.example.com/admin - Adaptations -----------