1. Recommended Upgrade Process

This is the recommended migration process, as using Taiga6 with docker is the recommended way to run Taiga in production. This tutorial assumes that you have a Taiga5 instance running either from source code or from Taiga5 docker images.

Note Although there are different Taiga docker images, this tutorial has been tested with:

For other installations, the steps to "Get the data from Taiga5" may differ.

1.1. Requirements and caveats

Prior to start the migration, ensure:

  • you have access to the Taiga5 server and its configuration:

    • in a source code installation, a local.py file

    • in a docker installation, the docker-compose.yml file

  • you have access to the Taiga6 server, and have cloned the taiga-docker repository

  • the Taiga6 server has docker and docker-compose

Besides, have in mind that:

  • for this migration, you stop the access to Taiga5 service to prevent state modifications (bbdd and media files)

  • this tutorial asumes that the destination bbdd is empty or may be emptied

1.2. Get the data from Taiga5

Before moving on through this tutorial, this could be a perfect moment to prevent other users from changing data in Taiga5. Remove the access to Taiga5.

1.2.1. …​ in a source code installation

Media files

Typically media files are in taiga-back/media. Create a tar with all the media files:

$ cd taiga-back/
$ tar -czf taiga5_media.tar.gz media
Database dump

Create a dump with the data; with postgres, it would be:

$ pg_dump -U $TAIGA_DB_USER -h $TAIGA_DB_HOST $TAIGA_DB_NAME > taiga5_db.sql

Move these two files to the server where Taiga6 will be.

1.2.2. …​ in a docker installation

Media files

Inside the container, media files are in /srv/taiga-back/media. To get them, enter the server container interactively and follow these steps:

:/# cd /srv/taiga-back
:/# tar -czf media/taiga5_media.tar.gz media

Exit the container and get the media file:

$ docker cp {CONTAINER_NAME}:/srv/taiga-back/media/taiga5_media.tar.gz .
Database dump

Enter the database container interactively and:

:/# cd
:/# pg_dump -U $TAIGA_DB_USER -h $TAIGA_DB_HOST $TAIGA_DB_NAME > taiga5_db.sql

Exit the container and get the dump file:

$ docker cp {CONTAINER_NAME}:/taiga5_db.sql .

Move these two files to the server where Taiga6 will be.

1.3. Get Taiga6

Clone this repository in the Taiga6 server.

$ cd taiga-docker/
$ git checkout stable

1.4. Configuration

There are two options to migrate the configuration:

Simple configuration: most likely this configuration will serve to your scenario. Open docker-compose.yml and migrate your configuration in local.py to the corresponding environment variables.

Advanced configuration: if you have a local.py with some complex settings, you can ignore the environment variables and map a config.py file (check the x-volumes section in docker-compose.yml).

1.5. Load the old dump

Follow these steps:

# Run only the database to avoid migrations
$ docker-compose up -d taiga-db

# Copy the dump inside the container:
$ docker cp taiga5_db.sql taiga-docker_taiga-db_1:/taiga5_db.sql

# Access the container
$ docker exec -ti taiga-docker_taiga-db_1 /bin/bash

And inside the container, load the dump:

:/# psql -U taiga taiga < taiga5_db.sql

Check that the data have been properly migrated. Delete the taiga5_db.sql file and exit the container.

1.6. Migrate the database

Next step is to run Taiga6 backend so the database can be migrated to the new schema:

$ docker-compose up -d taiga-back

1.7. Migrate the media files

With the backend up and running, copy the taiga5_media.tar.gz file inside the backend container and access the container:

$ docker cp taiga5_media.tar.gz taiga-docker_taiga-back_1:/taiga5_media.tar.gz
$ docker exec -ti taiga-docker_taiga-back_1 /bin/bash

And inside the container, remove the old media and extract the files:

:/# mv /taiga5_media.tar.gz /taiga-back/media
:/# cd /taiga-back/media
:/# tar -xzvf taiga5_media.tar.gz --strip 1
:/# rm taiga5_media.tar.gz
:/# chown -R taiga:taiga *

Exit the container, and continue with other configurations.

1.8. Other configurations

Before going on, check all the configurations recommended in the environment files.

1.9. Run Taiga6

Once everything has been migrated, launch all the services and check the result:

$ docker-compose up -d

Go to http://localhost:9000 where everything should be migrated and available.

1.10. Confingure the proxy

Your host configuration needs to make a proxy to http://localhost:9000. Example:

