Deploying Tinode

Introduction

Tinode is a modern, open-source instant messaging server designed for building chat applications. Written in Go, Tinode provides high-performance, scalable messaging infrastructure with support for real-time communications, push notifications, and rich media sharing. It comes with ready-to-use clients for web, Android, and iOS.

Key features of Tinode include:

• Real-Time Messaging: Instant message delivery via WebSocket
• One-on-One Chats: Private conversations between users
• Group Chats: Multi-user chat rooms with admin controls
• Push Notifications: FCM, APNS, and web push support
• Message Synchronization: Sync across multiple devices
• Read Receipts: Message delivery and read status
• Typing Indicators: Real-time typing notifications
• File Sharing: Images, videos, and document attachments
• User Presence: Online/offline status tracking
• End-to-End Encryption: Optional E2EE support
• Clustering: Horizontal scaling support
• REST and gRPC APIs: Multiple integration options

This guide walks you through deploying Tinode on Klutch.sh, configuring the database, and connecting chat clients.

Why Deploy Tinode on Klutch.sh

Deploying Tinode on Klutch.sh provides several advantages:

Always-On Chat: Instant messaging requires constant availability. Klutch.sh ensures your server remains accessible 24/7.

Simplified Deployment: Klutch.sh handles container orchestration, letting you focus on building your chat application.

Scalable Infrastructure: Scale resources as your user base grows.

Persistent Storage: Messages and user data persist reliably.

HTTPS by Default: Secure WebSocket connections with automatic SSL.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• MySQL, PostgreSQL, or MongoDB database (can be deployed on Klutch.sh)
• Basic familiarity with Docker and messaging concepts
• (Optional) Firebase credentials for push notifications

Understanding Tinode Architecture

Tinode uses a topic-based messaging model:

• Users: Individual accounts with profiles
• Topics: Conversation channels (p2p or group)
• Subscriptions: User-topic relationships
• Messages: Content sent to topics

Preparing Your Repository

Create a GitHub repository with the following structure:

tinode-deploy/
├── Dockerfile
├── .dockerignore
└── tinode.conf

Creating the Dockerfile

FROM tinode/tinode-server:latest

# Copy custom configuration
COPY tinode.conf /opt/tinode/tinode.conf

# Environment variables
ENV EXT_CONFIG=/opt/tinode/tinode.conf
ENV STORE_USE_ADAPTER=${STORE_USE_ADAPTER:-mysql}
ENV MYSQL_DSN=${MYSQL_DSN}
ENV POSTGRES_DSN=${POSTGRES_DSN}

# Push notifications (optional)
ENV FCM_CRED_FILE=${FCM_CRED_FILE}
ENV FCM_ENABLED=${FCM_ENABLED:-false}

# TLS configuration
ENV TLS_ENABLED=${TLS_ENABLED:-false}

# Expose ports
EXPOSE 6060 16060

# The base image includes the default entrypoint

Configuration File

Create tinode.conf:

{
    "listen": ":6060",
    "grpc_listen": ":16060",
    "api_path": "/",
    "cache_control": 39600,
    "static_mount": "/",
    "static_data": "static",

    "tls": {
        "enabled": false,
        "http_redirect": "",
        "strict_max_age": 604800,
        "autocert": {
            "cache": "/etc/letsencrypt/live",
            "email": "",
            "domains": []
        }
    },

    "auth_config": {
        "logical_names": [],
        "basic": {
            "add_to_tags": true,
            "min_login_length": 4,
            "min_password_length": 6
        },
        "token": {
            "expire_in": 1209600,
            "serial_num": 1,
            "key": "your-secret-key-here"
        }
    },

    "store_config": {
        "use_adapter": "mysql",
        "uid_key": "your-uid-key-here",
        "adapters": {
            "mysql": {
                "database": "tinode",
                "dsn": "tinode:password@tcp(mysql:3306)/tinode?parseTime=true"
            }
        }
    },

    "push": [],

    "plugins": []
}

Environment Variables Reference

Variable	Required	Default	Description
STORE_USE_ADAPTER	No	mysql	Database adapter (mysql, postgres, mongodb)
MYSQL_DSN	Conditional	-	MySQL connection string
POSTGRES_DSN	Conditional	-	PostgreSQL connection string
FCM_CRED_FILE	No	-	Firebase credentials file path
FCM_ENABLED	No	false	Enable Firebase push notifications

Deploying on Klutch.sh

Set Up Database

