Merge pull request #127 from FREVA-CLINT/more-info

More info

assets/share/freva/deployment/config/unprivileged-user.toml

@@ -32,7 +32,6 @@ private_keyfile = ""
 chain_keyfile = ""
 
 
-
 [web]
 # Set the host names where all services web UI will be deployed
 hosts = "localhost"
@@ -68,24 +67,36 @@ hosts = "localhost"
 ##
 [db.config]
 
-## Config variables for the database service
+## The database is running in a docker container. You can change the port
+## where the port that is exposed to the external network. Every DB connection
+## from outside going inside the container is made via that port.
 port = 3307
+
+## Set the user name of the mariadb user
 user = "freva"
+
+## Set the database name of the mariadb database
 db = "frevadb"
 
-##If you need a different user name you can set it here (defaults to current user):
+## If your user name where you run the deployment software and the user name
+## that installe the services differ you can instruct ansible to use the
+## the specified user name to establish ssh connections to the target server.
+## If left blank the current user name will be taken.
 ansible_user = "freva"
 
 ## You can set the db_host separately, if none is given (default)
 ## the one from the hosts names above are taken
-
-db_host = "freva"
+db_host = ""
 
 ## Set the become (sudo) user name to change to for installing the services
-## leave blank to utilise a non privileged user based installation
-ansible_become_user = ""
-
-## Ansible needs a python3 interpreter, which can be set for custom python3 instances
+## leave blank to utilise a non privileged user based installation.
+## Non privileged installation means, the system will be installed in the
+## userspace of the user that logs on to the system.
+ansible_become_user = "root"
+
+## Ansible needs a python3 interpreter on the target server. This interpreter
+## which can be set for custom python3 instances. By default ansible will try
+## to use the default python interpreter path /user/bin/python
 ansible_python_interpreter = ""
 
 ##Indicate whether or not to empty any pre-existing folders/docker volumes.
@@ -104,21 +115,30 @@ data_path = "~/freva-local/services"
 db_playbook = ""
 
 [freva_rest.config]
-# Set the memory for the solr server (solr is the search engine in the background)
+## How much memory do you want to give to the search enging
+## (solr is the search engine in the background)
 solr_mem = "1g"
 
-# Set the port the freva-rest should be running on
+## Set the port the freva_rest service should be running on
 freva_rest_port = 7778
 
 ## Set the become (sudo) user name to change to for installing the services
-## leave blank to utilise a non privileged user based installation
+## leave blank to utilise a non privileged user based installation.
+## Non privileged installation means, the system will be installed in the
+## userspace of the user that logs on to the system.
 ansible_become_user = ""
 
 ## Ansible needs a python3 interpreter, which can be set for custom python3 instances
 
+## Ansible needs a python3 interpreter on the target server. This interpreter
+## which can be set for custom python3 instances. By default ansible will try
+## to use the default python interpreter path /user/bin/python
 ansible_python_interpreter = ""
 
-## If you need a different user name you can set it here (default to current user):
+## If your user name where you run the deployment software and the user name
+## that installe the services differ you can instruct ansible to use the
+## the specified user name to establish ssh connections to the target server.
+## If left blank the current user name will be taken.
 ansible_user = "freva"
 
 ##Indicate whether or not to empty any pre-existing folders/docker volumes.
@@ -143,29 +163,32 @@ freva_rest_playbook = ""
 ## If blank, the user that runs the deployment is chosen
 admins = ""
 
-## The path where the core should be installed
+## The path where the core library should be installed to
+## Conda is used for installing the core library. Hence setting
 install_dir="~/freva-env"
 
+
 ## The directory where the project configuration files will be stored.
 ## This can be useful if you want to set up multiple freva instances with
-## the same software stack. leave blank to use the same directory as
-## `install_dir`
+## the same software stack (anaconda environment). Leave blank to use the
+## same directory as `install_dir`
 root_dir = ""
 
-## If you which not to install a core instance but only configure one set the
-## install variable to false. This can be useful if you have a central instance
+## If you wish not to install a new freva conda environment but only
+## (re) configure an already installed system you can set the ``install``
+## variable to false. This can be useful if you have a central instance
 ## of freva deployed and want to setup a project specific configuration that
-## uses this central instance
+## uses this central instance.
 install = true
 
 ## The directory where the user specific output will be stored,
-## if left blank then it defaults to `root_dir/work`
+## if left blank then it defaults to `<root_dir>/work`
 base_dir_location = ""
 
 ## Set the directory holding the user content, like plots, for the web user
 ## interface. Note: after plugin application, display content of the plugin
 ## output will be copied to this directory. The default location of this
-## directory (if left value left blank) is ${base_dir_location}/share/preview
+## directory (if left value left blank) is <base_dir_location>/share/preview
 preview_path = ""
 
 ## Set the workload manager system, currently available are:
