hobo/README

Hobo
====

Administration portal to configure and deploy applications.


Installation
------------

Dependencies can be installed with pip,

 $ pip install -r requirements.txt

It's then required to get the database configured (./manage.py syncdb); by
default it will create a db.sqlite3 file.

Hobo can then be run like typical django applications (./manage.py runserver),
it will communicate to deployment agents using Celery and expects a running
RabbitMQ server running on localhost.

The agent in charge of deploying application can then be run on the application
servers, for example:

  celery --app=hobo.agent.worker worker --loglevel=info

The agent will use settings from the file declared in the HOBO_AGENT_SETTINGS_FILE
environment variable (examples in hobo/agent/worker/settings.py)


Configuration
-------------

Hobo server configuration take place in hobo/settings.py, which import local
settings from the file declared in the HOBO_SETTINGS_FILE environment variable.

Adapt BROKER_URL if RabbitMQ doesn't run on localhost.

Some applications may support deployments templates, they can be specified in
the configuration with the SERVICE_TEMPLATES variable.

  SERVICE_TEMPLATES = {
        'wcs': [('export-auquo-light.wcs', u'Au quotidien light'),
                ('export-auquo.wcs', u'Au quotidien'),
                ('export-demo.wcs', u'Démo au quotidien')
                ],
  }


Agent configuration
-------------------

Agent configuration take place in hobo/agent/worker/settings.py, which import
local settings from the file declared in the HOBO_AGENT_SETTINGS_FILE
environment variable.

It's possible to limit agents to particular applications, or particular
hostnames, using the AGENT_HOST_PATTERNS configuration variable.

The format is a dictionary with applications as keys and a list of hostnames as
value. The hostnames can be prefixed by an exclamation mark to exclude them.

  AGENT_HOST_PATTERNS = {
     'wcs': ['*.example.net', '!  *.dev.example.net'],
  }

Will limit wcs deployments to *.example.net hostnames, while excluding
*.dev.example.net.


Usage
-----

Go to environment settings, pick a service, fill its name and URL, and watch it
being deployed.  Successfully deployed services will add a link to their
administration pages on the homepage.


Environment
-----------

An Hobo agent is a class defined in `hobo.agent.worker.services` and derived from
`BaseService`. For each service in the environment dictionary sent by the hobo
portal, it's instantiated with the key `base_url`, `title` and `secret_key` of
the service. If the `base_url` matches the `AGENT_HOST_PATTERNS` locally
defined, the `execute()` method of the instance is called, passing it his
`base_url` and the full environment dictionary.

The environment dictionary contains services for this particular agent and all
other services defined on the portal. The `execute()` method should only create
a tenant for the service whose `base_url` was passed to constructor. All other
informations are only for defining links with other services. The schema of the
dictionary is::

    {
        'timestamp': <current_time_as_an_unix_timestamp>,
        'users': [
            {
                'username': 'john.doe',
                'first_name': 'John',
                'last_name': 'Doe',
                'email': 'john.doe@example.com',
                'password': '<django-compatible-hashed-password>',
            }
        ],
        'services': [
           {
                'service-id': 'authentic' / 'wcs' / 'passerelle',
                'service-label': 'Authentic' / 'w.c.s.' / 'Passerelle',
                'title': 'name of service,
                'secret_key': '..', # base secret for Django applications or other needs
                'base_url': 'base url of the service',
                'saml-sp-metadata-url': '...',
                'template_name': 'demo', # name of the template bundle to use
                'variables': {
                    'variable-1': 'value-of-variable-1'
                }
           }
        ],
        'fields': [
           {
               'disabled': boolean,
               'name': unique identifier (e.g. 'first_name'),
               'label': '..' (e.g. 'First Name'),
               'kind': 'title' / 'string' / 'email',
               'asked_on_registration': boolean,
               'user_editable': boolean,
               'required': boolean,
               'user_visible': boolean,
               'order': 1
           },
        ],
        'variables': {
            'variable-1': 'value-of-variable-1'
        }
    }

Agents
------

 - w.c.s.

w.c.s. instances will be deployed using "/usr/bin/wcs-manage" by default, this
command can be adapted in the WCS_MANAGE_COMMAND setting. It should be run
with the same rights as the wcs process (redefine the command to use sudo
if necessary).

Template keys defined in SERVICE_TEMPLATES have to map wcs skeleton sites
(created from settings / export) stored in /var/lib/wcs/skeletons (the exact
directory may vary according to the wcs configuration).

 - authentic2

authentic2 instances will be deployed using
"/usr/bin/authentic2-multitenant-manage" by default, this command can be
adapted in the AUTHENTIC_MANAGE_COMMAND setting. It should be run with the
same rights as the authentic2 process (redefine the command to use sudo if
necessary).


Tests
-----

For testing hobo server, do in a virtualenv:

   pip install pytest pytest-django

   DJANGO_SETTINGS_MODULE=hobo.settings HOBO_SETTINGS_FILE=tests/settings.py py.test tests

For testing multitenant framework, do in a virtualenv:

   pip install pytest pytest-django python-memcached mock .

   cd tests_multitenant ; PYTHONPATH=. DJANGO_SETTINGS_MODULE=settings py.test .


Code Style
----------

black is used to format the code, using thoses parameters:

    black --target-version py37 --skip-string-normalization --line-length 110

isort is used to format the imports, using those parameters:

    isort --profile black --line-length 110

pyupgrade is used to automatically upgrade syntax, using those parameters:

    pyupgrade --keep-percent-format --py37-plus

djhtml is used to automatically indent html files, using those parameters:

    djhtml --tabwidth 2

django-upgrade is used to automatically upgrade Django syntax, using those parameters:

    django-upgrade --target-version 3.2

There is .pre-commit-config.yaml to use pre-commit to automatically run these tools
before commits. (execute `pre-commit install` to install the git hook.)


License
-------

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU Affero General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU Affero General Public License for more
details.

You should have received a copy of the GNU Affero General Public License along
with this program.  If not, see <http://www.gnu.org/licenses/>.


Combo embeds some other pieces of code or art, with their own authors and
copyright notices:

Application images (hobo/static/css/*.svg) from the unDraw project:
 # https://undraw.co/
 #
 # All images, assets and vectors published on unDraw can be used for free. You
 # can use them for noncommercial and commercial purposes. You do not need to ask
 # permission from or provide credit to the creator or unDraw.
 #
 # More precisely, unDraw grants you an nonexclusive, worldwide copyright
 # license to download, copy, modify, distribute, perform, and use the assets
 # provided from unDraw for free, including for commercial purposes, without
 # permission from or attributing the creator or unDraw. This license does not
 # include the right to compile assets, vectors or images from unDraw to
 # replicate a similar or competing service, in any form or distribute the assets
 # in packs. This extends to automated and non-automated ways to link, embed,
 # scrape, search or download the assets included on the website without our
 # consent.