Deploying traQ

Introduction

traQ is a self-hosted team communication platform developed at the Tokyo Institute of Technology. Designed for modern team collaboration, traQ provides real-time messaging, file sharing, and rich customization options while keeping all your data under your control.

Built with Go for the backend and Vue.js for the frontend, traQ offers a polished user experience comparable to commercial chat solutions. It supports channels, direct messages, file attachments, markdown formatting, and integration with external services through webhooks and bots.

Key highlights of traQ:

• Real-Time Messaging: WebSocket-based instant message delivery
• Channel Organization: Create public and private channels for different topics and teams
• Direct Messages: Private one-on-one and group conversations
• File Sharing: Upload and share files, images, and documents
• Markdown Support: Rich text formatting with markdown syntax
• Custom Stamps: Create and use custom emoji-like stamps for reactions
• User Groups: Organize users into groups for mentions and permissions
• Webhook Integration: Connect with external services and automation
• Bot Support: Build custom bots using the comprehensive API
• Mobile Friendly: Responsive design works on phones and tablets
• SSO Support: OAuth2 integration for enterprise authentication
• Open Source: Licensed under MIT for full transparency

This guide walks through deploying traQ on Klutch.sh using Docker, setting up persistent storage, and configuring the platform for team collaboration.

Why Deploy traQ on Klutch.sh

Deploying traQ on Klutch.sh provides several advantages for team communication:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds traQ without complex orchestration. Push to GitHub, and your chat platform deploys automatically.

Persistent Storage: Attach persistent volumes for your messages, files, and user data. Your communication history survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure communication and WebSocket connections.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Environment Variable Management: Securely store sensitive configuration like database credentials and secret keys through Klutch.sh’s environment variable system.

Always-On Availability: Your team’s communication hub remains accessible 24/7 from anywhere in the world.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your traQ configuration
• Basic familiarity with Docker and containerization concepts
• A MariaDB or MySQL database (can be deployed separately on Klutch.sh)
• (Optional) A custom domain for your traQ instance

Understanding traQ Architecture

traQ is built on a modern stack designed for real-time communication:

Go Backend: The core server handles REST API requests, WebSocket connections, and business logic.

Vue.js Frontend: A modern single-page application providing the user interface.

MariaDB/MySQL Database: Stores users, channels, messages, and all application data.

WebSocket Server: Provides real-time message delivery and presence updates.

File Storage: Local or S3-compatible object storage for file uploads.

Preparing Your Repository

To deploy traQ on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

traq-deploy/
├── Dockerfile
├── config.yaml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM traq/traq:latest

# Set environment variables
ENV TRAQ_ORIGIN=${ORIGIN}
ENV TRAQ_MARIADB_HOST=${MARIADB_HOST}
ENV TRAQ_MARIADB_PORT=${MARIADB_PORT:-3306}
ENV TRAQ_MARIADB_USERNAME=${MARIADB_USERNAME}
ENV TRAQ_MARIADB_PASSWORD=${MARIADB_PASSWORD}
ENV TRAQ_MARIADB_DATABASE=${MARIADB_DATABASE}

# Create directories
RUN mkdir -p /app/storage

# Copy configuration
COPY config.yaml /app/config.yaml

# 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/api/v3/ping || exit 1

Configuration File

Create config.yaml for your traQ configuration:

# Server configuration
origin: ${ORIGIN}
port: 3000

# Database configuration
mariadb:
  host: ${MARIADB_HOST}
  port: ${MARIADB_PORT}
  username: ${MARIADB_USERNAME}
  password: ${MARIADB_PASSWORD}
  database: ${MARIADB_DATABASE}

# Storage configuration
storage:
  type: local
  local:
    dir: /app/storage

# Session configuration
session:
  secret: ${SESSION_SECRET}

# OAuth2 configuration (optional)
oauth2:
  enabled: false

Environment Variables Reference

