fghaas / taiga-ansible

Ansible roles to deploy taiga.
GNU Affero General Public License v3.0
18 stars 14 forks source link

taiga-ansible

Ansible roles and playbooks to deploy Taiga

This is a set of Ansible roles and example playbook that enable you to deploy the Taiga project management platform to your own servers. It is based on the recommendations given in the Taiga production environment setup guide.

Prerequisites

The production installation guide guide requires that all systems in your inventory run Ubuntu 20.04 Focal Fossa. This is the only platform where upstream expects everything to work. However, the roles in this repository are also being used on Ubuntu 18.04 Bionic Beaver and should work fine there as well. Other Ubuntu releases might work, but no guarantees.

Your deploy host must be running at least Ansible 2.5. Ubuntu 20.04 ships Ansible 2.9, so if you don't have Ansible installed yet, you can simply run:

sudo apt install ansible

Roles

Taiga hosts are to be sorted into three different roles:

It is perfectly acceptable to assign all three roles to the same host, if needed.

The other defined roles, taiga, taiga-node, and taiga-webserver, are auxiliary and should never be used directly. The taiga-back, taiga-front, and taiga-events roles inherit from these as needed.

Inventory

For a single-node installation where you install Taiga to the same node as Ansible, your inventory file could look like this:

[taiga-back]
localhost ansible_connection=local

[taiga-front:children]
taiga-back

[taiga-events:children]
taiga-back

For a multi-node installation where all nodes are distinct from the Ansible node, you could use an inventory like this:

[taiga-back]
taiga-backend.example.com

[taiga-front]
taiga.example.com

[taiga-events]
taiga-events.example.com

Playbooks

An example playbook is provided in taiga.yml. It understands the group names taiga_back, taiga_front, and taiga_events, and maps them to the corresponding role names.

Note that the example playbook also understands the group names taiga-back, taiga-front, and taiga-events, using hyphens instead of underscores. Running a playbook with hyphens in group names is deprecated and will raise a warning in Ansible version 2.8 and later. Starting with Ansible 2.10, hyphens in group names are no longer supported — so if you use the example playbook verbatim, or use your own playbook with hyphens in group names, please update your inventory to correct your group names.

Variables

Your inventory, vars file, or environment must always set the following variable:

You should set the following variables on the initial deployment run only. It is recommended that you set these from the command line with ansible-playbook -e:

Other variables that you might want to set include:

Several other variables can be overridden; for their defaults, please see variables.md.

Slack Support

To enable the Slack notification plugin, set taiga_enable_slack to true.

LDAP Authentication

To enable LDAP authentication support, set taiga_enable_ldap_login to true, and set taiga_ldap_* variables to match your LDAP server configuration. For details on supported variables, see variables.md.

SAML Authentication

To enable SAML authentication, set taiga_enable_saml_login to true, and include your SAML configuration in the taiga_saml_* dictionary variables. An example configuration for those variables is given below:

taiga_saml_sp_name_id_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" 
taiga_saml_idp_entity_id: "http://example.com/saml"
taiga_saml_idp_single_sign_on_url: "http://example.com/saml/sso"
taiga_saml_security:    # these are the defaults, to use them just omit this variable
  nameIdEncrypted:         false
  authnRequestsSigned:     false
  logoutRequestSigned:     false
  logoutResponseSigned:    false
  signMetadata:            false
  wantMessagesSigned:      false
  wantAssertionsSigned:    false
  wantNameId:              true
  wantAssertionsEncrypted: false
  wantNameIdEncrypted:     false
  wantAttributeStatement:  true
  requestedAuthnContext:   true
taiga_saml_contact_person:
  technical:
    givenName:     # name of your technical contact
    emailAddress:  # email address of your technical contact
  support:
    givenName:     # name of your support contact
    emailAddress:  # email address of your support contact
taiga_saml_mapping:  # map SAML users to Taiga users
  id: SAML_NAMEID
  attributes:
    email:     SAML_ATTRIBUTE_NAME_EMAIL
    username:  SAML_ATTRIBUTE_NAME_USERNAME
    full_name: SAML_ATTRIBUTE_NAME_FULLNAME
    bio:       SAML_ATTRIBUTE_NAME_BIO
    lang:      SAML_ATTRIBUTE_NAME_LANG
    timezone:  SAML_ATTRIBUTE_NAME_TIMEZONE

Backups

Taiga creates two sets of data that merit backup and that you might use to restore (or pre-populate) a Taiga installation: the PostgreSQL database, and the media directory in taiga-back, where user uploads like avatars, project logos, and file attachments go.

To create a backup, simply run the taiga.yml playbook. It will automatically place a timestamped backup tarball in your local backup directory.

$ ansible-playbook taiga.yml
[...]
PLAY RECAP ****************************************************************
xenial-taiga-aio           : ok=111  changed=14   unreachable=0    failed=0

$ ls backup
20171123-224624.tar.bz2

If you want to run just a backup, run only the tasks marked with the backup tag:

$ ansible-playbook taiga.yml -t backup
[...]
PLAY RECAP ****************************************************************
xenial-taiga-aio           : ok=33   changed=6    unreachable=0 failed=0

ls backup/
20171123-224624.tar.bz2  20171123-224837.tar.bz2

