Deploying Tracim

Introduction

Tracim is an open-source collaborative workspace platform designed for teams who need to share documents, collaborate on content, and maintain organized discussions. It provides a unified space where team members can work together on files, threads, and pages while maintaining clear organization through workspaces.

Built with Python (backend) and React (frontend), Tracim offers a modern approach to team collaboration with features that rival commercial solutions. Its workspace-centric design helps teams organize information logically while enabling seamless sharing and permission management.

Key highlights of Tracim:

• Shared Workspaces: Organize content into logical spaces with customizable permissions
• Document Management: Upload, share, and collaboratively edit documents
• Rich Text Editing: Create and edit pages with a WYSIWYG editor
• Threaded Discussions: Comment and discuss content within context
• File Versioning: Track changes and access previous versions
• User Mentions: Tag team members in discussions for notifications
• WebDAV Support: Access files through standard file protocols
• LDAP/SSO Integration: Connect to existing authentication systems
• Real-Time Updates: See changes as they happen
• 100% Open Source: Licensed under AGPL-3.0

This guide walks through deploying Tracim on Klutch.sh using Docker, setting up workspaces, and configuring team collaboration features.

Why Deploy Tracim on Klutch.sh

Deploying Tracim on Klutch.sh provides several advantages for team collaboration:

Always Accessible: Team members can access shared workspaces from anywhere, anytime.

HTTPS by Default: Secure communication for sensitive documents with automatic SSL certificates.

Persistent Storage: Documents and workspace data persist safely across restarts.

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

Scalable Resources: Start small and scale up as your team and content grows.

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

Prerequisites

Before deploying Tracim 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
• PostgreSQL database (or plan to use embedded)
• (Optional) A custom domain for your Tracim instance

Understanding Tracim Architecture

Tracim uses a layered architecture:

Backend: Python/Pyramid-based API server handling business logic and data management.

Frontend: React-based single-page application providing the user interface.

Database: PostgreSQL for persistent storage of workspaces, content, and users.

File Storage: Filesystem-based storage for uploaded documents and attachments.

WebDAV: Protocol support for native file system integration.

Preparing Your Repository

Create a GitHub repository with your Tracim configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM algoo/tracim:latest

# Set environment variables
ENV TRACIM_WEBSITE__BASE_URL=${TRACIM_WEBSITE__BASE_URL}
ENV TRACIM_DATABASE__SQLALCHEMY_URL=${TRACIM_DATABASE__SQLALCHEMY_URL}
ENV TRACIM_USER__AUTH_TOKEN__VALIDITY=604800

# Create data directories
RUN mkdir -p /var/tracim/data /var/tracim/depot /var/tracim/logs

# Expose ports
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
    CMD curl -f http://localhost/api/system/is-alive || exit 1

Creating the .dockerignore File

Create a .dockerignore file:

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

Deploying Tracim on Klutch.sh

Follow these steps to deploy your Tracim instance:

Set Up PostgreSQL

Tracim requires PostgreSQL. Options include:

• Deploy PostgreSQL separately on Klutch.sh
• Use a managed PostgreSQL service (recommended)

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Tracim configuration"
git remote add origin https://github.com/yourusername/tracim-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 “collaboration” or “tracim”.

Create a New App

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

Configure HTTP Traffic

Tracim serves its web interface over HTTP:

• Select HTTP as the traffic type
• Set the internal port to 80

Set Environment Variables

Configure essential environment variables:

Variable	Value
TRACIM_WEBSITE__BASE_URL	https://your-app-name.klutch.sh
TRACIM_DATABASE__SQLALCHEMY_URL	postgresql://user:pass@host:5432/tracim
TRACIM_EMAIL__NOTIFICATION__ACTIVATED	true
TRACIM_EMAIL__NOTIFICATION__SMTP__SERVER	Your SMTP server

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
/var/tracim/data	50 GB	Application data
/var/tracim/depot	100 GB	Uploaded files and documents
/var/tracim/logs	5 GB	Application logs

Deploy Your Application

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

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

Complete Initial Setup

Navigate to https://your-app-name.klutch.sh and create your admin account.

Initial Configuration

Creating Admin Account

On first access, create your administrator:

1. Navigate to the setup page
2. Enter admin email and password
3. Complete the registration

Creating Your First Workspace

Set up a workspace for your team:

1. Log in as admin
2. Click Create Workspace
3. Enter name and description
4. Configure initial permissions

Workspace Management

Workspace Types

Tracim supports different workspace configurations:

Type	Description
Shared	All members can view and edit
Private	Restricted to specific users
Public	Visible to all registered users

