Running a server

This guide is for system administrators who install and run an Antimatter server. It assumes you know Linux, Docker and reverse proxies, but not Antimatter.

What makes up a deployment

Antimatter is a self-hosted team chat, a fork of Mattermost. A complete deployment has these parts. Only the first three are required.

Part	What it does	Required
The Antimatter server	One Go program (`antimatter`) that serves the web app, the API and the websockets on port 8065, runs the bundled apps (plugins), and carries call media on port 8443. The command-line tool `amctl` manages it.	yes
PostgreSQL	The database: messages, users, communities and, in the recommended setup, the server's configuration. Version 15 or newer.	yes
File storage	Uploaded files, images and installed apps: an S3-compatible service (the compose file runs RustFS), or a local directory.	yes
A reverse proxy	HTTPS in front of the server: the compose file's Caddy profile, or your own nginx.	for production
The GIF service (`gifs-server`)	GIFs and stickers for the GIF picker, from your own catalogue. It speaks the Tenor API.	no
A push proxy	Forwards notifications to the mobile app through Apple and Google.	for mobile notifications
rtcd, a TURN server	A separate media server for many calls, and a relay for people behind strict firewalls.	no
AI endpoints	The models behind the composer's rewrite, recaps, translation, read-aloud, AI agents and call transcription, added as model connections: a cloud provider or servers you run.	no

Antimatter has no licence and no paid edition: single sign-on, LDAP, high availability, compliance exports, data retention and the other features Mattermost reserves for its paid plans are all included.

Requirements

A Linux server, amd64 or arm64, with 2 CPU cores and 4 GB of memory or more for a few hundred people, and disk space for the files people upload.
Docker Engine with the Compose plugin (docker compose), for the recommended installation. Or, for the packages, a Debian, Ubuntu, Fedora or RHEL-compatible server with systemd.
For production: a domain name pointing at the server, and ports 80 and 443 open for HTTPS.
For calls: port 8443, UDP and TCP, reachable by the people who call.
For email: an SMTP server Antimatter can send through.

Quick start

mkdir antimatter && cd antimatter
curl -fsSLO https://antimatter.chat/compose.yaml
cat > .env <<EOF
SITE_URL=http://localhost:8065
POSTGRES_PASSWORD=$(openssl rand -hex 24)
S3_SECRET_KEY=$(openssl rand -hex 24)
GIFS_API_KEY=$(openssl rand -hex 24)
AM_AI_ENCRYPTION_KEY=$(openssl rand -base64 32)
EOF
docker compose up -d

Then open the site URL and create your account: the first account becomes the system administrator. Installing explains each step and the other ways to install.

In this guide

Installing: Docker Compose, the images, the first administrator, the .deb and .rpm packages, the release archive.
Configuration: settings in the database or a file, AM_ environment variables, the System Console, amctl, logs.
Domain and HTTPS: the site URL, Caddy, nginx, client addresses.
Calls and voice: ports, NAT, TURN, rtcd, transcription and captions.
Email and push: SMTP, the push proxy and the mobile app.
Bundled apps: which apps are on, their settings, installing others.
AI: model connections, the built-in AI features, agents, speech and translation, the encryption key, and what data goes where.
Sign-in and accounts: sign-up, passwords, MFA, single sign-on, LDAP, guests, sessions.
Backups and upgrades: backup, restore, upgrade, moving from Mattermost.
Operations: monitoring, scaling, data retention, compliance, troubleshooting.
Security: hardening checklist and outside connections.
Desktop app deployment: the MSI, Group Policy and Intune, macOS profiles and the Linux policy file.

Running a community rather than a server (channels, roles, moderation)? See Running a community. Building integrations? See Building on Antimatter.

Your first hour

Install, and create the administrator account right away.
Put the server behind HTTPS on its own domain.
Configure SMTP and send a test email.
Open the calls port. For a company, set the kind of new communities to Workspace, so that calls are on in channels.
Decide who can sign up, and turn on MFA.
Review the outside connections in Security.
Set up daily backups. Before adding AI model connections, set the AI encryption key.

Getting help

Ask questions in the community discussions, and report bugs in the community repository. Report security problems privately, as the security policy explains.