The backup tarball contains your PostgreSQL database dump (taiga.sql) and a copy of the media directory:

$ tar -vtjf backup/20171123-224837.tar.bz2
-rw-r--r-- taiga/taiga  254602 2017-11-23 23:48 taiga.sql
drwxr-xr-x taiga/taiga       0 2017-11-23 23:34 media/project/
drwxr-xr-x taiga/taiga       0 2017-11-23 23:34 media/user/
drwxr-xr-x taiga/taiga       0 2017-11-23 22:09 media/project/e/
drwxr-xr-x taiga/taiga       0 2017-11-23 22:09 media/project/e/4/
drwxr-xr-x taiga/taiga       0 2017-11-23 22:09 media/project/e/4/5/
drwxr-xr-x taiga/taiga       0 2017-11-23 22:09 media/project/e/4/5/6/
drwxr-xr-x taiga/taiga       0 2017-11-23 22:09 media/project/e/4/5/6/1c77291428251856b6ddc6985e6558bf06eb0f723258d032f9d44f8147c1/
[...]

Restore

To restore or pre-populate a Taiga installation, either

Then, invoke the playbook with the taiga_back_restore variable set to true:

$ ansible-playbook taiga.yml -e taiga_back_restore=true
[...]
PLAY RECAP ****************************************************************
xenial-taiga-aio           : ok=120  changed=21   unreachable=0    failed=0

The playbook run will fail if you set taiga_back_restore=true, but there is no restore file.

If you want to run just a restore, run only the tasks marked with the restore tag (but just as with the full playbook, don’t forget to also set the taiga_back_restore variable):

$ ansible-playbook taiga.yml -e taiga_back_restore=true -t restore
[...]
PLAY RECAP ****************************************************************
xenial-taiga-aio           : ok=35   changed=9    unreachable=0    failed=0

Upgrades

Taiga itself will be updated on every run to whatever Git version (tag, branch, etc.) you specify.

When run with taiga_upgrade set to true, the playbook also invokes apt-get safe-upgrade, and also upgrades all installed PIP and NPM modules (as far as possible).

If you only want to run a package upgrade and not change any configuration, you can run just the install tasks with taiga_upgrade=true:

$ ansible-playbook taiga.yml -e taiga_upgrade=true -t install
[...]
PLAY RECAP ****************************************************************
xenial-taiga-aio           : ok=84   changed=7    unreachable=0    failed=0

Base system upgrades

If you want to upgrade the base operating system of the platform that Taiga runs on (say, upgrade from Ubuntu Bionic to Ubuntu Focal in-place), you should be able to do that in the usual manner, and then continue to manage Taiga using Ansible.

However, the recommended course of action is to create a backup of your Taiga instance running on your old system, and then populate a freshly installed instance on the new system, by restoring data from that backup. To do so, use the exact same backup and restore procedure as described above, just update your inventory in between.

Tags

The roles support the following tags:

For example, if you wanted to run the whole playbook but skip all tasks that require connectivity, and also skip the automatic backups, you might run with ansible-playbook taiga.yml --tags offline --skip-tags backup.

Limitations

In addition, you should be aware that the variable defaults for taiga_backend_host, taiga_events_host and taiga_frontend_host assume that you operate a single Taiga environment from your inventory. If you want to manage several Taiga instances, then you should

Low-memory platforms

On low-memory platforms, you may bump into into the rather hefty memory utilization from compiling the pip-installed lxml package, to the point of your memory being exhausted and the installation failing. To that end, the taiga-back role checks taiga_back_required_memory against the available memory on the target machine, defaulting to 1024 (MB).

You can still install Taiga on a box with less available memory (such as an Ubuntu-powered Raspberry Pi 3 that you may use to host a Taiga instance for personal use). But you must meet a few prerequisites, at least for the duration of the installation:

  1. Swap space must be available. Yes, it’ll be terribly slow on a MicroSD card, but it will get you over lxml’s memory utilization hump.

  2. PostgreSQL must be stopped while the compilation is running. This must be done manually, the taiga-back role does not have a task for this.

  3. RabbitMQ must not run while the compilation is running. This can be accomplished by stopping RabbitMQ (again, manually), or you can set both taiga_enable_events and taiga_enable_async_tasks to false; both those features are probably not of much use on a Raspberry Pi or similar platform anyway.

  4. You must set taiga_back_required_memory to a value that matches your target system, such as 900.

Even with all these hacks in place, you’re not certain to succeed. Running Taiga on a low-memory platform generally isn’t something that you should consider “supported.”

Python 3

All of Taiga runs on Python 3, and since Ansible 2.5 and later fully support Python 3, the roles in this repository should allow you to build completely “Python 2-free” systems.

However, the rabbitmq-server package in Ubuntu Bionic currently has a dependency on python (the Ubuntu Python 2 package). Thus, if you run with taiga_enable_events: true and/or taiga_enable_async_tasks: true, which will install rabbitmq-server onto your taiga-back and taiga-events nodes, you will pull Python 2 libraries into those systems. This — depending on your Ansible configuration — may or may not cause Ansible to revert to Python 2 on subsequent runs.

License

Like Taiga itself, these playbooks are licensed under the AGPL 3.0; for the full license text see LICENSE.