Installation & Upgrading
Relevant source files
The following files were used as context for generating this wiki page:
Matterbridge provides multiple methods for installation and upgrading, ranging from pre-compiled binaries and package managers to building from source. The project is designed to be highly portable, supporting various chat protocols through a modular bridge architecture.
The installation process typically involves acquiring the executable, configuring a matterbridge.toml file, and defining gateways to link different chat platforms. Upgrading is generally a matter of replacing the existing binary with a newer version or pulling the latest container image.
Sources: README.md:144-156, README.md:231-255
Acquisition Methods
Pre-compiled Binaries
For most users, downloading the latest stable release is the recommended method. Stable releases are tagged (e.g., v1.26.0), while development releases follow the master branch and are available as artifacts from GitHub Actions.
On Unix-like systems, the binary must be granted execution permissions using chmod a+x.
Sources: README.md:144-156
Package Managers
Matterbridge is available through several package management systems:
- Snap: Available via Snapcraft.
- Scoop: Available through a dedicated bucket.
- Other Packages: Version overviews are maintained on Repology.
Sources: README.md:158-161
Building from Source
Building from source requires Go 1.18 or higher. This method allows for customization, such as including specific experimental bridges or excluding heavy components to save memory.
Build Customization via Tags
The build process uses Go build tags to manage dependencies. For example, the Microsoft Teams bridge requires significant memory (approx. 3GB RAM) to compile; users can exclude it using the nomsteams tag to reduce requirements to 0.5GB RAM.
# Install latest stable without msteams or zulip
go install -tags nomsteams,nozulip github.com/42wim/matterbridge@latest
Sources: README.md:163-181
Experimental Bridge: WhatsApp Multi-Device
Building with WhatsApp multi-device support requires a manual build because it utilizes a GPL3 library, which prevents the distribution of pre-compiled binaries under the standard Matterbridge license.
# Building with WhatsApp multi-device support
go install -tags whatsappmulti github.com/42wim/matterbridge@master
Sources: README.md:189-204
Installation Flow Architecture
The following diagram illustrates the decision logic for choosing an installation method based on user requirements and system constraints.
The diagram shows the transition from acquisition to execution, highlighting the impact of build tags on the installation process.
Sources: README.md:144-204
Configuration and Execution
Once installed, Matterbridge requires a configuration file (defaulting to matterbridge.toml). The configuration defines the "accounts" (connections to protocols) and "gateways" (the logic that bridges them).
Execution Arguments
| Flag | Description | Default |
|---|---|---|
-conf | Path to the configuration file | matterbridge.toml |
-debug | Enables debug logging | false |
-gops | Enables the gops agent for diagnostics | false |
-version | Displays the current version | N/A |
Sources: README.md:278-286
Docker Deployment
Matterbridge can be deployed as a container. Users typically mount their local matterbridge.toml into the container to maintain configuration persistence.
Sources: README.md:288-290
Upgrade Process
Upgrading Matterbridge follows a simple replacement pattern. Because the application is stateless (storing configuration in a external file and not maintaining a local database for message history), the upgrade does not require complex migrations.
This sequence illustrates a manual upgrade flow for binary installations.
Sources: README.md:150-156, vendor/golang.org/x/sys/unix/README.md:40-50
Summary
Installing Matterbridge is highly flexible, supporting binary downloads for ease of use and source builds for technical customization. Upgrading is streamlined by the application's design, which separates the executable logic from the TOML-based configuration, allowing for simple binary replacement or container image updates.