Installing Antimatter

Install Antimatter with the ready-made compose file, from the .deb or .rpm package of a release, or from a release archive. Then create the first administrator account.

Install with Docker Compose

This is the recommended way. One compose file runs Antimatter, PostgreSQL, the file storage and the GIF service. You need a Linux server with Docker Engine and its Compose plugin (docker compose), 2 CPU cores and 4 GB of memory or more.

1. Download the compose file

mkdir antimatter && cd antimatter
curl -fsSLO https://antimatter.chat/compose.yaml

2. Create the .env file

The compose file reads its settings from a .env file in the same directory. Create it with random secrets:

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
chmod 600 .env

Set SITE_URL to the address people will type in their browser, for example http://192.168.1.20:8065 on a local network or https://chat.example.com with a domain. Keep the .env file: the database and the storage use these passwords from the first start, the API keys of AI model connections are encrypted with AM_AI_ENCRYPTION_KEY, and you need the same file to restore a backup.

3. Start it

docker compose up -d
docker compose ps

The first start takes a minute or two: PostgreSQL creates the database, a one-shot bucket service creates the storage bucket, a one-shot gifs-stickers service imports the starter sticker pack, and Antimatter creates its tables. Follow it with docker compose logs -f antimatter.

To use a domain name and HTTPS from the start, see Domain and HTTPS: with the compose file it is two more lines in .env and the https profile.

The .env variables

What runs

PostgreSQL, the storage and the GIF service are on an internal network (private) with no Internet access, which only Antimatter joins. None of them publishes a port.

The Antimatter container keeps nothing on disk: its settings are in the database (AM_CONFIG points at it) and its files and apps are in the storage service. You can remove and recreate the container at any time. Its data volume only holds the AI encryption key file, which the server makes when AM_AI_ENCRYPTION_KEY is empty. Everything to back up is in the postgres, files, gifs and data volumes, plus your .env.

Choose an image

Two Antimatter images are published, both for linux/amd64 and linux/arm64, and both built from the main branch of every repository:

Neither image bundles Kanban or Playbooks any more: install either from its own GitHub release (see below) if you want it. A server that already has one installed keeps it across an upgrade.

The site's compose file uses antimatter-next, because the GIF service and most of the apps described on this site are only in that image. To change image, set ANTIMATTER_IMAGE in .env and run docker compose up -d.

Inside the image

• The server lives in /antimatter, with the binaries antimatter and amctl in /antimatter/bin (on the PATH).
• It runs as the unprivileged user antimatter (uid 2000) on a minimal distroless base, with no shell.
• Ports: 8065 (web and API), 8067 (metrics), 8074 (cluster), 8443 UDP and TCP (calls).
• Local mode (ServiceSettings.EnableLocalMode) is on, so amctl --local works inside the container. The health check runs amctl system status --local.
• The bundled apps are in /antimatter/prepackaged_plugins, signed with the Antimatter app signing key.
• Text extraction tools (pdftotext, wvText, unrtf, tidy) are included, so the content of uploaded documents can be searched.

Other compose files

The antimatter-docker repository has a production setup in deploy/compose/: nginx with your own certificates or Let's Encrypt (certbot), PostgreSQL, the optional GIF service (profile gifs) and named volumes for the server's configuration, data and logs, documented in its README. It uses the stable image by default and stores files on a local volume instead of S3 storage. Use it if you prefer nginx to Caddy, or already have certificates.

Create the first administrator

