Skip to content

GitLab

Commit da14a8b5 authored by Alex Pyrgiotis's avatar Alex Pyrgiotis
Browse files

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
Hide whitespace changes
Inline Side-by-side
docs/admin-guide.rst
View file @ da14a8b5
......@@ -1662,44 +1662,52 @@ from the Astakos/Cyclades stats.
Access and permissions
----------------------
The Admin dashboard can be accessed by default from the `/admin/` URL. Since
there is no login form, the user must login on Astakos first and then visit the
above URL. Access will be granted only to users that belong to a predefined
list of Astakos groups. By default, there are three group categories that
are mapped 1-to-1 to Astakos groups:
The Admin dashboard can be accessed by default from the ``ADMIN_BASE_URL`` URL.
Since there is no login form, the user must login on Astakos first and then
visit the above URL. Access will be granted only to users that belong to a
predefined list of Astakos groups. By default, there are three group categories
that are mapped 1-to-1 to Astakos groups:
* ADMIN_READONLY_GROUP: 'admin-readonly'
* ADMIN_HELPDESK_GROUP: 'helpdesk'
* ADMIN_GROUP: 'admin'
The group categories can be changed using the `ADMIN_PERMITTED_GROUPS` setting.
In order to change the Astakos group that a category corresponds to, the
administrator can specify the group that he/she wants in the
`ADMIN_READONLY_GROUP`, `ADMIN_HELPDESK_GROUP` or `ADMIN_GROUP` settings.
The group categories can be changed using the ``ADMIN_PERMITTED_GROUPS``
setting. In order to change the Astakos group that a category corresponds to,
the administrator can specify the group that he/she wants in the
``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
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,
users in the `ADMIN_READONLY_GROUP` cannot perform any actions. On the other
hand, users in the `ADMIN_GROUP` can perform all actions. In the middle of the
spectrum is the `ADMIN_HELPDESK_GROUP`, which by default performs a small
subset of reversible actions.
(RBAC) policy, which can be changed from the ``ADMIN_RBAC`` setting. By
default, users in the ``ADMIN_READONLY_GROUP`` cannot perform any actions. On
the other hand, users in the ``ADMIN_GROUP`` can perform all actions. In the
middle of the spectrum is the ``ADMIN_HELPDESK_GROUP``, which by default
performs a small subset of reversible actions.
Seting up Admin
---------------
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
or not. Therefore, the administrator only needs 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:
one, ``ADMIN_ENABLED``, is set to ``True`` and defines whether Admin will be used
or not.
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
snf-manage group-add admin
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,
please consult the following section:
......@@ -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.
In order to disable the Astakos/Cyclades API in the Admin node, the
administrator can add the following line in `99-local.conf`:
.. 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.
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.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
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:
.. code-block:: console
......@@ -1754,16 +1758,16 @@ example setup is the following:
DATABASE_ROUTERS = ['snf_django.utils.routers.SynnefoRouter']
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
case, we suggest that you use as default the Cyclades database. Finally, you
must not forget to add the `DATABASE_ROUTERS` setting in the above example that
must always be used in multi-db setups.
Django requires that every ``DATABASES`` setting has a *default* database. In
our case, we suggest that you use as default the Cyclades database. Finally,
you must not forget to add the ``DATABASE_ROUTERS`` setting in the above
example that must always be used in multi-db setups.
Disabling Admin
---------------
The easiest way to disable the Admin Dashboard is to set the `ADMIN_ENABLED`
setting to `False`.
The easiest way to disable the Admin Dashboard is to set the ``ADMIN_ENABLED``
setting to ``False``.
List of all Synnefo components
......
docs/install-guide-centos.rst
View file @ da14a8b5
......@@ -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
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
connected all components.
docs/install-guide-debian.rst
View file @ da14a8b5
......@@ -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
SSH or RDP (for windows machines).
Congratulations. You have successfully installed the whole Synnefo stack and
connected all components.
Installation of Admin on node1
==============================
......@@ -2570,7 +2567,13 @@ package by running on node1 the following command:
# 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
================
......@@ -2586,11 +2589,14 @@ section:
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:
``http://node1.example.com/admin/``
``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
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