Variable	Required	Default	Description
ORIGIN	Yes	-	Public URL of your traQ instance (e.g., https://chat.example.com)
MARIADB_HOST	Yes	-	MariaDB/MySQL server hostname
MARIADB_PORT	No	3306	MariaDB/MySQL server port
MARIADB_USERNAME	Yes	-	Database username
MARIADB_PASSWORD	Yes	-	Database password
MARIADB_DATABASE	Yes	-	Database name
SESSION_SECRET	Yes	-	Secret key for session encryption

Deploying traQ on Klutch.sh

Once your repository is prepared, follow these steps to deploy traQ:

Set Up a Database

traQ requires a MariaDB or MySQL database. You can deploy one on Klutch.sh or use a managed database service. Create a database named traq with appropriate credentials.

Generate Your SESSION_SECRET

Generate a secure secret key for session encryption:

openssl rand -hex 32

Save this key securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.yaml .dockerignore
git commit -m "Initial traQ deployment configuration"
git remote add origin https://github.com/yourusername/traq-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. Give it a descriptive name like “traq” or “team-chat”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your traQ Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000 (traQ default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
ORIGIN	https://your-app-name.klutch.sh
MARIADB_HOST	Your database host
MARIADB_PORT	3306
MARIADB_USERNAME	Your database username
MARIADB_PASSWORD	Your database password
MARIADB_DATABASE	traq
SESSION_SECRET	Your generated secret from step 2

Attach Persistent Volumes

Persistent storage is essential for traQ. Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/storage	10 GB	File uploads and attachments

Deploy Your Application

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

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the traQ container
• Provision an HTTPS certificate

Access traQ

Once deployment completes, access your traQ instance at https://your-app-name.klutch.sh. Create your first admin account on initial access.

Initial Setup and Configuration

Creating the First User

When you first access traQ:

1. Click “Register” to create your account
2. The first registered user automatically becomes an administrator
3. Set up your profile with a display name and avatar

Creating Channels

Organize your team’s communication with channels:

1. Click the ”+” icon in the channel sidebar
2. Choose “Create Channel”
3. Enter a channel name (e.g., #general, #engineering, #random)
4. Set visibility (public or private)
5. Add a description explaining the channel’s purpose

Channel Hierarchy

traQ supports hierarchical channel organization:

• Create parent channels for broad topics
• Add child channels for specific subtopics
• Example: #engineering/frontend, #engineering/backend

Custom Stamps

Create custom reaction stamps:

1. Go to Settings > Stamps
2. Click “Add Stamp”
3. Upload an image (recommended 64x64 pixels)
4. Set a name for the stamp

User Management

Inviting Users

Add team members to your traQ instance:

1. Go to Settings > Users
2. Share the registration URL with new users
3. Or create user accounts directly as an admin

User Groups

Create groups for easy mentions and organization:

1. Navigate to Settings > Groups
2. Create groups like @developers, @designers, @managers
3. Add users to appropriate groups
4. Use @groupname to notify all group members

Permissions

Control access with permission settings:

• Channel-level permissions for read/write access
• Private channels visible only to members
• Admin capabilities for user management

Messaging Features

Message Formatting

traQ supports rich markdown formatting:

• Bold: **text**
• Italic: *text*
• Strikethrough: ~~text~~
• Code: `code`
• Code blocks with syntax highlighting
• Lists and blockquotes
• Links and mentions

File Sharing

Share files with your team:

1. Drag and drop files into the message input
2. Or click the attachment icon
3. Images display inline as previews
4. Other files appear as downloadable links

Mentions and Notifications

Get attention with targeted notifications:

• @username - Notify a specific user
• @group - Notify all group members
• @here - Notify active users in the channel
• Reply to specific messages for context

Bot and Webhook Integration

Creating Bots

Build custom bots using the traQ API:

1. Go to Settings > Bots
2. Click “Create Bot”
3. Configure bot permissions
4. Use the provided token for API access

Webhook Setup

Connect external services with webhooks:

1. Navigate to channel settings
2. Create a new webhook
3. Use the webhook URL to post messages from external systems
4. Common integrations: CI/CD, monitoring, GitHub

SSO Configuration

OAuth2 Setup

Configure enterprise authentication:

1. Register traQ as an OAuth2 client with your IdP
2. Configure callback URLs
3. Add OAuth2 settings to your config.yaml
4. Enable SSO login in settings

Supported Providers

• Generic OAuth2
• OpenID Connect
• Enterprise identity providers

Production Best Practices

Security Recommendations

• Strong Secrets: Use properly generated session secrets
• HTTPS Only: Klutch.sh provides this automatically
• Database Security: Use strong database passwords
• Regular Updates: Keep traQ updated for security patches

Backup Strategy

Protect your team’s communication:

1. Database Backups: Regularly back up your MariaDB database
2. File Storage: Back up the /app/storage directory
3. Configuration: Keep your config.yaml in version control

Performance Optimization

• Database Tuning: Optimize MariaDB for your message volume
• Storage Scaling: Monitor and expand file storage as needed
• Resource Allocation: Scale resources based on active users

Troubleshooting Common Issues

Connection Issues

Symptoms: Cannot connect to traQ or WebSocket disconnects.

Solutions:

• Verify ORIGIN matches your actual deployment URL
• Check database connectivity
• Review container logs for errors

Message Delivery Problems

Symptoms: Messages not appearing in real-time.

Solutions:

• Check WebSocket connection status
• Verify SSL/TLS configuration
• Review network connectivity

Database Errors

Symptoms: Application errors or missing data.

Solutions:

• Verify database credentials
• Check database server connectivity
• Review database logs for issues

Additional Resources

• traQ GitHub Repository
• traQ Wiki
• traQ API Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying traQ on Klutch.sh gives you a powerful, self-hosted team communication platform accessible from anywhere. The combination of traQ’s modern features and Klutch.sh’s deployment simplicity means you can focus on collaboration rather than infrastructure.

With real-time messaging, file sharing, custom stamps, and bot integration, traQ provides everything your team needs for effective communication. Your data remains under your control, your conversations stay private, and your team stays connected 24/7.