Commit da14a8b5 authored by Alex Pyrgiotis's avatar Alex Pyrgiotis

docs: Update install/admin guides

Update the install/admin guides to reflect the addition of the
`ADMIN_BASE_URL` setting. Also, add an Admin section in the CentOS
install guide.
parent d8ee980d
...@@ -1662,44 +1662,52 @@ from the Astakos/Cyclades stats. ...@@ -1662,44 +1662,52 @@ from the Astakos/Cyclades stats.
Access and permissions Access and permissions
---------------------- ----------------------
The Admin dashboard can be accessed by default from the `/admin/` URL. Since The Admin dashboard can be accessed by default from the ``ADMIN_BASE_URL`` URL.
there is no login form, the user must login on Astakos first and then visit the Since there is no login form, the user must login on Astakos first and then
above URL. Access will be granted only to users that belong to a predefined visit the above URL. Access will be granted only to users that belong to a
list of Astakos groups. By default, there are three group categories that predefined list of Astakos groups. By default, there are three group categories
are mapped 1-to-1 to Astakos groups: that are mapped 1-to-1 to Astakos groups:
* ADMIN_READONLY_GROUP: 'admin-readonly' * ADMIN_READONLY_GROUP: 'admin-readonly'
* ADMIN_HELPDESK_GROUP: 'helpdesk' * ADMIN_HELPDESK_GROUP: 'helpdesk'
* ADMIN_GROUP: 'admin' * ADMIN_GROUP: 'admin'
The group categories can be changed using the `ADMIN_PERMITTED_GROUPS` setting. The group categories can be changed using the ``ADMIN_PERMITTED_GROUPS``
In order to change the Astakos group that a category corresponds to, the setting. In order to change the Astakos group that a category corresponds to,
administrator can specify the group that he/she wants in the the administrator can specify the group that he/she wants in the
`ADMIN_READONLY_GROUP`, `ADMIN_HELPDESK_GROUP` or `ADMIN_GROUP` settings. ``ADMIN_READONLY_GROUP``, ``ADMIN_HELPDESK_GROUP`` or ``ADMIN_GROUP`` settings.
Note that while any user that belongs to the `ADMIN_PERMITTED_GROUPS` has the Note that while any user that belongs to the ``ADMIN_PERMITTED_GROUPS`` has the
same access to the administrator dashboard, the actions that are allowed for a same access to the administrator dashboard, the actions that are allowed for a
group may differ. That's because Admin implements a Role-Based Access Control group may differ. That's because Admin implements a Role-Based Access Control
(RBAC) policy, which can be changed from the `ADMIN_RBAC` setting. By default, (RBAC) policy, which can be changed from the ``ADMIN_RBAC`` setting. By
users in the `ADMIN_READONLY_GROUP` cannot perform any actions. On the other default, users in the ``ADMIN_READONLY_GROUP`` cannot perform any actions. On
hand, users in the `ADMIN_GROUP` can perform all actions. In the middle of the the other hand, users in the ``ADMIN_GROUP`` can perform all actions. In the
spectrum is the `ADMIN_HELPDESK_GROUP`, which by default performs a small middle of the spectrum is the ``ADMIN_HELPDESK_GROUP``, which by default
subset of reversible actions. performs a small subset of reversible actions.
Seting up Admin Seting up Admin
--------------- ---------------
Admin is bundled by default with a list of sane settings. The most important Admin is bundled by default with a list of sane settings. The most important
one, `ADMIN_ENABLED`, is set to `True` and defines whether Admin will be used one, ``ADMIN_ENABLED``, is set to ``True`` and defines whether Admin will be used
or not. Therefore, the administrator only needs to create the necessary Astakos or not.
groups and add trusted users in them. The following example will create an
admin group and will add a user in it: The administrator simply has to create the necessary Astakos groups and
add trusted users in them. The following example will create an admin group and
will add a user in it:
.. code-block:: console .. code-block:: console
snf-manage group-add admin snf-manage group-add admin
snf-manage user-modify --add-group=admin <user_id> snf-manage user-modify --add-group=admin <user_id>
Finally, the administrator must edit the ``20-snf-admin-app-general.conf``
settings file, uncomment the ``ADMIN_BASE_URL`` setting and assign the
appropriate URL to it. In most cases, this URL will be the top-level URL of the
Admin node, with the optional addition of an extra path (e.g. ``/admin``) in
order to distinguish it from different components.
That's all that is required for a single-node setup. For a multi-node setup, That's all that is required for a single-node setup. For a multi-node setup,
please consult the following section: please consult the following section:
...@@ -1712,22 +1720,18 @@ settings of their nodes. As a result, when installing Admin in a node, the ...@@ -1712,22 +1720,18 @@ settings of their nodes. As a result, when installing Admin in a node, the
Astakos and Cyclades packages will also be installed. Astakos and Cyclades packages will also be installed.
In order to disable the Astakos/Cyclades API in the Admin node, the In order to disable the Astakos/Cyclades API in the Admin node, the
administrator can add the following line in `99-local.conf`: administrator can add the following line in ``99-locals.conf`` (you can create
it if doesn't exist):
.. code-block:: console
ROOT_URLCONF="synnefo_admin.admin.urls"
As a result, Admin will be accessible by this URL: `<Admin_Node_URL>/`. If the
administrator wishes to use the default URL (`<Admin_Node_URL>/admin/`), then
the following line must be added instead.
.. code-block:: console .. code-block:: console
ROOT_URLCONF="synnefo_admin.urls" ROOT_URLCONF="synnefo_admin.urls"
Note that the above change does not interfere the with the ``ADMIN_BASE_URL``,
which will be used normally.
Furthermore, if Astakos and Cyclades have separate databases, then they must be Furthermore, if Astakos and Cyclades have separate databases, then they must be
defined in the `DATABASES` setting of `10-snf-webproject-database.conf`. An defined in the ``DATABASES`` setting of ``10-snf-webproject-database.conf``. An
example setup is the following: example setup is the following:
.. code-block:: console .. code-block:: console
...@@ -1754,16 +1758,16 @@ example setup is the following: ...@@ -1754,16 +1758,16 @@ example setup is the following:
DATABASE_ROUTERS = ['snf_django.utils.routers.SynnefoRouter'] DATABASE_ROUTERS = ['snf_django.utils.routers.SynnefoRouter']
You may notice that there are three databases instead of two. That's because You may notice that there are three databases instead of two. That's because
Django requires that every `DATABASES` setting has a *default* database. In our Django requires that every ``DATABASES`` setting has a *default* database. In
case, we suggest that you use as default the Cyclades database. Finally, you our case, we suggest that you use as default the Cyclades database. Finally,
must not forget to add the `DATABASE_ROUTERS` setting in the above example that you must not forget to add the ``DATABASE_ROUTERS`` setting in the above
must always be used in multi-db setups. example that must always be used in multi-db setups.
Disabling Admin Disabling Admin
--------------- ---------------
The easiest way to disable the Admin Dashboard is to set the `ADMIN_ENABLED` The easiest way to disable the Admin Dashboard is to set the ``ADMIN_ENABLED``
setting to `False`. setting to ``False``.
List of all Synnefo components List of all Synnefo components
......
...@@ -2512,5 +2512,51 @@ to state 'Running' and you will be able to use it. Click 'Console' to connect ...@@ -2512,5 +2512,51 @@ to state 'Running' and you will be able to use it. Click 'Console' to connect
through VNC out of band, or click on the machine's icon to connect directly via through VNC out of band, or click on the machine's icon to connect directly via
SSH or RDP (for windows machines). SSH or RDP (for windows machines).
Installation of Admin on node1
==============================
This section describes the installation of Admin. Admin is a Synnefo component
that provides to trusted users the ability to manage and view various different
Synnefo entities such as users, VMs, projects etc.
We will install Admin on node1. To do so, we install the corresponding
package by running on node1 the following command:
.. code-block:: console
# apt-get install snf-admin-app
Once the package is installed, we must configure the ``ADMIN_BASE_URL``
setting. This setting is located in the ``20-snf-admin-app-general.conf``
settings file. Uncomment it and assign the following URL to it:
``https://node1.example.com/admin``
Now, we can proceed with testing Admin.
Testing of Admin
================
In order to test the Admin Dashboard, we need a user that belongs to the
`admin` group. We will use the user that was created in `Testing of Astakos`_
section:
.. code-block:: console
root@node1:~ # snf-manage group-add admin
root@node1:~ # snf-manage user-modify 1 --add-group=admin
Then, you need to login to the Astakos node by visiting the following URL:
``https://node1.example.com/astakos``
Once you login successfully, you can access the Admin Dashboard from this URL:
``https://node1.example.com/admin``
This should redirect you to the **Users** table, where there should be an entry
with this user.
Congratulations. You have successfully installed the whole Synnefo stack and Congratulations. You have successfully installed the whole Synnefo stack and
connected all components. connected all components.
...@@ -2552,9 +2552,6 @@ to state 'Running' and you will be able to use it. Click 'Console' to connect ...@@ -2552,9 +2552,6 @@ to state 'Running' and you will be able to use it. Click 'Console' to connect
through VNC out of band, or click on the machine's icon to connect directly via through VNC out of band, or click on the machine's icon to connect directly via
SSH or RDP (for windows machines). SSH or RDP (for windows machines).
Congratulations. You have successfully installed the whole Synnefo stack and
connected all components.
Installation of Admin on node1 Installation of Admin on node1
============================== ==============================
...@@ -2570,7 +2567,13 @@ package by running on node1 the following command: ...@@ -2570,7 +2567,13 @@ package by running on node1 the following command:
# apt-get install snf-admin-app # apt-get install snf-admin-app
Once the package is installed, we are done. We can proceed with testing Admin. Once the package is installed, we must configure the ``ADMIN_BASE_URL``
setting. This setting is located in the ``20-snf-admin-app-general.conf``
settings file. Uncomment it and assign the following URL to it:
``https://node1.example.com/admin``
Now, we can proceed with testing Admin.
Testing of Admin Testing of Admin
================ ================
...@@ -2586,11 +2589,14 @@ section: ...@@ -2586,11 +2589,14 @@ section:
Then, you need to login to the Astakos node by visiting the following URL: Then, you need to login to the Astakos node by visiting the following URL:
``http://node1.example.com/astakos`` ``https://node1.example.com/astakos``
Once you login successfully, you can access the Admin Dashboard from this URL: Once you login successfully, you can access the Admin Dashboard from this URL:
``http://node1.example.com/admin/`` ``https://node1.example.com/admin``
This should redirect you to the **Users** table, where there should be an entry This should redirect you to the **Users** table, where there should be an entry
with this user. with this user.
Congratulations. You have successfully installed the whole Synnefo stack and
connected all components.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment