Deployment

1-Click Deployment on DigitalOcean

titra is available in the DigitalOcean Marketplace for easy 1-click deployment of droplets. Get started below: 

Create a droplet on DigitalOcean


Environment Variables

ROOT_URL: the URL under which titra is served. Could be http://localhost:3000 for a local instance or https://app.titra.io for a setup with reverse proxy and DNS records.

MONGO_URL: the URL of the mongoDB backend (e.g. mongodb://localhost:27017/titra)

MONGO_OPLOG_URL: the URL pointing to the OPLOG of the mongoDB backend (e.g. mongodb://localhost:27017/local)

MAIL_URL: The server reads from the MAIL_URL environment variable to determine how to send mail. The MAIL_URL should reference an SMTP server and use the form:

smtp://USERNAME:PASSWORD@HOST:PORT

or

smtps://USERNAME:PASSWORD@HOST:PORT

The smtps:// form (the s is for “secure”) should be used if the mail server requires TLS/SSL (and does not use STARTTLS) and is most common on port 465. Connections which start unencrypted prior to being upgraded to TLS/SSL (using STARTTLS) typically use port 587 (and sometimes 25) and should use smtp://. For more information see the Nodemailer docs

METEOR_SETTINGS are Deprecated starting with titra version 0.18.0

Please use the new Globalsettings available for administrators through the Administration page.

METEOR_SETTINGS: the titra specific settings in JSON format, all settings have to belong to the “public” hierarchy. The available parameters are:

disablePublic: true/false – if set to true, projects can not be set as public

enableAnonymousLogins: true/false – if set to true, the /try path will be available allowing anonymous accounts to be created on the fly.

Below is an example for a METEOR_SETTINGS environment variable value:

{
  "public": {
   "disablePublic": "true",
   "enableAnonymousLogins": "true"
  }
}

Docker Guide

Deploying titra with Docker

You will need a MongoDB container to use titra. Here is an example to get started:

docker run --name mongodb -p 27017:27017 mongo

Please note that this basic approach will store all database data in a transient Docker volume – this is not a good approach to run MongoDB in production! Checkout this guide for a more sophisticated approach on how to get started with running MongoDB in Docker.

Once the database is ready, titra needs to be aware of that container, an easy way to achieve this is using –link:

docker run --name titra -p 3000:3000 --link mongodb -e MONGO_URL=mongodb://mongodb/titra -e ROOT_URL=http://localhost:3000 kromit/titra

In addition to the manual steps above, you can also use docker-compose to deploy the whole stack:

curl -L https://github.com/faburem/titra/raw/master/docker-compose.yml | ROOT_URL=http://localhost:3000 docker-compose -f - up

Please note that our standard Docker compose file does not map a volume for the database files and thus everything is stored in a transient Docker volume.

Congratulations! titra should now be up and running at http://localhost:3000

Persisting MongoDB database files

As mentioned above, the MongoDB container will fallback to using transient Docker volumes if not specified otherwise. If you are planning to run titra in production you should therefore specify a volume mapping for the container path /data/db. A ready-to-roll production yml file can also be found in the titra GitHub repository which maps the container path to /root/mongodb. This setup is used for the DigitalOcean one-click deployment app.

Sending E-mails

Environment Variables

MAIL_URL: The server reads from the MAIL_URL environment variable to determine how to send mail. The MAIL_URL should reference an SMTP server and use the form:

or

The smtps:// form (the s is for “secure”) should be used if the mail server requires TLS/SSL (and does not use STARTTLS) and is most common on port 465. Connections which start unencrypted prior to being upgraded to TLS/SSL (using STARTTLS) typically use port 587 (and sometimes 25) and should use smtp://. For more information see the Nodemailer docs

Docker Setup

The MAIL_URL can be passed to Docker with the -e parameter:

It can also be added in a similar way with docker-compose:

Update an existing titra instance (Docker)

If you have used the quick start guide in the titra Github repository you can use the following steps to update titra to the latest version:

  1. curl -L https://github.com/faburem/titra/raw/master/docker-compose.yml | docker-compose -f - down
  2. docker pull kromit/titra
  3. curl -L https://github.com/faburem/titra/raw/master/docker-compose.yml | ROOT_URL=http://localhost:3000 docker-compose -f - up

The commands above assume that you are executing them either as a user with root permissions or docker is running in rootless mode. Depending on your setup you might have to add 'sudo' before the docker-compose commands.

If you have used a local docker-compose.yml file to override some default settings you can of course replace the curl command with your local file.

docker pull kromit/titra will pull the latest version, however you can also use any tag to update to a specific version (e.g. docker pull kromit/titra:0.89.6)

Titra on Synology nas DSM

If your system do support Docker ( here the list ) go and install it from the Synology package center.

Once you have Docker installed open the package and go to the Registry menu to search for the images we need to run Titra.

image

Search for titra and double click on the kromit/titra to download the Titra’s image.
Select from dropdown the latest version available (latest tag is not working for me so i choose 0.29.0 manually)

Next image needed is mongo for the mongodb
Go again in Registry and search for mongo to download 4.2 version

image

Once the images are downloaded go to Image section and there you’ll find them.

Now it’s time to create Containers from the images.

At first we create the db container

double click on the mongo image and select a name for the container (e.g. mongodb)

image

click Next and then uncheck “Run this container after the wizard is finished” before clicking Apply

Now go to container section and EDIT the mongodb container to set up a Volume for data persistency

image

click Add Folder and select a folder on your nas to store the db datas as mount path set /data/db and then apply.

Now start the container with the toggle you see right next to it and wait some time to have it up.

if you double click on container and go in LOG label you’ll see something like this
NETWORK [listener] Listening on 0.0.0.0

meaning mongodb is up and listening on all interfaces.

Go back to images section, now is time for creating Titra container and linking it to mongodb

Double click on Titra image, choose a name for it and click the advanced button

image

Go to port settings and choose a local port that is free on your system, don’t touch container port.

image

Now switch to Environment tab and set 2 new variables for the container

image

They must be set accordingly to your container configuration

For example:

ROOT_URL = http://10.0.1.100:3000
and
MONGO_URL = mongodb://mongodb:27017/titra

as 10.0.1.100 is my local lan NAS ip

Now go Next and click apply to have the container running.
Docker could alert you that mongodb was started because its needed to Titra (it’s ok it’s our goal)

In container section you must see both container running

image

Let’s test if everythings gone right

open your broswer and point it to http://nasip:port choosen before Titra should be working ?

image
Tutorial by github.com/tomonetml

Zammad Interface

Enable CORS

This might be specific to our setup, but after following the default installation instructions for the Zammad community edition we had to add the following to the end of our nginx configuration (/etc/nginx/sites-enabled/zammad.conf) to have a working CORS setup:

  location /api/ {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Headers' '*';
        proxy_hide_header 'Access-Control-Allow-Origin';
        proxy_hide_header 'Access-Control-Allow-Headers';
        proxy_pass http://zammad-railsserver;
  }

Create API access token

Login to your Zammad instance and go to Profile > Token Access. Create a new Personal Access token for titra. Since we are only querying ticket information we only need the ticket.agent permission to use the API:

Connect titra to Zammad

In titra navigate to Settings > Interfaces and enter the URL of the Zammad instance (don’t forget the trailing “/”) and the previously generated Access Token.

Verify and Enjoy

If the interface has been setup correctly you can now use your Zammad tickets as a task source for time tracking! Try searching for some of your tickets and they will show up in the task auto-complete suggestion.

Wekan Integration

The built-in Wekan integration of titra enables you to plan your project tasks in Wekan using the agile methodology and track time against these very tasks when you and your time work on them. This is powerful combination which can be used to efficiently execute projects of any size and duration.

Prerequites

  1. A titra environment (preferable secured over HTTPS) e.g. app.titra.io
  2. A Wekan environment (preferable secured over HTTPS). Attention, if the environments are served from different hosts, make sure the Access-Control-Allow-Origin header is set to allow access from the the titra environment.

For 2. this is in particular the CORS environment variables of Wekan, to enable CORS for all domains you can use the following settings: CORS=*, CORS_ALLOW_HEADERS=Authorization. More details can be found in the corresponding Wekan documentation.

How to enable and configure the Wekan integration in titra

  1. Enable the Wekan integration in titra 
    Administration > Global Settings

    image-1642153511833.png

  2. Edit the project you want to link to a Wekan board


  3. Wekan: Click on "Export board" in the Wekan board menu
  4. Wekan: In the submenu Right click on "Export board to JSON" to copy the Wekan board URL

    Export Wekan board

  5. Paste the copied URL to the project Wekan integration field, click on "Check" to validate the URL 

    image-1642155190279.png

  6. If the provided URL is valid and can be reached from titra, the available lists will be retrieved from Wekan. Select the list you want to use as source for time-tracking and click on Save

    image-1642155526858.png

  7. Verify the Wekan integration works by searching for a card in the track time view 
    Verify Wekan integration

OpenID Connect (OIDC) Authentication

  1. Configure your OIDC client for Authorization Code Flow
  2. Set the relevant fields in titra

You can disable the default login form to prevent password based logins entirely:

image.png

Gitlab OpenID Provider

Example configuration provided by Github user Rishats in issue 171.
Screenshot from 2023-04-28 13-33-08

Screenshot from 2023-04-28 13-33-35

All credit goes to @iamscottcab who has authored this documentation and provided two pull requests to improve the OIDC integration. Also a shoutout to @Rishats for providing the Gitlab example configuration!

API documentation

To use the titra API you need to create an API token first. See user-settings for more information.
Once the setup is complete, the complete titra API documentation can be found at https://kromitgmbh.github.io/titra/ .

MongoDB version compatibility

titra is built on Meteor.js which is in turn using the official Node.js MongoDB driver. The official statement regarding compatibility can be found here.

titra will always be updated to the latest Meteor.js version and thus inherits its dependencies.The official MongoDB Node.js driver compatibility is available here.