Tinode

Instant messaging platform, an open-source alternative to WhatsApp or Telegram

Alternative to: WhatsApp, Telegram, Facebook Messenger

Tinode is a federated instant messaging platform designed as a modern replacement for XMPP. It supports one-to-one and group messaging, voice and video calls, and chatbots, with native clients for Android, iOS, and the web, plus a Go backend that can run against MySQL, PostgreSQL, MongoDB, or RethinkDB.

Tinode Docker Compose example

Self-host Tinode on your own server, homelab, or VPS starting from this Docker Compose example. It runs Tinode in Docker containers using the official mysql:8, tinode/tinode:latest images, with persistent volumes and automatic restarts preconfigured. Review the environment variables and adjust them to your setup, save the file as compose.yml (or docker-compose.yml), and start the stack with docker compose up -d.

services:
  mysql:
    image: mysql:8
    environment:
      # The database is reachable only inside the compose network — no password on root.
      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 5s
      retries: 10
    volumes:
      - db_data:/var/lib/mysql
    restart: unless-stopped

  tinode:
    image: tinode/tinode:latest
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      # Storage backend selector — the tinode:latest image is built with the mysql adapter.
      STORE_USE_ADAPTER: "mysql"
      # Wait for the mysql service before starting the server.
      WAIT_FOR: "mysql:3306"
      # Salt used to derive the client API key — REGENERATE FOR PRODUCTION (32 random bytes, base64).
      API_KEY_SALT: "T713/rYYgW7g4m3vG6zGRh7+FM1t0T8j13koXScOAj4="
      # Key used to sign authentication tokens — REGENERATE FOR PRODUCTION (32 random bytes, base64).
      AUTH_TOKEN_KEY: "wfaY2RgF2S1OQI/ZlK+LSrp1KB2jwAdGAIHQ7JZn+Kc="
      # Key used to initialize the user-ID generator — REGENERATE FOR PRODUCTION (16 random bytes, base64).
      UID_ENCRYPTION_KEY: "la6YsO+bNX/+XIkOqc5Svw=="
      # Default country code for phone-number formatting.
      DEFAULT_COUNTRY_CODE: "US"
      # Google Firebase Cloud Messaging push notifications for mobile clients.
      FCM_PUSH_ENABLED: "false"
      # Tinode Push Gateway (SaaS) push notifications.
      TNPG_PUSH_ENABLED: "false"
      # WebRTC voice/video calls.
      WEBRTC_ENABLED: "false"
      # SMTP server used to send email address verification codes at signup — leave empty to skip.
      SMTP_SERVER: ""
      SMTP_PORT: ""
      SMTP_SENDER: ""
      SMTP_LOGIN: ""
      SMTP_PASSWORD: ""
      # Reset the database on startup (destroys all data). Leave "false" outside first-time recovery.
      RESET_DB: "false"
      # Upgrade the database schema on startup after a Tinode version bump.
      UPGRADE_DB: "false"
    restart: unless-stopped

volumes:
  db_data:

Prefer a managed setup? WinterFlow installs, configures, and updates Tinode for you using this same Docker Compose configuration.