Hopefully improved documentation around initial admin account creation.

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
 

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
 -----------------
 

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
 -----------