Adding Members

Invite users to workspaces:

1. Open the workspace
2. Click Members
3. Add users by email
4. Set their role (Reader, Contributor, Content Manager, Workspace Manager)

User Roles

Role	Capabilities
Reader	View content only
Contributor	Create and edit own content
Content Manager	Manage all content
Workspace Manager	Full workspace control

Content Types

Documents

Upload and manage files:

1. Navigate to workspace
2. Click Upload
3. Select files to upload
4. Documents support versioning and comments

Pages

Create rich text content:

1. Click New > Page
2. Use the WYSIWYG editor
3. Save and share with team

Threads

Start discussions:

1. Click New > Thread
2. Enter title and initial message
3. Team members can reply and react

Folders

Organize content:

1. Click New > Folder
2. Move content into folders
3. Set folder-specific permissions

Collaboration Features

Comments and Discussions

Collaborate on content:

• Comment on any content item
• Use @mentions to notify team members
• Track conversation history

Version History

Access previous versions:

1. Open a document
2. Click Versions
3. View or restore previous versions

Activity Timeline

Track workspace activity:

• See recent changes
• Filter by user or content type
• Export activity reports

WebDAV Access

Enabling WebDAV

Access files through WebDAV protocol:

1. Get your WebDAV URL: https://your-tracim.klutch.sh/webdav
2. Use your Tracim credentials
3. Connect from file managers or applications

Mapping Network Drive

Windows:

1. Open File Explorer
2. Right-click This PC
3. Select Map network drive
4. Enter WebDAV URL

macOS:

1. Finder > Go > Connect to Server
2. Enter WebDAV URL
3. Authenticate with Tracim credentials

Email Integration

Notification Settings

Configure email notifications:

TRACIM_EMAIL__NOTIFICATION__ACTIVATED=true
TRACIM_EMAIL__NOTIFICATION__SMTP__SERVER=smtp.example.com
TRACIM_EMAIL__NOTIFICATION__SMTP__PORT=587
TRACIM_EMAIL__NOTIFICATION__SMTP__USER=your-user
TRACIM_EMAIL__NOTIFICATION__SMTP__PASSWORD=your-password

Email Replies

Enable replying to notifications:

1. Configure inbound email processing
2. Users can reply to notifications to add comments

LDAP/SSO Integration

LDAP Configuration

Connect to existing directory:

TRACIM_LDAP__URL=ldap://ldap.example.com
TRACIM_LDAP__BASE_DN=ou=users,dc=example,dc=com
TRACIM_LDAP__BIND_DN=cn=admin,dc=example,dc=com
TRACIM_LDAP__BIND_PASSWORD=secret

SAML SSO

Configure SAML authentication for enterprise deployments.

API Integration

REST API

Tracim provides a comprehensive REST API:

# Get workspaces
curl -H "Authorization: Bearer TOKEN" \
  https://your-tracim.klutch.sh/api/users/me/workspaces

# Create content
curl -X POST -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "html-document", "label": "My Page"}' \
  https://your-tracim.klutch.sh/api/workspaces/1/contents

Performance Tuning

Resource Recommendations

Users	RAM	CPU
1-20	2 GB	1 vCPU
20-100	4 GB	2 vCPU
100+	8 GB	4 vCPU

Storage Optimization

• Archive old workspaces
• Set document retention policies
• Monitor storage usage

Troubleshooting Common Issues

Cannot Upload Files

Symptoms: Upload fails or times out.

Solutions:

• Check volume has available space
• Verify file size limits
• Check network timeout settings

Slow Performance

Symptoms: Pages load slowly.

Solutions:

• Increase memory allocation
• Optimize PostgreSQL
• Review active user count

Email Notifications Not Sending

Symptoms: Users don’t receive notifications.

Solutions:

• Verify SMTP configuration
• Check email logs
• Test SMTP connection

Additional Resources

• Official Tracim Website
• Tracim GitHub Repository
• Tracim Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Tracim on Klutch.sh provides a powerful, self-hosted collaboration platform for teams who value data ownership and flexibility. The workspace-centric approach helps teams organize information effectively while enabling seamless collaboration on documents, discussions, and shared content.

With features like WebDAV access, LDAP integration, and comprehensive API support, Tracim integrates well with existing workflows and tools. Deployed on Klutch.sh with persistent storage, your team’s collaboration data remains secure and accessible while the reliable infrastructure ensures always-on availability.

Whether you’re a small team looking for document collaboration or an organization needing structured workspaces with role-based access, Tracim delivers the features to support effective teamwork.