Open SITE_URL in your browser and create an account. The first account created on a new server becomes the system administrator, and the setup then guides you through creating your first community (Antimatter's name for a team or workspace).

Do it right after the first start: until then, anyone who reaches the server first becomes its administrator. To create the account from the command line instead, before the server is reachable from outside:

docker compose exec antimatter amctl --local user create --system-admin --email-verified \
    --email admin@example.com --username admin --password 'a-long-password'
docker compose exec antimatter amctl --local team create --name main --display-name "Main"
docker compose exec antimatter amctl --local team users add main admin

Then sign in at SITE_URL. Start the command with a space to keep the password out of your shell history (with HISTCONTROL=ignorespace), or change the password once signed in.

Next steps once you are in:

1. For a company or an organisation, set Kind of new communities to Workspace, and change the kind of a community you already created in its settings: Guild or workspace.
2. Decide who can create accounts: Sign-in and accounts.
3. Configure email, so invitations and password resets work: Email and push notifications.
4. Open the calls port in your firewall: Calls and voice.
5. Check which apps are on: Bundled apps.

Download a release

Without Docker, install Antimatter from the files of a release on GitHub: github.com/AntimatterChat/antimatter/releases. Each release has a version number such as 0.9.0, and its tag is the same number with a v in front (v0.9.0).

Each release has these files, for amd64 and arm64 servers:

The packages and the archive hold the same program: the server (antimatter), the command-line tool (amctl), both web apps (the default interface and the classic one), the bundled apps, the email templates and the translations. The packages add a systemd service and a settings file, so each is an all-in-one installation: you only add a PostgreSQL database. There are no separate binary downloads: the binaries are in the archive, in antimatter/bin/. They are static, so they run on any Linux distribution of their architecture.

In the package names, the hyphen of a prerelease version becomes a tilde, so that the package manager sorts a prerelease before the final release: version 0.9.0-rc.1 gives antimatter_0.9.0~rc.1-1_amd64.deb and antimatter-0.9.0~rc.1-1.x86_64.rpm. The archive keeps the hyphen.

antimatter version prints the release version as Build Number, with the commit it was built from as Build Hash. Its Version line is the version of the Mattermost line Antimatter is based on.

Check the download

Download the file you need and SHA256SUMS into the same directory, from the release page or with curl, then check the file:

curl -fLO https://github.com/AntimatterChat/antimatter/releases/download/v<version>/antimatter_<version>-1_amd64.deb
curl -fLO https://github.com/AntimatterChat/antimatter/releases/download/v<version>/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS

Each file you downloaded must be listed with OK. Any other result means the file is damaged or incomplete: download it again, and don't install it. SHA256SUMS is not signed: it detects a damaged download, and proves nothing more than the HTTPS download from GitHub does.

Install the .deb or .rpm package

The package installs Antimatter as a systemd service, which only needs a database to start. Use it on a 64-bit Debian, Ubuntu, Fedora or RHEL-compatible server with systemd.

What the package installs

The directories the server writes to in /opt/antimatter (config, data, plugins, client/plugins and logs) are links to /etc/antimatter, /var/lib/antimatter and /var/log/antimatter. So an upgrade, which replaces /opt/antimatter, never touches your data. The package also creates the system user antimatter, which runs the server and owns these directories.

The package depends on ca-certificates. It recommends PostgreSQL (postgresql on Debian and Ubuntu, postgresql-server on Fedora and RHEL), media-types (mailcap for the .rpm) and gifs-server, the GIF service, which has its own release (see below). apt and dnf install recommended packages when they find them. It suggests poppler-utils, wv, unrtf and tidy (no wv for the .rpm): they extract the text of uploaded documents, so that search finds words inside them. Install them yourself if you want this.

1. Install the packages

Download the Antimatter package and the GIF service package of your architecture, check them as shown above, and install both in one command, so that the recommendation of gifs-server is met (it is not in the distributions' repositories):

# Debian, Ubuntu
sudo apt install ./antimatter_<version>-1_amd64.deb ./gifs-server_*_amd64.deb
# Fedora, RHEL
sudo dnf install ./antimatter-<version>-1.x86_64.rpm ./gifs-server-*.x86_64.rpm

Keep the ./: it tells apt and dnf to install a local file. To install without the GIF service, leave its package out. The package enables the antimatter service but doesn't start it, and prints the next steps.

2. Create the database

Antimatter needs PostgreSQL 15 or newer, on this server or another one. Check the version of your distribution's PostgreSQL with psql --version. If it is older, install a newer version from the PostgreSQL project's own repositories, or use a database on another server. On Debian and Ubuntu, the postgresql package starts the database. On Fedora and RHEL, create and start it first:

sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

Then create a user and a database for Antimatter:

sudo -u postgres psql -c "CREATE USER antimatter WITH PASSWORD 'a-long-password'"
sudo -u postgres psql -c "CREATE DATABASE antimatter OWNER antimatter"

PostgreSQL must accept password connections from 127.0.0.1: the host lines of its pg_hba.conf file, with the scram-sha-256 method.

3. Set the database and the site URL

Edit /etc/antimatter/antimatter.env (sudoedit /etc/antimatter/antimatter.env). Remove the # in front of the lines you use, and set the database and the address people will open:

AM_SQLSETTINGS_DRIVERNAME=postgres
AM_SQLSETTINGS_DATASOURCE=postgres://antimatter:a-long-password@localhost:5432/antimatter?sslmode=disable&connect_timeout=10
AM_SERVICESETTINGS_SITEURL=https://chat.example.com

Any setting of the configuration can go in this file, as AM_<SECTION>_<SETTING>: for example, SqlSettings.DataSource is AM_SQLSETTINGS_DATASOURCE. A setting set here can't be changed in the System Console. See Configuration. Restart the server after each change: sudo systemctl restart antimatter.

The service also sets a few defaults, which a line in antimatter.env overrides: logging to files is off (AM_LOGSETTINGS_ENABLEFILE=false, AM_NOTIFICATIONLOGSETTINGS_ENABLEFILE=false), and local mode is on (AM_SERVICESETTINGS_ENABLELOCALMODE=true), so that amctl --local works on the server.

4. Start it

sudo systemctl start antimatter
journalctl -u antimatter -f
sudo -u antimatter amctl --local system status

At the first start, the server creates its tables, then listens on port 8065. Open http://<server>:8065, or your domain once a reverse proxy is in place (see Domain and HTTPS), and create the first account right away: it becomes the system administrator. To create it from the command line instead, use the amctl commands of Create the first administrator, with sudo -u antimatter amctl --local in place of docker compose exec antimatter amctl --local.

5. Turn on GIFs

The GIFs app is bundled and on, and antimatter.env already points it at the GIF service on the same server (AM_GIFS_SERVICE_URL=http://127.0.0.1:8080/v2). It still needs the service's API key. The gifs-server package generated one at its installation:

sudo systemctl start gifs-server-stickers    # imports the sticker pack, about a minute and a half
sudo systemctl start gifs-server
sudo grep -v '^#' /etc/gifs-server/api-keys

Put the key in antimatter.env as AM_GIFS_API_KEY=<key> and restart Antimatter, or enter it as API key in System Console › Plugins › GIFs. If the GIF service runs on another server, set AM_GIFS_SERVICE_URL to its address. To let people add their own GIFs and stickers, see GIFs.

The service

• It runs as the antimatter user, in /opt/antimatter, and reads /etc/antimatter/antimatter.env. systemd restarts the server whenever it exits, and gives it up to an hour to start, because the database migrations of a new version can take long.
• Its logs are in the journal: journalctl -u antimatter.
• It is hardened: /usr and /etc are read-only for the server, except /etc/antimatter/config, and it can't see /home, /root or /run/user. If you move the file storage (FileSettings.Directory), choose a directory outside these, owned by antimatter.
• Upgrades replace the service file. To change it, use sudo systemctl edit antimatter, which keeps your changes in a separate file.

Upgrade a package

1. Take a backup (see Backups and upgrades).
2. Download the new package and SHA256SUMS, and check them.
3. Stop the server, install the new package over the old one, and start it again:

   sudo systemctl stop antimatter
   sudo apt install ./antimatter_<new version>-1_amd64.deb     # or: sudo dnf install ./antimatter-<new version>-1.x86_64.rpm
   sudo systemctl start antimatter
   journalctl -u antimatter -f

The package doesn't restart the server itself. After an upgrade it prints Antimatter was upgraded; restart it to run the new version: sudo systemctl restart antimatter: if you didn't stop the server first, restart it right away. The upgrade replaces /opt/antimatter and the service file, and keeps antimatter.env, config.json, /var/lib/antimatter and the logs. When it starts, the server upgrades the database and installs the newer versions of the bundled apps.

If a new version changes the default antimatter.env, apt asks whether to keep your version: keep it. dnf keeps yours and saves the new one as /etc/antimatter/antimatter.env.rpmnew. Upgrades only go forward: don't install an older version over a newer one.

Remove a package

sudo apt remove antimatter or sudo dnf remove antimatter stops and disables the service, and removes the program. It keeps the data (/var/lib/antimatter), the configuration (/etc/antimatter), the database and the antimatter user: delete them yourself to remove Antimatter completely.

Apps in the packages and the archive

The packages and the archive include the latest signed release of these apps, in prepackaged_plugins/: AI chat, Calls, GIFs, Memes, Notes, Polls, Todo, Voice Channels and Whiteboard. An app that had no release yet when the server release was built is left out: ls /opt/antimatter/prepackaged_plugins shows what your release includes. Memes and Todo are included but not turned on: Bundled apps explains how to install and enable them.

Kanban and Playbooks are no longer bundled with the server or with either Docker image: a server that already has one installed keeps it across an upgrade, and anyone else installs it from its own release, like the apps below. The other apps of the Docker images are not in the packages or the archive either: Mail, Calendar, GitHub, GitLab, Jira and Metrics. Install each one, Kanban and Playbooks included, from its own releases:

Each app release has the app's bundle (a .tar.gz file), its signature (the same name with .sig added) and a SHA256SUMS file. To install an app, allow uploads, then add the bundle with amctl:

# 1. In /etc/antimatter/antimatter.env, add this line, then restart Antimatter
AM_PLUGINSETTINGS_ENABLEUPLOADS=true
sudo systemctl restart antimatter
# 2. Download the bundle where the antimatter user can read it, and install it
cd /tmp
curl -fLO https://github.com/AntimatterChat/antimatter-plugin-boards/releases/download/v<version>/<bundle>.tar.gz
sudo -u antimatter amctl --local plugin add <bundle>.tar.gz
sudo -u antimatter amctl --local plugin enable focalboard

To upgrade an app installed this way, add the new bundle with plugin add --force: package upgrades only upgrade the bundled apps. You can remove the AM_PLUGINSETTINGS_ENABLEUPLOADS line again afterwards. See Installing other apps for the other ways to install apps.

App signatures

The app bundles are signed with the Antimatter app signing key: each .tar.gz.sig file is a detached GPG signature of its bundle. The server checks these signatures before it installs a bundled app. To check a bundle yourself:

curl -fsSLO https://raw.githubusercontent.com/AntimatterChat/antimatter-docker/main/keys/antimatter-plugin-signing.asc
gpg --import antimatter-plugin-signing.asc
gpg --verify <bundle>.tar.gz.sig <bundle>.tar.gz

gpg must report a good signature from Antimatter Plugin Signing, with the fingerprint 06C8 1032 4677 0F08 BBA7 78B9 E69B 05C3 92A6 9A45. It also warns that the key is not certified with a trusted signature: that is normal for a key you haven't signed yourself. An app release without .sig files is unsigned, and its release notes say so.

Install from a release archive

The archive, antimatter-<version>-linux-<arch>.tar.gz (for example antimatter-0.9.0-linux-amd64.tar.gz), suits a distribution without .deb or .rpm packages, or a layout of your own. It contains a single antimatter/ directory with bin/antimatter, bin/amctl, config/config.json, the web apps (client/ and client-fusion/), the bundled apps (prepackaged_plugins/, see above), the email templates and the translations.

1. Prepare PostgreSQL

Antimatter only supports PostgreSQL, version 15 or newer (older versions start, with an error in the log). Create a user and a database:

sudo -u postgres psql <<'EOF'
CREATE USER antimatter WITH PASSWORD 'a-long-password';
CREATE DATABASE antimatter OWNER antimatter;
EOF

2. Unpack and configure

sudo tar -xzf antimatter-<version>-linux-amd64.tar.gz -C /opt
sudo useradd --system --user-group antimatter
sudo mkdir -p /opt/antimatter/data
sudo chown -R antimatter:antimatter /opt/antimatter

Point the server at the database, either in /opt/antimatter/config/config.json (SqlSettings.DataSource) or with environment variables, and set the site URL:

AM_SQLSETTINGS_DRIVERNAME=postgres
AM_SQLSETTINGS_DATASOURCE=postgres://antimatter:a-long-password@localhost:5432/antimatter?sslmode=disable&connect_timeout=10
AM_SERVICESETTINGS_SITEURL=https://chat.example.com

The archive's config.json is a complete default configuration: settings you change in the System Console are saved back to it. To keep the configuration in the database instead, see Configuration.

3. Run it as a service

A systemd unit, in /etc/systemd/system/antimatter.service:

[Unit]
Description=Antimatter
After=network.target postgresql.service

[Service]
Type=notify
User=antimatter
Group=antimatter
WorkingDirectory=/opt/antimatter
ExecStart=/opt/antimatter/bin/antimatter
EnvironmentFile=-/etc/antimatter.env
TimeoutStartSec=3600
Restart=always
RestartSec=10
LimitNOFILE=49152

[Install]
WantedBy=multi-user.target

Put your AM_ variables in /etc/antimatter.env (readable by root only), then:

sudo systemctl daemon-reload
sudo systemctl enable --now antimatter
journalctl -u antimatter -f

The server listens on port 8065. Open http://<server>:8065, or your domain once a reverse proxy is in place (see Domain and HTTPS), and create the first account: it becomes the system administrator.

bin/amctl manages the running server from the command line. On the server itself, it works without signing in through local mode: set AM_SERVICESETTINGS_ENABLELOCALMODE=true, then run sudo -u antimatter /opt/antimatter/bin/amctl --local system status.

For GIFs, install the GIF service (see below) and set AM_GIFS_SERVICE_URL and AM_GIFS_API_KEY as in step 5 of the packages.

The GIF service and push proxy packages

The GIF service and the push proxy have their own releases, with the same rules as the server's: a .tar.gz archive, a .deb and a .rpm package for amd64 and arm64, and a SHA256SUMS file. Versions with a hyphen are prereleases. Check the downloads with sha256sum --check --ignore-missing SHA256SUMS, as for the server.

The GIF service (gifs-server)

Releases: github.com/AntimatterChat/gifs-server/releases. The archive is gifs-server-<version>-linux-<arch>.tar.gz; the packages are named gifs-server.

sudo apt install ./gifs-server_*_amd64.deb      # Debian, Ubuntu
sudo dnf install ./gifs-server-*.x86_64.rpm     # Fedora, RHEL

The package installs:

• /usr/bin/gifs-server, and the gifs-server service, which runs as the gifs-server user and keeps its catalogue in /var/lib/gifs-server;
• the gifs-server-stickers service, which imports or updates the sticker pack in /usr/share/gifs-server/stickers when you start it, then stops;
• its settings, /etc/gifs-server/gifs-server.env (AM_GIFS_ variables, kept on upgrades), and /etc/gifs-server/api-keys, one API key per line, with a random key generated at the first installation.

It listens on 127.0.0.1:8080, so only Antimatter on the same server can reach it. If Antimatter runs elsewhere, set AM_GIFS_LISTEN=:8080 in gifs-server.env and restrict access to the port with your firewall. The file lists the other settings: AM_GIFS_UPLOAD_KEYS (the keys allowed to add GIFs and stickers, and to delete the ones added with them), AM_GIFS_PUBLIC_URL, AM_GIFS_TRUST_PROXY and AM_GIFS_LOG_LEVEL. The package recommends ffmpeg, gifsicle, librsvg2-bin (librsvg2-tools for the .rpm) and a DejaVu font: the service uses them to make the GIF, video and sticker formats when it imports or receives files, and runs without them.

Like the server, the service is enabled but not started at installation. Start it as shown in step 5 of the packages. After an upgrade, restart it: sudo systemctl restart gifs-server. Removing the package keeps the catalogue in /var/lib/gifs-server.

The push proxy

Releases: github.com/AntimatterChat/push-proxy/releases. The archive is antimatter-push-proxy-<version>-linux-<arch>.tar.gz; the packages are named antimatter-push-proxy. The package installs /usr/bin/antimatter-push-proxy and the antimatter-push-proxy service, which runs as the antimatter-push-proxy user and reads /etc/antimatter-push-proxy/antimatter-push-proxy.json (kept on upgrades). The Apple and Firebase credentials go in /etc/antimatter-push-proxy/certs: Push notifications explains where they come from.

sudo apt install ./antimatter-push-proxy_*_amd64.deb      # or: sudo dnf install ./antimatter-push-proxy-*.x86_64.rpm
sudo install -o root -g antimatter-push-proxy -m 0640 \
    AuthKey_ABCDE12345.p8 firebase-service-account.json /etc/antimatter-push-proxy/certs/
sudoedit /etc/antimatter-push-proxy/antimatter-push-proxy.json
sudo systemctl start antimatter-push-proxy
journalctl -u antimatter-push-proxy -f

In the settings file, paths are relative to /etc/antimatter-push-proxy: for example "AppleAuthKeyFile": "./certs/AuthKey_ABCDE12345.p8" and "ServiceFileLocation": "./certs/firebase-service-account.json". Then set Push Notification Server in Antimatter to http://<proxy host>:8066. After an upgrade, restart it: sudo systemctl restart antimatter-push-proxy.

Other server commands

Besides running the server (antimatter, or antimatter server), the binary has a few maintenance commands. They read the same configuration as the server.