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 have always 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-terms. 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.

• Sprintboard
  Provides possibility for short-term scheduling.
• Backlog
  Provides possibility for long-term scheduling.
• Olea-bar
  A command line tool to create and edit existing issues.
• Time-logging
  For both issues and projects, where the value for the later one is simply the sum of relative issue-time-logs.
• Activity charts
  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 acitivty overview for a project and a different chart for the proportion of issues on a single project.
• Notifications
  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
    show the latest actions in multiple streams.
  • Discussion App
    Get notifications on changes or comments on a specific issue you set a watchpoint for.
  • Email notifications
    Sends notifications via email.
• Search function
  Search any type of a specific data with regex support.
• Integrations
  To simplify your workflow
  • Git
  • Slack
• REST-API
  To extend your possibilities on how to use iguana.
• Markdown support
  For nicer formatting of comments and descriptions.
• Ansible
  Easy and fast start due to the usage of ansible

You can use docker to run iguana in production. The docker-compose file comes with automated letsencrypt certificate generation.

• adapt docker/settings.json:
  • SECRET_KEY and HOST/ALLOWED_HOSTS
  • email: either use a sendgrid api key or a normal mail server
• adapt the env variables of the web service in docker-compose.yml
• run sudo docker-compose up

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

make production

This command runs the following Makefile targets:

• setup-virtualenv
• initialize-settings
• css

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

make staging

This command runs the following Makefile targets:

• setup-virtualenv stage
• initialize-settings
• css

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

make development [<webdriver>]

The <webdriver> option the driver for the setup-webriver target can be specified. Beside that the following targets are executed:

• setup-virtualenv dev
• initialize-settings dev
• css
• link-git-hooks
• setup-webdriver <webdriver>
• migrate

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/1.11/howto/deployment/wsgi/gunicorn/

To start the local Django web server simply run:

make run

TODO: write Ansible instructions

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

These targets can be run with:

make <target>

• production
  See subsection Production.
• staging
  See subsection Staging.
• development
  See subsection Development.

• help
  Prints a short description for each Makefile target.

• setup-virtualenv [dev|stage]
  This target prepares the virtual python environment in which this project is executed. The packages for the virtual environment are defined in the file requirements/production.req.
  If you want to setup the virtualenv for development (development.req) or staging (staging.req), add dev or stage option.

• initialize-settings [dev]
  This target sets up the settings for Iguana. By default the production or staging settings are loaded.
  If you want to initialize the development settings and generate a sample SECRET_KEY for Django, add the dev option.
  For more information about configuring Iguana see section Configuration.

• css
  See section Styling.

• link-git-hooks
  This target installs the required git hooks for contributing to the development process. The hooks can be found in the tools/git-hooks directory.

• setup-webdriver [<webdriver>]
  This target configures the webdriver for the functional tests. You can replace <webdriver> with chrome, firefox or safari. If you use this target for the first time and no driver is specified, it uses chrome as default. Then if there's no driver supplied, it tries to use the current one.

• makemigrations
  Create the Django migrations.

• migrate
  Apply the Django migrations to the database or create the database if no exists.

• refresh-reqs [dev|stage]
  Reinstall all packages in the virtual environment. If dev parameter is specified, the development requirements (requirements/development.req) will be installed. For stage the staging (requirements/staging.req) and if no parameter is provided, the production requirements (requirements/production.req) are reinstalled.

• startapp <appname>
  Create a new Django application with the specified name.

• test [<appname>]
  Run the Django unit tests. If an application name is provided, only that app is tested. To run the functional tests call test functional_tests[.appname].

• run
  Run the default django server.

• make-messages <lang-code>
  See section Translation.

• compile-messages
  Compile the Django messages.

• coverage [<appname>]
  Run the coverage tool on the Django tests. To get a better output you can run one of the following commands:

  • coverage-report
    Get the coverage in text form.
  • coverage-html
    Get the coverage as a html website.
  • coverage-xml
    Get the coverage as a xml file.

• coverage-erase
  Delete the last coverage report.

• list_bugs
  List all occurrence of the tag TODO BUG.

• list_missing_testcases
  List all occurrence of the tag TODO TESTCASE.

• add_license_header
  Insert the license header into all source files.

• check_requirements
  Check whether our requirements are up to date or not.

Currently the style is stored in config/scss/style.scss. To build it run make css. For Selenium tests use StaticLiveServerTestcase instead of LiveServerTestcase to make sure static files (like css) are served.

Documentation on Sass and SCSS: http://sass-lang.com/guide

I propose we use SCSS, as it is a superset of CSS and the default Sass syntax. If we change our mind, there are tools to convert between the two syntaxes.

Please use translation hooks in templates (see \_base.html for an example) and code (ugettext as _).

You can create/update the *.po in the locale directory by running make-messages <lang-code>. The default language is English (code: en). This file is where the actual translations go. It should be checked in after updating. This uses the GNU gettext toolset.

For new translations to be usable by django, run make compilemessages.

To see a page in a different language, open it with a different language prefix in the url. For example /de/login instead of /en/login.

Iguana has a lot of settings that can be changed by the user. The settins files are stored in the common/settings package. The package structure is:

common/settings
          |- __init__.py
          |- common.py
          |- global_conf.py
          |- local_conf.py

A default init-file gets created by the Makefile target initialize-settings (see section Makefile targets).
For the development process this file can contain additional settings that should not be published in the repository. Mainly the Django-SECRET_KEY = '...' setting is defined here, when the project is in the development environment.
Important: The file must start with the line:

from <site_config> import *

You can replace <site_config> with (don't forget the '.'):

• .local_conf: the development settings are loaded
• .global_conf: the production and staging settings are loaded

This file contains the basic settings that are the same for the other two configuration files.
This file should not be changed by the user! It contains basic settings for the Django framework. Changing these settings without knowing what you do could lead to unexpected behaviour.

Basically this file contains all settings that are required to run Iguana in an staging or production environment.
But the settings that should be changed by the user are loaded from the file /var/lib/iguana/settings/settings.json. This file gets created when installing Iguana through Ansible. A template for this file can be found in ansible/roles/user/files/settings_template.json.

This file contains all settings that are required to run Iguana in a development environment.
Normally there's no need to change these settings.

Iguana was mainly developed with the Django framework (https://www.djangoproject.com).

Iguana is licensed under the CC-BY-SA license:
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. Since we use the version 4 of CC-BY-SA there is not necessarily an incompatibility with GPL - see Can I apply a Creative Commons license to software? and ShareAlike compatibility: GPLv3. If you see any problems that are caused by that CC-BY-SA license tell us and we might find a solution.

Besides the following plug-ins were used: