Serve Twake-on-Matrix as a Container

Docker images are published on Docker Hub:

Configuration

Applications can be configured via:

Environment variables (recommended for containers)
JSON config file specified by environment variable
Default config file at config.json in project root

Config File Environment Variables

Variable	Description
`TWAKE_SERVER_CONF`	Path to TOM Server config JSON
`TWAKE_IDENTITY_SERVER_CONF`	Path to Matrix Identity Server config JSON
`TWAKE_FEDERATED_IDENTITY_SERVICE_CONF`	Path to Federated Identity Service config JSON

Environment Variables

Status	Description
required	Server cannot start without
recommended	Server can start without, but advised to use
optional	Use to enable specific features

Core Server

Name	Description	Default	Status
`BASE_URL`	Public URL (e.g., `https://tom.example.com`)	-	required
`SERVER_NAME`	Matrix server name (same as homeserver.yaml)	localhost	required
`TRUSTED_PROXIES`	Space-separated IPs allowed to set `X-Forwarded-For`	-	optional
`TRUST_X_FORWARDED_FOR`	Trust X-Forwarded-For header	false	optional

Database

Name	Description	Default	Status
`DATABASE_ENGINE`	Database type (`pg` or `sqlite`)	-	required
`DATABASE_HOST`	`pg`: hostname, `sqlite`: path to .db file	-	required
`DATABASE_NAME`	Database name (pg only)	-	required for pg
`DATABASE_USER`	Database username (pg only)	-	required for pg
`DATABASE_PASSWORD`	Database password (pg only)	-	required for pg
`DATABASE_SSL`	SSL config as JSON (pg only)	false	optional
`DATABASE_VACUUM_DELAY`	Vacuum delay in seconds	3600	optional

User Database

Name	Description	Default	Status
`USERDB_ENGINE`	User database engine (`ldap` or `sqlite`)	ldap	optional
`USERDB_HOST`	User DB host or path	./users.db	optional
`USERDB_NAME`	User DB name	-	optional
`USERDB_USER`	User DB username	-	optional
`USERDB_PASSWORD`	User DB password	-	optional
`USERDB_SSL`	User DB SSL config as JSON	false	optional

LDAP

Name	Description	Default	Status
`LDAP_URI`	LDAP server URI (e.g., `ldaps://ldap.company.com`)	-	recommended
`LDAP_BASE`	Base DN (e.g., `dc=example,dc=com`)	-	recommended
`LDAP_USER`	Full LDAP DN for binding	-	recommended
`LDAP_PASSWORD`	LDAP bind password	-	recommended
`LDAP_FILTER`	Search filter	(objectClass=inetOrgPerson)	recommended
`LDAP_UID_FIELD`	Field for user ID	uid	optional

Matrix

Name	Description	Default	Status
`MATRIX_SERVER`	Matrix homeserver URL	localhost	required
`MATRIX_INTERNAL_HOST`	Internal Matrix host for backend calls	MATRIX_SERVER	optional
`MATRIX_ADMIN_LOGIN`	Matrix admin username	admin	optional
`MATRIX_ADMIN_PASSWORD`	Matrix admin password	change-me	optional
`ADMIN_ACCESS_TOKEN`	Admin API access token	secret	optional
`MATRIX_DATABASE_ENGINE`	Matrix DB type (`pg` or `sqlite`)	-	optional
`MATRIX_DATABASE_HOST`	Matrix DB host or path	-	optional
`MATRIX_DATABASE_NAME`	Matrix DB name (pg only)	-	optional
`MATRIX_DATABASE_USER`	Matrix DB username (pg only)	-	optional
`MATRIX_DATABASE_PASSWORD`	Matrix DB password (pg only)	-	optional
`MATRIX_DATABASE_SSL`	Matrix DB SSL config (pg only)	false	optional

OIDC

Name	Description	Default	Status
`OIDC_ISSUER`	OpenID Connect issuer URL	-	required

SMTP

Name	Description	Default	Status
`SMTP_SERVER`	SMTP server host	localhost	optional
`SMTP_PORT`	SMTP server port	25	optional
`SMTP_USER`	SMTP username	-	optional
`SMTP_PASSWORD`	SMTP password	-	optional
`SMTP_SENDER`	From email address	-	optional
`SMTP_TLS`	Enable SMTP TLS	false	optional
`SMTP_VERIFY_CERTIFICATE`	Verify SMTP certificate	false	optional

SMS

Name	Description	Default	Status
`SMS_API_URL`	SMS API endpoint	-	optional
`SMS_API_LOGIN`	SMS API login	-	optional
`SMS_API_KEY`	SMS API key	-	optional

Jitsi

Name	Description	Default	Status
`JITSI_BASE_URL`	Jitsi instance URL	-	optional
`JITSI_JWT_ALGORITHM`	JWT signing algorithm	HS256	optional
`JITSI_JWT_ISSUER`	JWT issuer identifier	-	optional
`JITSI_SECRET`	Jitsi JWT secret	-	optional
`JITSI_PREFERRED_DOMAIN`	Preferred Jitsi domain	-	optional
`JITSI_USE_JWT`	Enable JWT authentication	false	optional

Crowdsec

Name	Description	Default	Status
`CROWDSEC_URI`	Crowdsec API URI	-	optional
`CROWDSEC_KEY`	Crowdsec authentication key	-	optional

Cache

Name	Description	Default	Status
`CACHE_ENGINE`	Cache engine type (e.g., redis)	-	optional
`REDIS_URI`	Redis connection URI	-	optional

Rate Limiting

Name	Description	Default	Status
`RATE_LIMITING_WINDOW`	Window duration in milliseconds	600000	recommended
`RATE_LIMITING_NB_REQUESTS`	Max requests per window	100	recommended
`HASHES_RATE_LIMIT`	Hash lookup rate limit	100	optional

Cron Jobs

Name	Description	Default	Status
`CRON_SERVICE`	Enable cron tasks	false	optional
`PEPPER_CRON`	Pepper update schedule (cron syntax)	9 1 * * *	optional
`UPDATE_USERS_CRON`	User data refresh schedule	_/10 _ * * *	optional
`UPDATE_FEDERATED_IDENTITY_HASHES_CRON`	Federated hash update schedule	_/10 _ * * *	optional

Federated Identity

Name	Description	Default	Status
`FEDERATED_IDENTITY_SERVICES`	Comma/space-separated list of federation servers	-	recommended
`TRUSTED_SERVERS_ADDRESSES`	Trusted server IP addresses/networks	-	optional

Feature Flags

Name	Description	Default	Status
`ADDITIONAL_FEATURES`	Enable all search features	false	recommended
`FEATURE_COMMON_SETTINGS_ENABLED`	Enable common settings service	false	optional
`FEATURE_USER_PROFILE_DEFAULT_VISIBILITY`	Default profile visibility	private	optional
`FEATURE_USER_DIRECTORY_ENABLED`	Enable user directory search	false	optional
`FEATURE_MATRIX_PROFILE_UPDATES_ALLOWED`	Allow Matrix profile updates	false	optional

Twake Chat Client

Name	Description	Default	Status
`TCHAT_ENABLE_INVITATIONS`	Enable email invitations	false	optional
`TCHAT_APPLICATION_NAME`	Application display name	-	optional
`TCHAT_APPLICATION_WELCOME_MESSAGE`	Welcome message	-	optional
`TCHAT_PRIVACY_URL`	Privacy policy URL	-	optional
`TCHAT_REGISTRATION_URL`	User registration URL	-	optional
`TCHAT_SUPPORT_URL`	Support page URL	-	optional
`TCHAT_SUPPORT_CONTACT`	Support contact info	-	optional
`TCHAT_QR_CODE_DOWNLOAD_URL`	QR code app download URL	-	optional
`TCHAT_DEV_MODE`	Enable development mode	false	optional
`TCHAT_ENABLE_LOGS`	Enable client-side logging	false	optional
`TCHAT_MAX_UPLOAD_AVATAR_SIZE`	Max avatar upload size (bytes)	-	optional
`TCHAT_RENDER_HTML`	Render HTML in messages	false	optional
`TCHAT_HIDE_REDACTED_EVENTS`	Hide deleted messages	false	optional
`TCHAT_HIDE_UNKNOWN_EVENTS`	Hide unknown event types	false	optional
`TCHAT_APP_GRID_DASHBOARD_AVAILABLE`	Enable app grid dashboard	false	optional
`TCHAT_TWAKE_WORKPLACE_HOMESERVER`	Twake workplace homeserver	-	optional
`TCHAT_PLATFORM`	Platform identifier	-	optional

URLs

Name	Description	Default	Status
`QRCODE_URL`	QR code login URL scheme	twake.chat://login	optional
`CHAT_URL`	Chat application URL	https://chat.twake.app	optional
`AUTH_URL`	Authentication service URL	-	optional
`SIGNUP_URL`	User signup URL	https://sign-up.twake.app/?app=chat	optional
`SENDER_LOCALPART`	Matrix sender localpart	twake	optional

Timing & Security

Name	Description	Default	Status
`KEY_DELAY`	Key rotation delay (seconds)	3600	optional
`KEYS_DEPTH`	Number of keys to maintain	5	optional
`MAIL_LINK_DELAY`	Email verification link validity (seconds)	7200	optional

Logging

Name	Description	Default	Status
`LOG_TRANSPORTS`	Log output destinations	Console	optional
`LOG_LEVEL`	Log level (error, warn, info, http, verbose, debug, silly)	info	optional

Templates

Name	Description	Default	Status
`TEMPLATE_DIR`	Path to email templates folder	node_modules/@twake/server/templates	recommended

Running with Docker

Example deployment with PostgreSQL database, LDAP directory, and Matrix integration:

docker run -d -p 3000:3000 \
    -e BASE_URL=https://tom.example.com/ \
    -e SERVER_NAME=example.com \
    -e OIDC_ISSUER=https://auth.example.com/ \
    -e DATABASE_ENGINE=pg \
    -e DATABASE_HOST=pg-host.xyz \
    -e DATABASE_NAME=twake \
    -e DATABASE_USER=twake \
    -e DATABASE_PASSWORD=mydbpassword \
    -e DATABASE_SSL=true \
    -e LDAP_URI=ldap://ldap.example.com \
    -e LDAP_BASE=dc=example,dc=com \
    -e LDAP_FILTER="(objectClass=inetOrgPerson)" \
    -e MATRIX_SERVER=matrix.example.com \
    -e MATRIX_DATABASE_ENGINE=pg \
    -e MATRIX_DATABASE_HOST=synapse-db \
    -e MATRIX_DATABASE_NAME=synapse \
    -e MATRIX_DATABASE_USER=synapse \
    -e MATRIX_DATABASE_PASSWORD=synapse_password \
    -e ADDITIONAL_FEATURES=true \
    -e CRON_SERVICE=true \
    linagora/tom-server

Docker Compose

Development environments are provided in .compose/examples/:

pgsql.yml - PostgreSQL with persistent storage
sqlite.yml - SQLite for quick testing
sso.yml - SSO with LemonLDAP::NG (HTTPS)

Architecture

All environments include:

Service	Description	Port
Traefik	Reverse proxy and routing	80, 8080 (dashboard)
ToM Server	Twake-on-Matrix identity server	3000
Synapse	Matrix homeserver	8008
OpenLDAP	User directory	389
SMTP	Development email server (Papercut)	2525
Federated Identity	Federation service	3000

PostgreSQL variant additionally includes:

PostgreSQL database for ToM and Synapse

SSO variant additionally includes:

LemonLDAP::NG SSO service for OIDC authentication
Latest Twake Chat client

Prerequisites

`/etc/hosts`

Add these entries to your hosts file:

127.0.0.1 docker.internal
127.0.0.1 matrix.docker.internal
127.0.0.1 tom.docker.internal
127.0.0.1 fed.docker.internal
127.0.0.1 auth.docker.internal
127.0.0.1 chat.docker.internal

Running the Environments

PostgreSQL (Recommended)

# Start all services
docker compose -f .compose/examples/pgsql.yml up -d

# Rebuild after code changes
docker compose -f .compose/examples/pgsql.yml up -d --build

SQLite (Lightweight)

# Start all services
docker compose -f .compose/examples/sqlite.yml up -d

# Rebuild after code changes
docker compose -f .compose/examples/sqlite.yml up -d --build

Accessing Services

Service	URL
ToM Server API	http://tom.docker.internal
Matrix Homeserver	http://matrix.docker.internal
Federation Service	http://fed.docker.internal
Traefik Dashboard	http://localhost:8080

Test Users

Name	Username	Password
Doctor Who	dwho	dwho
Rose Tyler	rtyler	rtyler

See .compose/ldap/README.md for the full list of 60+ test users.

Sending Invitations

With TCHAT_ENABLE_INVITATIONS=true, ToM can send email invitations:

curl -X POST 'https://tom.example.com/_twake/v1/invite' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"contact":"invitee@example.com","medium":"email"}'

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Serve Twake-on-Matrix as a Container

Configuration

Config File Environment Variables

Environment Variables

Core Server

Database

User Database

LDAP

Matrix

OIDC

SMTP

SMS

Jitsi

Crowdsec

Cache

Rate Limiting

Cron Jobs

Federated Identity

Feature Flags

Twake Chat Client

URLs

Timing & Security

Logging

Templates

Running with Docker

Docker Compose

Architecture

Prerequisites

`/etc/hosts`

Running the Environments

PostgreSQL (Recommended)

SQLite (Lightweight)

Accessing Services

Test Users

Sending Invitations

FilesExpand file tree

docker.md

Latest commit

History

docker.md

File metadata and controls

Serve Twake-on-Matrix as a Container

Configuration

Config File Environment Variables

Environment Variables

Core Server

Database

User Database

LDAP

Matrix

OIDC

SMTP

SMS

Jitsi

Crowdsec

Cache

Rate Limiting

Cron Jobs

Federated Identity

Feature Flags

Twake Chat Client

URLs

Timing & Security

Logging

Templates

Running with Docker

Docker Compose

Architecture

Prerequisites

/etc/hosts

Running the Environments

PostgreSQL (Recommended)

SQLite (Lightweight)

Accessing Services

Test Users

Sending Invitations

`/etc/hosts`