Tinode supports MySQL, PostgreSQL, or MongoDB. Deploy your chosen database on Klutch.sh:

Mount Path	Size	Purpose
/var/lib/mysql	20 GB	Database storage

Create the Tinode database and user.

Configure Push Notifications (Optional)

For mobile push notifications:

1. Create Firebase project
2. Download service account JSON
3. Note credentials for configuration

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “tinode” or “chat-server”.

Create the Tinode App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set the traffic type to HTTP with the internal port set to 6060.

Set Environment Variables

Configure the database connection:

Variable	Value
STORE_USE_ADAPTER	mysql
MYSQL_DSN	user:pass@tcp(host:3306)/tinode?parseTime=true

Attach Persistent Volumes

Add persistent storage:

Mount Path	Size	Purpose
/opt/tinode/uploads	20 GB	File uploads
/opt/tinode/logs	2 GB	Server logs

Deploy Your Application

Click Deploy to build and launch Tinode.

Initialize Database Schema

Run the database initialization on first deployment.

Initial Configuration

Creating the Root User

Initialize the admin account:

1. Access the Tinode server
2. Create the root user through API or CLI
3. Set a strong password

Configuring Authentication

Tinode supports multiple auth methods:

• Basic Auth: Username/password authentication
• Token Auth: JWT-based session tokens
• Anonymous: Guest access (optional)

Setting Up Push Notifications

Configure Firebase Cloud Messaging:

1. Add Firebase credentials
2. Enable push in configuration
3. Configure per-platform settings

Client Integration

Web Client

Tinode provides a React-based web client:

1. Clone the tinodejs repository
2. Configure server endpoint
3. Deploy the static files

Android Client

Connect the Android app:

1. Clone the tindroid repository
2. Update server configuration
3. Build and deploy

iOS Client

Set up the iOS client:

1. Clone the ios repository
2. Configure server settings
3. Build in Xcode

Custom Integration

Use the Tinode SDK:

// JavaScript example
import { Tinode } from 'tinode-sdk';

const tinode = new Tinode({
    host: 'your-tinode-server.klutch.sh',
    transport: 'wss',
    secure: true
});

// Connect to server
tinode.connect()
    .then(() => {
        // Login
        return tinode.loginBasic('username', 'password');
    })
    .then((ctrl) => {
        console.log('Logged in:', ctrl.params.user);
    });

Chat Features

One-on-One Messaging

Private conversations between users:

1. Find user by username or ID
2. Create p2p topic
3. Send messages

Group Chats

Multi-user conversations:

1. Create group topic
2. Set group name and description
3. Invite members
4. Manage permissions

Message Types

Tinode supports various message formats:

Type	Description
Plain text	Simple text messages
Drafty	Rich text with formatting
Images	Photo attachments
Files	Document sharing
Locations	Geographic coordinates

Presence and Typing

Real-time status features:

• Online/offline status
• Last seen timestamp
• Typing indicators
• Read receipts

Production Best Practices

Security Recommendations

• Strong Token Keys: Use cryptographically secure keys
• Password Policies: Enforce minimum password strength
• TLS Everywhere: Use HTTPS/WSS connections
• Rate Limiting: Implement request rate limits
• Input Validation: Sanitize user input

Performance Optimization

• Connection Pooling: Optimize database connections
• Message Caching: Configure appropriate cache settings
• Clustering: Use multiple nodes for high availability
• Load Balancing: Distribute WebSocket connections

Backup Strategy

Protect your chat data:

1. Regular database backups
2. Back up uploaded files
3. Export user data
4. Document configuration

Troubleshooting

Connection Issues

• Verify WebSocket endpoint URL
• Check SSL/TLS configuration
• Review firewall rules
• Test with WebSocket client

Authentication Failures

• Check token expiration
• Verify credentials
• Review auth configuration
• Check database connectivity

Messages Not Delivering

• Verify topic subscriptions
• Check user permissions
• Review server logs
• Test with different clients

Push Notifications Not Working

• Verify Firebase credentials
• Check FCM configuration
• Test notification delivery
• Review push logs

Additional Resources

• Tinode Documentation
• Tinode GitHub Repository
• Tinode Android Client
• Tinode Web Client
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Tinode on Klutch.sh provides a solid foundation for building real-time chat applications. With support for one-on-one and group messaging, push notifications, and rich media, Tinode offers everything needed for modern instant messaging. The combination of Tinode’s feature-rich platform and Klutch.sh’s reliable infrastructure ensures your chat service remains fast, secure, and always available.