README.md.j2

Taiga Dockerized environment
============================

Complete environment to run self-hosted Taiga.io project in an elegant
way.

**Features:**
- Optional SSL support in the container
- Optional events support (allows live updates in the application)
- BUILDS ANY TAIGA VERSION EASILY!
- In comparison to other docker images, this one runs production
  environment...
- Very flexible, a lot of environment variables to configure
- Uses docker-compose to simplify setup, can be used also standalone or
  in Kubernetes/Swarm
- Uses standardized JINJA2 to generate configuration files
- Allows to change a lot of parameters without rebuilding the container
- With Makefile all tasks are automated enough to provide a fully working environment without need to adjust anything

*Notice: This is not a official Taiga.io project and is not affiliated
with Taiga Agile, LLC © or any other company, it's a completly grassroot
project*

*Based on docker image built originally by Benjamin Hutchins <ben@hutchins.co> and released on GPL license*

*Built docker images are licensed under MIT*

#### What is Taiga?

Taiga is a project management platform for startups and agile developers & designers who want a simple, beautiful tool that makes work truly enjoyable.

> [taiga.io](https://taiga.io)

#### Running the container

The container is placed at `quay.io/riotkit/taiga`. There is no `latest` tag, we do not like it, it's an unstable, dangerous idea to use latest.
Instead of `latest` we tag each Taiga stable release with the release number ex. `quay.io/riotkit/taiga:4.2.12`

See the list of available tags there: https://quay.io/repository/riotkit/taiga?tab=tags and check out the configuration reference.

![versioning](./docs/versioning.png)

```bash
# NOTICE 1: Check "Configuration reference" section of this README for list of available environment variables
# NOTICE 2: You need a working PostgreSQL server
# NOTICE 3: Use volumes to keep your uploads, else they will disappear on container recreation

sudo docker run \
    -v $(pwd)/media:/usr/src/taiga-back/media \
    -p 80:80 \
    -e TAIGA_DB_HOST=some-db-host \
    -e TAIGA_DB_USER=some-user \
    -e TAIGA_DB_PASSWORD=some-password \
    quay.io/riotkit/taiga:4.2.12
```

#### Quick start with Docker-Compose

```
# get the sources
git clone https://github.com/riotkit-org/docker-taiga.git
cd docker-taiga

# prepare the environment
virtualenv .venv
source .venv/bin/activate
pip install -r ./requirements.txt

# optionally if you do not have docker-compose
# pip install docker-compose

# edit configuration
cp .env.dist .env
edit .env

# start it!
rkd :start

# tadam...
```

##### First log-in to the application, default username and password

To log-in first time you should go to the [login page](http://localhost/login?next=%252Fdiscover) and enter "admin" as username, and "123123" as password.
You can also log-in to the Django administration panel at http://localhost/admin/ (please remember about the slash at the end)

#### Configuring LDAP

LDAP support can optionally be enabled by setting the `TAIGA_LDAP` environment variable to `true`. See the Dockerfile for a list of the environment variables used for configuring LDAP and their descriptions.

#### Configuration reference

List of all environment variables that could be used.

```yaml
{% for env_var, attrs in DOCKERFILE_ENVS.items() %}{% if attrs[2] %}# {{ attrs[2] }}{% endif %}
- {{ attrs[0] }} # (default: {{ attrs[1] }})

{% endfor %}
```

Building images
---------------

```
# to build a 4.2.5 version of backend and frontend
rkd :build:snapshot --backend-version=4.2.5 --frontend-version=4.2.5-stable
```

Troubleshooting
---------------

1. Not able to log-in or edit user settings

If you have trouble logging in or editing user settings it may be related to a failure sending emails. This will be accompanied by a `[CRITICAL] WORKER TIMEOUT` error in the logs. Try validating your email configuration or setting `TAIGA_ENABLE_EMAIL` to `false` to see if that fixes the issue.

2. Using existing database

Set `TAIGA_DB_HOST` to point to your PostgreSQL hostname.
See also: https://github.com/riotkit-org/docker-taiga/issues/24

3. Debugging, getting logs

In container there is a supervisor configured. Use `supervisorctl` to access services.

Examples:
```bash
supervisorctl status send_app_notifications
supervisorctl tail -f send_app_notifications stderr
supervisorctl tail -f backend stderr
supervisorctl tail -f nginx stderr
```

4. Installing under subpath, not subdomain eg. domain.org/taiga

Sorry, you cannot. The application itself does not support it. See https://github.com/riotkit-org/docker-taiga/issues/32

5. Running under custom port eg. 8002

Taiga's frontend requires a fixed url to be defined in a configuration file, the container is doing this on start - you only need to append port to `TAIGA_HOSTNAME` variable.

Example: `TAIGA_HOSTNAME=taiga.localhost:8002` (see: [#41](https://github.com/riotkit-org/docker-taiga/issues/41))

Developing the container
------------------------

- The container is built on quay.io
- When you start working on it locally, please before commiting do the `rkd :generate-readme` (pull requests should be rejected, when something was added only to README.md, not to README.j2, and when environment variables were added to Dockerfile but README file was not generated)
- Use `rkd` for building, pushing, etc.

Releasing
---------

On Travis CI the build is triggered each month, then all recent versions of Taiga are built. Already existing docker tags are not overwritten.
The build is also triggered on-commit. Snapshot version is made from master branch, and is always a latest master, can be unstable.

To release a bugfix version and REBUILD EXISTING TAGS just add "@force-rebuild" in commit message, recent 3 tags will be rebuilt (not all in registry).

Versioning
----------

![versioning](./docs/versioning.png)

The container has it's own versioning.  There are a few rules:

1. Releasing TEST builds requires tagging `master` branch with name containing "RC" eg. `1.0-RC3`

After tagging 1.0-RC3, recent 3 versions of Taiga will be built with RC eg. quay.io/riotkit/taiga:4.2.12-D1.0-RC3
**No main tag would be replaced, so quay.io/riotkit/taiga:4.2.12 stays untouched**

2. Development versions of the container

On each commit a SNAPSHOT version is produced. Snapshot means a not numbered version of docker container, replaces on each new commit.

Example of produced images on push: taiga:5.0.0-SNAPSHOT, taiga-5.0.1-SNAPSHOT

2. Releasing STABLE images requires tagging `master` with just version number eg. `1.0`

When `master` branch was tagged and pushed with eg. `1.0`, then 2 recent versions of Taiga would be rebuilt.
The main versions such as **quay.io/riotkit/taiga:4.2.12** would be rebuilt, and new tags such as **quay.io/riotkit/taiga:4.2.12-D1.0** would be produced.

If you want to use only unchanged, stable releases, without getting hotfixes you should use a TAIGA VERSION + BUILD NUMBER, WITHOUT RC. Example: **quay.io/riotkit/taiga:4.2.12-D1.0**

Copyleft
--------

Created by **RiotKit Collective**, a libertarian, grassroot, non-profit organization providing technical support for the non-profit Anarchist movement.

Check out those initiatives:
- International Workers Association (https://iwa-ait.org)
- Federacja Anarchistyczna (http://federacja-anarchistyczna.pl)
- Związek Syndykalistów Polski (https://zsp.net.pl) (Polish section of IWA-AIT)
- Komitet Obrony Praw Lokatorów (https://lokatorzy.info.pl)
- Solidarity Federation (https://solfed.org.uk)
- Priama Akcia (https://priamaakcia.sk)