@@ -174,7 +197,7 @@ scheduler_system = "local"
 
 ## Set the path to the directory that contains the stdout of the plugins,
 ## this directory must be accessible to the web UI. The workload manager
-## will write the stdout into this directory. Defaults to ${base_dir_location}/share
+## will write the stdout into this directory. Defaults to <base_dir_location>/share
 scheduler_output_dir = ""
 
 # Set the target architecture of the system where the backend will be installed
@@ -187,10 +210,15 @@ arch = "Linux-x86_64"
 ## different user. Leave blank for if not needed.
 ansible_become_user = ""
 
-##If you need a different user name you can set it here (defaults to current user):
-ansible_user = "freva"
+## If your user name where you run the deployment software and the user name
+## that installe the services differ you can instruct ansible to use the
+## the specified user name to establish ssh connections to the target server.
+## If left blank the current user name will be taken.
+ansible_user = ""
 
-## Ansible needs a python3 interpreter, which can be set for custom python3 instances
+## Ansible needs a python3 interpreter on the target server. This interpreter
+## which can be set for custom python3 instances. By default ansible will try
+## to use the default python interpreter path /user/bin/python
 ansible_python_interpreter = ""
 
 ## The core deployment needs git, if git is not in the default PATH variable
@@ -215,22 +243,29 @@ wipe = false
 core_playbook = ""
 
 [web.config]
-## List of user that can alter the configuration of freva web
+## Set the url of the web user interface.
 project_website = "www.freva.dkrz.de"
 
-## Ansible needs a python3 interpreter, which can be set for custom python3 instances
+## Ansible needs a python3 interpreter on the target server. This interpreter
+## which can be set for custom python3 instances. By default ansible will try
+## to use the default python interpreter path /user/bin/python
 ansible_python_interpreter = ""
 
-##If you need a different user name you can set it here (defaults to current user):
-ansible_user = "freva"
+## If your user name where you run the deployment software and the user name
+## that installe the services differ you can instruct ansible to use the
+## the specified user name to establish ssh connections to the target server.
+## If left blank the current user name will be taken.
+ansible_user = ""
 
 ## Set the path where the permanent web data should be stored. By default
 ## this is set to /opt/freva
 data_path = "~/freva-local/services"
 
-##Set html colors
+## Set main html colors scheme
 main_color = "Tomato"
+## Set the html colors for the borders
 border_color = "#6c2e1f"
+## Set the html hover colors
 hover_color = "#d0513a"
 
 ## The about us text is a small blurb about freva within the project
@@ -247,7 +282,7 @@ contacts = ""
 ## Set the smpt email server that will be used to send emails to contacts via the web UI
 email_host = ""
 
-## Now set postal address
+## Set postal address, this will appear in the footer of the webside.
 imprint = "Project name, German Climate Computing Centre (DKRZ), Bundesstr. 45a, 20146 Hamburg, Germany."
 
 ## Here you can set a lengthy project description.
@@ -258,18 +293,22 @@ homepage_text = "Bal bla bla."
 ## Set a one line blurb of the project
 homepage_heading = "Short description of the project."
 
-## Set the name of the project/institution
+## Set the name of the project/institution, like FUB, DWD, DKZ etc.
 institution_name = "Freva"
 
-## Set the slurm scheduler host
+## Set the workload manager scheduler host. The web app will log into this
+## machine via ssh to submit plugin jobs.
 scheduler_host = ["localhost"]
 
 ## Settings for ldap
 
-## Ldap server name(s)
+## Ldap server name
 auth_ldap_server_uri = ""
 
-## Set the group that will be allowed to log on
+## Set the user ldap group that will be allowed to log on
+## You can either instruct the web UI to allow access to only that group
+## or set the <allowed_group> to '*' to allow all users regardless of the
+## ldap group to log on.
 allowed_group = "test_group"
 
 ## Set the ldap search user base
@@ -299,10 +338,11 @@ ldap_group_class = "groupOfNames"
 ## Set the ldap group type, available values are are [posix, nested]
 ldap_group_type = "nested"
 
-## Set the ldap tools class for users
+## Set the ldap tools class for users, this class needs to implemented
+## in the web app backend.
 ldap_model = "MiklipUserInformation"
 
-## set the passwd for the ldap user
+## set the passwd for the ldap admin user
 ldap_user_pw = ""
 
 #######
@@ -331,11 +371,7 @@ menu_entries = [["Data-Browser", "solr:data_browser","browser_menu"],
 web_playbook = ""
 
 ## Set the become (sudo) user name to change to for installing the services
-## leave blank to utilise a non privileged user based installation
+## leave blank to utilise a non privileged user based installation.
+## Non privileged installation means, the system will be installed in the
+## userspace of the user that logs on to the system.
 ansible_become_user = ""
-
-# Deploy a http reverse proxy. Turn off the deployment (set to false) of an
-# reverse proxy doesn't the user that deploys the web doesn't have access to
-# port 80 and 443 in this case you will have to deploy the reverse proxy
-# yourself.
-deploy_web_server = false

assets/share/freva/deployment/db_service/reset_root_pw.sh

@@ -7,6 +7,9 @@ echo "USE mysql; FLUSH PRIVILEGES; ALTER USER "\
      "'root'@'localhost' IDENTIFIED BY '$MYSQL_ROOT_PASSWORD'; "\
      "ALTER USER 'root'@'%' IDENTIFIED BY '$MYSQL_ROOT_PASSWORD'; "\
      "ALTER USER '$MYSQL_USER'@'%' IDENTIFIED BY '$MYSQL_PASSWORD'; "\
+     "FLUSH PRIVILEGES;"\
+     "GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' WITH GRANT OPTION;"\
+     "GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;"\
      "FLUSH PRIVILEGES;" > /tmp/my.sql
 mariadb -u root < /tmp/my.sql
 rm /tmp/my.sql

docs/deployment/TuiHowto.md

@@ -18,6 +18,7 @@ After opening the tui with the `deploy-freva` command you'll see a small
 navigation panel on the bottom. Navigation is done by shortcuts and similar
 to those used in the *nano* text editor. All shortcuts start with
 a `^` which indicates `CTRL+`, main shortcuts are:
+> `CTRL+f`: Further information on each configuration item.
 - `CTRL+x`: Enter main menu.
 - `CRTL+v`: Edit/Add environment variables.
 - `CTRL+o`: Load a saved configuration.
@@ -97,6 +98,9 @@ essential setup steps:
 17. Set the path to the `git` executable if not in default path
    such as `/usr/bin/git`.
 
+
+> ``📝`` Press CTRL+f for *f*urther information on each configuration item.
+
 ### Notes on the core setup
 It is good practice to use only one anaconda environment for multiple Freva
 instances. Each Freva instance only differs in its configuration
@@ -162,6 +166,8 @@ essential setup steps:
     to root. Leave blank if no special user is needed.
 30. Set the login user name for the remote machine.
 
+> ``📝`` Press CTRL+f for *f*urther information on each configuration item.
+
 ### Notes on the web ui setup
 Currently there are ties between the core running on the HPC machine and
 the web ui. These are:
@@ -198,7 +204,7 @@ vault service that gets deployed when setting up the database.
 
 
 
-## Databrowser server setup
+## Freva rest setup
 The third screen configures the setup databrowser server. At the top of
 the screen you'll see a tick box, which indicates whether or not this step is
 used for deployment. If this box is *un*ticked - tick/untick using the
@@ -222,7 +228,9 @@ following explains the essential setup steps:
    binary is not part of the `$PATH` variable.
 8. Set the login user name for the remote machine.
 
-### Notes on the databrowser setup
+> ``📝`` Press CTRL+f for *f*urther information on each configuration item.
+
+### Notes on the freva-rest setup
 Any existing data is *not* overridden if you deploy
 a new server and do not chose to delete any pre existing data. The
 data will be saved to `/opt/freva/<project_name>/databrowser_service/`
@@ -258,6 +266,8 @@ following explains the essential setup steps:
     binary is not part of the `$PATH` variable.
 10. Set the login user name for the remote machine.
 
+> ``📝`` Press CTRL+f for *f*urther information on each configuration item.
+
 ### Notes on the database setup
 This step also includes the deployment of a vault service where all information
 on the database connection are stored. The `evaluation_system` core library

docs/whatsnew.rst

@@ -7,39 +7,46 @@ What's new
    :maxdepth: 0
    :titlesonly:
 
+v2406.0.0
+~~~~~~~~~
+* Add info panel (access via CTRL+f) for further information on config items.
+* Bug fix reset mariadb root password script.
+
+
+
 v2405.1.1
-~~~~~~~~
+~~~~~~~~~
 * Minor bug fixing.
 
 
 
 v2405.1.0
-~~~~~~~~
+~~~~~~~~~
 * Bumped version of freva core to 2406.0.0
 
 
 
 v2405.0.0
-~~~~~~~~
+~~~~~~~~~
 * Bumped version of freva_rest to 2403.0.3
 
 
 
 v2404.0.0
-~~~~~~~~
+~~~~~~~~~
 * Bumped version of django_evaluation to 2405.0.0
 
 
 
 
 v2403.2.0
-~~~~~~~~
+~~~~~~~~~
 * Bumped version of databrowserAPI to 2403.0.3
 
 
 
 v2403.1.0
-~~~~~~~~
+~~~~~~~~~
 * Bumped version of databrowserAPI to 2403.0.2
 
 

src/freva_deployment/__init__.py

@@ -1,7 +1,7 @@
 import argparse
 from urllib.request import urlretrieve
 
-__version__ = "2405.1.1"
+__version__ = "2406.0.0"
 
 FREVA_PYTHON_VERSION = "3.11"
 AVAILABLE_PYTHON_VERSIONS = ["3.8", "3.9", "3.10", "3.11", "3.12"]