Iguana

Description

Iguana is a mixture of a ticket system, an issue tracker and an issue management system, heavily based on basic functions being easy to use. So Iguana can help you to plan the next schedule and to always have a nice overview about your current tasks depending on your needs, especially for working in groups. There is a kanban board to keep an eye on the progress until the end of the next planning stage and also a backlog to have the ability for scheduling of long-term tasks. In combination with a mechanism to log time spent on different tasks individually those are the essential functionalities.

For more detailed documentation including a list of features see our github documentation page at https://iguana-project.github.io.

Features

• Sprintboard<br /> Provides possibility for short-term scheduling.
• Backlog<br /> Provides possibility for long-term scheduling.
• Olea-bar<br /> A command line tool to create and edit existing issues.
• Time-logging<br /> For both issues and projects, where the value for the later one is simply the sum of relative issue-time-logs.
• Activity charts<br /> To keep an eye on the progress of a specific project in both aspects, for time management and amount of activities (e.g. commits). There is an activity overview for a project and a different chart for the proportion of issues on a single project.
• Notifications<br /> Present multiple ways to notify you for different events. In the future it will be customizable which notifications shall be shown with which feature.
  • Activity stream<br /> show the latest actions in multiple streams.
  • Discussion App<br /> Get notifications on changes or comments on a specific issue you set a watchpoint for.
  • Email notifications<br /> Sends notifications via email.
• Search function<br /> Search any type of a specific data with regex support.
• Integrations<br /> To simplify your workflow
  • Git
  • Slack
• REST-API<br /> To extend your possibilities on how to use iguana.
• Markdown support<br /> For nicer formatting of comments and descriptions.
• Ansible<br /> Easy and fast start due to the usage of ansible
• Docker<br /> Alternatively an even easier and faster start with Docker

Installation

Manual

Preparation

If you want to manually install Iguana, there are some dependencies and actions that must be installed and done before:

Dependencies

TODO: more dependencies required

We generally try to avoid any non-python dependencies but this doesn't always work well. The test cases need the Exempi library so for the development environment this is required and can be installed like this:

apt-get install libexempi3  # Ubuntu/Debian
pacman -S exempi		    # Arch Linux
brew install exempi         # OS X

Setup Python Version

Iguana is currently tested against Python 3.8.</br> It may be also run on higher versions. But if you run into any problems, please test first if they also occur with Python 3.8.

To install Python 3.8 locally (independent from your current system version), you can use pyenv. For installation and setting up pyenv please stick to their documentation: https://github.com/pyenv/pyenv/wiki

Once you've got pyenv running execute the following command in the main iguana directory:

pyenv install -v $(cat .python-version)

If everything is correctly setup and if you simply run python in your command shell, the python interpreter with the version specified in the .python-version file should be started. If you already created a virtualenv previously you should delete it and recreate it with the specified python version.

Common problems using pyenv: Since pyenv is compiling every python version other than your system one directly on your PC, it can happen that after some time this version won't work any more. Often there are errors of missing shared libraries, when you try to start Iguana or the Python interpreter installed by pyenv. This can happen e.g. after a system update/upgrade. To solve this issue simply reinstall the Python version with the above pyenv command.

Production

To setup Iguana in a production environment you simply have to call:

make production

This command runs the following Makefile targets:

• setup-virtualenv
• django makemigrations
• django migrate
• css

Staging

To setup Iguana in a staging environment you simply have to call:

make staging

This does the same as the production target but it creates the staging virtual environment.

Development

To setup Iguana in a development you simply have to call:

make development ++webdriver [<webdriver>]

The <webdriver> option the driver for the setup-webriver target can be specified ("chrome" is used as default). Beside that the following targets are executed:

• production
• setup-webdriver <webdriver>

Starting Iguana

Currently Iguana supports only Nginx as web server backend. For configuring Nginx and using Gunicorn together with Django please stick to the official documentation: https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/gunicorn/

Starting the local Iguana instance

To start the local Django web server simply run:

make run

Docker

Build images

Three images can be built with the Dockerfile:

• development (default)

  docker build -f Dockerfile .

• staging/production

  docker build -f Dockerfile . --build-arg VARIANT=[staging|production] [--build-arg USE_NGINX=[false|true]]

  The USE_NGINX variable indicates if a (basic) Nginx server should be included in the image. The default value is false!

Start a container

Each Iguana docker image can be started with the following command:

docker run -d \
	-p 80:8000 \
	-v <data_directory>:/files \
	-e TZ=<time zone> \
	-e PUID=<user ID> \
	-e PGID=<group ID> \
	<Iguana image ID>

| Environment variable | Default value | Description | |-|-|-| | TZ | UTC | Set the time zone for the container, e.g. Europe/Berlin | | PUID | 1000 | The ID of the user running Iguana in the container | | PGID | 1000 | The group ID of the above user |

But in staging/production environment more configuration should be done by the user! Therefore a settings.json file is placed in the Docker volume after the first run. You can edit this file to your needs (see Configuration section -> settings.json). To apply the changes simply restart the container. Please look especially at the SECRET_KEY and HOST/ALLOWED_HOSTS settings!

If a Nginx server was included in the image (with USE_NGINX=true), the nginx.conf file can also be found on the Docker volume. But for real production environments, a separate Nginx container is recommended!

All files uploaded to Iguana are placed in the media directory on the Docker volume.

TODO: add DockerHub badges and links

Using Ansible for deployment

TODO: write Ansible instructions

Integrations

• TODO: write instructions for git integration
• TODO: write instructions for slack integration

Makefile targets

These targets can be run with:

make <target> [++option]

Note that options have to begin with + or ++ instead of - or --. This is due to a bug that prevents passing options to make targets.

Main:

• help<br /> Prints a short description for each Makefile target.

• production<br /> See subsection Production.

• staging<br /> See subsection Staging.

• development [+w <webdriver>]<br /> See subsection Development.

Django management:

• django <command> [<args>]<br /> Any command and its arguments gets directly passed to Django's manage.py script. Please have a look at the official Django documentation for a list of supported commands: https://docs.djangoproject.com/en/dev/ref/django-admin/

• test [+a <appname>|+f|+c] [+i]<br /> Run the Django unit tests. If an application name is provided with +a, only that app is tested. To run the functional tests use the +f option. If all tests should be run, use option +c. With the option +i the warnings and errors from imported packages get suppressed