server {
  server_name taiga.mycompany.com;

  ...

  location / {
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Scheme $scheme;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
    proxy_pass http://localhost:9000/;
  }
}

2. From Taiga5 source code to Taiga6 source code

This is the recommended migration if you installed Taiga5 from source code and want to keep it that way.

2.1. PostgreSQL

Although it’s not strictly mandatory, it’s highly recommended to keep PostgreSQL updated. Check the official documentation and choose the best way that fits your scenario.

2.2. RabbitMQ

Although it’s not strictly mandatory, it’s highly recommended to keep RabbitMQ updated. Check the official documentation and choose the best way that fits your scenario.

2.3. Back

Run as a non-priviledged user like taiga, do not run this code as root.

 
# Update the code
$ cd ~/taiga-back
$ git checkout stable
$ git fetch && git reset --hard origin/stable

# Activate your virtual environment

# Update the dependencies
$ pip install -r requirements.txt

Configuration has changed the way it’s used. Now, it’s expected to read a DJANGO_SETTINGS_MODULE from environment with the namespace to the configuration file. Example:

$ DJANGO_SETTINGS_MODULE=settings.local python manage.py

If this envvar doesn’t exist, the system defaults to settings.common. Besides this change in the configuration system, you should check and use the file settings/config.py.prod.example with all the options. We strongly recommend that you copy this file and port your local.py settings:

cp settings/config.py.prod.example settings/config.py

Edit this file with your settings from local.py and check the new settings.

Important note: new config.py expects a database configuration, instead of relying in the database configuration of common.py. Make sure you migrate your database credentials to config.py file.

Check out the new ENABLE_TELEMETRY setting.

If you have some contrib plugins installed you should to upgrade them before the next step.

 
$ DJANGO_SETTINGS_MODULE=settings.config python manage.py migrate --noinput
$ DJANGO_SETTINGS_MODULE=settings.config python manage.py compilemessages
$ DJANGO_SETTINGS_MODULE=settings.config python manage.py collectstatic --noinput

Update /etc/systemd/system/taiga.service to have all the options shown at these instructions.

Restart taiga service.

2.4. Async tasks

Upgrade this module always after the backend.

If you are not using the async tasks service, we strongly recommend you to do: - Make sure you have CELERY_ENABLED=True in your config.py file - Make sure you have the RabbitMQ credentials in the config.py file - Create the systemd unit following these instructions

If you were already using async tasks, then: - update your config.py file with the new environment variables (check the example) - update /etc/systemd/system/taiga-async.service (it was called taiga-celery.service) to have all the options shown at these instructions.

Restart taiga-async service.

2.5. Front

$ cd ~/taiga-front-dist
$ git checkout stable
$ git rebase && git reset --hard origin/stable

Restart nginx service.

2.6. Events

If you are not using the events service, we strongly recommend you to do:

If you were already using events, it’s important that you update all dependencies, because they have completely changed. Configuration and systemd unit have changed as well. These are the steps to update it:

$ cd ~/taiga-events
$ git checkout stable
$ git rebase && git reset --hard origin/stable

# Update the dependencies
$ npm install

Use the new config file .env:

cp .env.example .env

Edit the file and put your own data (before it was in a config.json file).

Edit the systemd unit (most likely in /etc/systemd/system/taiga-events.service) to be like:

[Unit]
Description=taiga_events
After=network.target

[Service]
User=taiga
WorkingDirectory=/home/taiga/taiga-events
ExecStart=npm run start:production
Restart=always
RestartSec=3

[Install]
WantedBy=default.target

Reload the systemd daemon and restart the taiga-events service:

sudo systemctl daemon-reload
sudo systemctl restart taiga-events

2.7. Protected

If you are not using the protected service, we strongly recommend you to do:

To update it:

$ cd ~/taiga-protected
$ git checkout stable
$ git rebase && git reset --hard origin/stable

Important note: check the configuration variables needed for this module:

DEFAULT_FILE_STORAGE = "taiga_contrib_protected.storage.ProtectedFileSystemStorage"
THUMBNAIL_DEFAULT_STORAGE = DEFAULT_FILE_STORAGE

Restart the taiga-protected and taiga-back services.

2.8. Nginx

Although it’s not strictly mandatory, it’s highly recommended to keep Nginx updated. Check the official documentation and choose the best way that fits your scenario.

Besides, there is a new recommended base configuration for Nginx (slightly different from Taiga5), so we encourage you to check it and update it.