Deploying Titra

Introduction

Titra is a modern, open-source time tracking application built for freelancers, teams, and organizations who need accurate time logging with powerful reporting capabilities. Built with Meteor.js and MongoDB, Titra provides a responsive web interface that works seamlessly across desktop and mobile devices.

Unlike proprietary time tracking solutions, Titra gives you complete control over your data while offering features comparable to commercial alternatives. From simple time entries to detailed project reporting, Titra scales from individual use to team deployments.

Key highlights of Titra:

Intuitive Time Tracking: Start/stop timers or manual time entry with flexible options
Project Management: Organize time entries by projects and customers
Team Support: Multi-user with team management and permissions
Detailed Reporting: Generate reports by project, user, date range, or custom filters
Export Capabilities: Export data to CSV, PDF, and other formats
Billable Hours: Track billable vs. non-billable time with rate management
Calendar Integration: View time entries in calendar format
API Access: REST API for integrations and automation
Responsive Design: Works on desktop, tablet, and mobile
100% Open Source: Licensed under GPL-3.0

This guide walks through deploying Titra on Klutch.sh using Docker, configuring projects and teams, and leveraging reporting features.

Why Deploy Titra on Klutch.sh

Deploying Titra on Klutch.sh provides several advantages for time tracking:

Always Accessible: Access your time tracker from anywhere with 24/7 availability.

HTTPS by Default: Secure access to your time data with automatic SSL certificates.

Persistent Storage: Your time entries and project data persist safely across restarts.

GitHub Integration: Manage configuration through version control with automatic redeployments.

Scalable Resources: Start small for individual use and scale up for team deployments.

Custom Domains: Use your own domain for a branded time tracking experience.

Prerequisites

Before deploying Titra on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization concepts
MongoDB database (MongoDB Atlas recommended)
(Optional) A custom domain for your Titra instance

Understanding Titra Architecture

Titra uses a modern web application stack:

Meteor.js Framework: Full-stack JavaScript framework providing real-time data synchronization and reactive UI updates.

MongoDB Database: Document database storing all time entries, projects, users, and settings.

Blaze Templates: Reactive template engine for the user interface.

Node.js Runtime: Server-side JavaScript execution environment.

Preparing Your Repository

Create a GitHub repository with your Titra configuration.

Repository Structure

titra-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/kromitgmbh/titra:latest

# Set environment variables
ENV ROOT_URL=${ROOT_URL:-http://localhost}
ENV MONGO_URL=${MONGO_URL:-mongodb://mongo:27017/titra}
ENV PORT=3000

# Expose the web interface port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
node_modules

Deploying Titra on Klutch.sh

Follow these steps to deploy your Titra instance:

Set Up MongoDB

Titra requires MongoDB. For simplicity, use MongoDB Atlas:

Create a free cluster at MongoDB Atlas
Note your connection string

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Titra configuration"
git remote add origin https://github.com/yourusername/titra-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Name it something like “time-tracker” or “titra”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Titra repository.

Configure HTTP Traffic

Titra serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 3000

Set Environment Variables

Configure essential environment variables:

Variable	Value
`ROOT_URL`	`https://your-app-name.klutch.sh`
`MONGO_URL`	Your MongoDB connection string
`MAIL_URL`	`smtp://user:pass@smtp.example.com:587` (optional)

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
`/app/uploads`	5 GB	File uploads and attachments

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Build your Docker image
Attach persistent volumes
Start the Titra server
Provision an HTTPS certificate

Create Your Account

Navigate to https://your-app-name.klutch.sh and register your first account.

Initial Setup

Creating Your First Project

After logging in:

Navigate to Projects
Click New Project
Enter project details (name, description, customer, hourly rate)
Save the project

Time Entry Basics

Enter time using different methods:

Timer Mode:

Select a project
Click Start Timer
Work on your task
Click Stop when finished

Manual Entry:

Click Add Entry
Select date and project
Enter start/end times or duration
Add description and save

Project Management

Project Structure

Organize your work:

Customer
└── Project
    └── Time Entries

Creating Customers

Add customers for better organization:

Go to Customers
Click New Customer
Enter customer details
Assign projects to customers

Team Management

Adding Team Members

Invite users to your Titra instance:

Go to Settings > Users
Click Invite User
Enter email address
Set role and permissions

User Roles

Role	Capabilities
Admin	Full system access, user management
Manager	Team oversight, all reports
User	Own time entries and basic reports

Reporting

Built-in Reports

Titra provides several report types:

Time Report:

Filter by date range, project, user
View totals and breakdowns
Export to CSV/PDF

Project Report:

Budget utilization
Time distribution
Team member contributions

Exporting Data

Export options:

Format	Use Case
CSV	Spreadsheet analysis
PDF	Client invoices
JSON	API integrations

Billing and Invoicing

Billable Time

Mark time as billable:

On time entry, toggle Billable
Set hourly rate
Include in billing reports

Invoice Generation

Generate client invoices:

Go to Reports > Invoice
Select customer and date range
Review billable entries
Generate invoice PDF

Performance Tuning

Resource Recommendations

Team Size	RAM	CPU
1-5 users	512 MB	0.5 vCPU
5-20 users	1 GB	1 vCPU
20-50 users	2 GB	2 vCPU

Troubleshooting Common Issues

Cannot Connect to MongoDB

Symptoms: Application won’t start or shows database errors.

Solutions:

Verify MONGO_URL is correct
Check MongoDB cluster is accessible
Ensure IP whitelist includes Klutch.sh IPs

Slow Performance

Symptoms: Long page load times.

Solutions:

Check MongoDB performance
Increase allocated resources
Limit report date ranges

Additional Resources

Conclusion

Titra on Klutch.sh provides a powerful, self-hosted time tracking solution that rivals commercial alternatives while keeping your data under your control. Whether you’re a freelancer tracking billable hours or a team managing project time, Titra’s feature set covers the essentials with room to grow.

The combination of Meteor.js real-time updates, comprehensive reporting, and team collaboration features makes Titra suitable for serious time tracking needs. Deployed on Klutch.sh with MongoDB, you get a reliable, always-accessible time tracking system without managing complex infrastructure.