diff --git a/docs/source/admin_guide.rst b/docs/source/admin_guide.rst index 3218a4a..e14f728 100644 --- a/docs/source/admin_guide.rst +++ b/docs/source/admin_guide.rst @@ -9,10 +9,14 @@ Test with Docker .. _Docker: https://www.docker.com/community-edition -A local test instance of Oncall can be setup with Docker_ in two commands: +A local test instance of Oncall can be setup with Docker_ in a few commands: .. code-block:: bash + cd ./ops/packer + mkdir output + python gen_packer_cfg.py ./oncall.yaml | tail -n +2 > ./output/oncall.json + packer build -only=docker oncall.json docker run -d --name oncall-mysql -e MYSQL_ROOT_PASSWORD='1234' mysql docker run -d --link oncall-mysql:mysql -p 8080:8080 -e DOCKER_DB_BOOTSTRAP=1 quay.io/iris/oncall @@ -33,3 +37,52 @@ exists in the DB). You can navigate to the "Browse Teams" page and check out "Test Team", which shows a calendar page where you can create and modify events. See :ref:`user-guide` for more information on how to interact with the UI. + +Adding Users +```````````` + +Users may be imported from other systems such as LDAP and Slack. This process is +extensible by developing your own plugins. + +Let's use LDAP as an example. First we configure the user_sync process to use the +ldap_sync module, then we provide specific configuration for this module to +connect to LDAP. + +.. code-block:: yaml + + user_sync: + module: 'oncall.user_sync.ldap_sync' + + ldap_sync: + url: 'ldaps://ldapserver.org' + base: 'ou=accounts,dc=company,dc=org' + user: 'cn=oncall,ou=serviceaccount,dc=company,dc=org' + password: 'xxxx' + cert_path: '/etc/ldap_cert.pem' + query: '(uid=*)' + attrs: + username: 'uid' + full_name: 'cn' + mail: 'mail' + mobile: 'mobile' + image_url: 'https://image.example.com/api/%s/picture' + +User synchronization is a seperate process which needs to be started manually, +but will continue to run in a loop, updating users as necessary. + +To run this process, you simply point to the configuration file: + +.. code-block:: bash + + ./oncall-user-sync /home/oncall/config/config.yaml + +Now that your users are in Oncall, they can be accessed by Iris. Note that +this too is a manually triggered synchronization process, rather than just +a call to Oncall. But while Iris will import these as Targets, it will still +call Oncall to determine who is the current Oncall-primary and secondary, when +creating a new message to be sent. + +.. _Oncall-admin: https://github.com/dwang159/oncall-admin + +.. NOTE:: + It is also possible to use Oncall-admin_ to do manual user administration