Bill of Materials and Registry Mirroring

EditionTeam Edition, Professional, Enterprise, Enterprise Advanced

DeploymentSelf-Hosted, Air-Gapped

On an internet-connected machine, you must gather all required packages, container images, and dependencies needed for the installation process. The resources you'll need will depend on your deployment method.

Bill of materials

Linux

Using our provided tarball is recommended as the simplest installation method for air-gapped environments. You can install the Mattermost Server in a few minutes on any air-gapped 64-bit Linux system.

Prerequisites

• Mattermost tarball. We recommend using the latest ESR for extended support where server upgrades may be infrequent.
• Database: PostgreSQL installation packages or container images for your Linux distribution.
• File Storage: Local filesystem storage is sufficient for deployments under 2,000 users. For larger deployments requiring high availability, we recommend using an S3-compatible object storage solution or an NFS (Network File System) server for shared storage needs.
• Load balancer: If you already have a load balancer running in your air-gapped environment you can skip this resource, otherwise we recommend deploying NGINX from these Linux packages.
• Desktop app: Download the required package based on your deployment method.

(Optional) Supporting services

Consider downloading these additional resources if you plan to enable these optional components:

• Mattermost Calls: mattermost-calls-offloader (required for recording, transcription, and live captions) and mattermost-rtcd (required for performance and scalability).
• Elasticsearch can be deployed for enhanced search performance at scale.
• Prometheus and Grafana for monitoring and observability.

Kubernetes

Kubernetes is recommended for a highly scalable and robust deployment if your organization is already running a Kubernetes cluster in the air-gapped environment.

Prerequisites

• Mattermost Operator and values.
• Database: We recommend options such as the Postgres Operator from Crunchy Data, CloudNativePG, or pgEdge.
• File Storage: We recommend using an S3-compatible storage service or a mounted NFS volume for shared storage needs.
• Load balancer: If you already have a load balancer running in your air-gapped environment you can skip this resource, otherwise we recommend deploying NGINX, using the NGINX Ingress Controller operator.
• Desktop app: Download the required package based on your deployment method.

(Optional) Supporting services

Consider downloading these additional resources if you plan to enable these optional components:

• Mattermost Calls helm charts: mattermost-calls-offloader and values (required for recording, transcription, and live captions), mattermost-rtcd and values (required for performance and scalability).
• Elasticsearch can be deployed in air-gapped k8s environments for enhanced search performance at scale.
• Prometheus and Grafana operators for monitoring and observability.

Docker

Docker can be used if you don't have a running Kubernetes cluster in the air-gapped environment, but want to use containers for simplified installation and dependency management. Docker is not recommended for production environments at high scale, as it doesn't support clustered deployments or High Availability (HA) configurations out-of-the-box.

Prerequisites

• Mattermost Enterprise Edition image.
• Database: PostgreSQL image.
• Load balancer: If you already have a load balancer running in your air-gapped environment you can skip this resource, otherwise we recommend deploying NGINX from these images.
• Desktop app: Download the required package based on your deployment method.

(Optional) Supporting services

Consider downloading these additional resources if you plan to enable these optional components:

• Mattermost Calls images: calls-offloader (required for recording, transcription, and live captions) and rtcd (required for performance and scalability).
• Elasticsearch image for enhanced search performance at scale.
• Prometheus and Grafana images for monitoring and observability.

Mattermost plugins

Mattermost includes a number of pre-built integrations for mission-critical tools. If you'd like to use any plugins beyond those that are pre-built in the Mattermost package, you'll need to download the plugin binaries from the Mattermost Marketplace. Once you have Mattermost deployed, these plugin binaries can be uploaded directly in the System Console.

SSL/TLS certificates and keys

If your deployment requires SSL, ensure you have the necessary certificates. This includes certificates and keys for enabling HTTPS with Mattermost, as well as any CA files or certificates needed to access internal services such as LDAP or SAML. See Setup TLS for configuration details.

Local documentation

Mattermost documentation can be built and served locally so that installation and configuration guidance is available inside the air-gapped environment. Clone the mattermost/mattermost repository on your internet-connected machine, build the documentation site, and transfer the generated static output across the air gap alongside the rest of your bill of materials.

Prerequisites

• Git [download]
• Node.js 20 or later [download]

git clone https://github.com/mattermost/mattermost.git
cd mattermost/docs/site
npm ci
npm run build

The build writes a self-contained static site to docs/site/build/, which you can serve from any web server in the air-gapped environment. See the documentation site README for the full build options, including how to skip the API reference generation step if you don't need it.

Set up a private registry or mirror

A private container registry securely stores the Docker images necessary for air-gapped deployments, ensuring compliance with data isolation requirements. Similarly, a private package mirror stores operating system packages necessary for air-gapped deployments in Ubuntu or RHEL/CentOS Linux environments. Setting up a local registry or mirror is a critical step in deploying Mattermost to ensure all images, dependencies, and packages are available to you in the air-gapped environment. The steps below outline the process required to set up a local registry or mirror, depending on the deployment method you are using. These steps are a rough guide, and can be supplemented with online resources depending on your specific deployment needs.

Linux

(Ubuntu) Set up a private Debian package mirror

We will use Aptly to create a local mirror, although you can also use other options such as debmirror.

1. Install Aptly (on an internet-connected machine):

   apt-get update
   apt-get install aptly gnupg

2. Create a GPG key for signing packages:

   gpg --gen-key

3. Create a mirror configuration:

   aptly mirror create -architectures=amd64 debian-bullseye http://deb.debian.org/debian bullseye main contrib non-free

4. Update the mirror to download packages:

   aptly mirror update debian-bullseye

5. Create and publish a snapshot:

   aptly snapshot create debian-bullseye-$(date +%Y%m%d) from mirror debian-bullseye
   aptly publish snapshot debian-bullseye-$(date +%Y%m%d)

6. Serve the repository:

   aptly serve

7. Client configuration: Configure apt to use your local mirror:

   cat > /etc/apt/sources.list << EOF
   deb http://mirror.example.com/debian bullseye main contrib non-free
   EOF

(RHEL/CentOS) Set up a private RHEL package mirror

We will use reposync for a local mirror.

1. Install required tools (on an internet-connected RHEL system):

   yum install yum-utils createrepo

2. Download packages:

   mkdir -p /var/www/html/repos/rhel8
   reposync -p /var/www/html/repos/rhel8 --download-metadata --repo=rhel-8-for-x86_64-baseos-rpms
   reposync -p /var/www/html/repos/rhel8 --download-metadata --repo=rhel-8-for-x86_64-appstream-rpms

3. Create repository metadata:

   createrepo /var/www/html/repos/rhel8/rhel-8-for-x86_64-baseos-rpms
   createrepo /var/www/html/repos/rhel8/rhel-8-for-x86_64-appstream-rpms

4. Set up a web server:

   yum install httpd
   systemctl enable httpd
   systemctl start httpd

5. Client configuration: Disable existing repositories:

   cd /etc/yum.repos.d/
   mkdir backup
   mv *.repo backup/

6. Client configuration: Create new repository files:

   cat > /etc/yum.repos.d/local-baseos.repo << EOF
   [local-baseos]
   name=Red Hat Enterprise Linux 8 BaseOS
   baseurl=http://mirror.example.com/repos/rhel8/rhel-8-for-x86_64-baseos-rpms
   enabled=1
   gpgcheck=0
   EOF
   
   cat > /etc/yum.repos.d/local-appstream.repo << EOF
   [local-appstream]
   name=Red Hat Enterprise Linux 8 AppStream
   baseurl=http://mirror.example.com/repos/rhel8/rhel-8-for-x86_64-appstream-rpms
   enabled=1
   gpgcheck=0
   EOF

7. Client configuration: Clear cache and test:

   yum clean all
   yum repolist

Kubernetes

Set up a self-hosted private container registry

1. Install Docker Registry:

   docker run -d -p 5000:5000 --restart=always --name registry registry:2

2. Configure persistent storage:

   docker run -d -p 5000:5000 --restart=always --name registry \
   -v /mnt/registry:/var/lib/registry \
   registry:2

3. Add TLS security (recommended):

   a. Generate self-signed certificates:

   mkdir -p certs
   openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
   -x509 -days 365 -out certs/domain.crt

   b. Run the registry with TLS:

   docker run -d -p 5000:5000 --restart=always --name registry \
   -v /mnt/registry:/var/lib/registry \
   -v $(pwd)/certs:/certs \
   -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
   -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
   registry:2

Configure Kubernetes to use private image registries

When using Kubernetes in an air-gapped environment, you need to configure it to use your private registry.

1. Create a Kubernetes secret for registry authentication:

   kubectl create secret docker-registry regcred \
   --docker-server=registry.example.com:5000 \
   --docker-username=your_username \
   --docker-password=your_password \
   --docker-email=your_email@example.com

2. Reference the secret in pod specifications:

   apiVersion: v1
   kind: Pod
   metadata:
     name: mattermost-pod
   spec:
     containers:
     - name: mattermost
       image: registry.example.com:5000/mattermost/mattermost-enterprise-edition:latest
     imagePullSecrets:
     - name: regcred

3. For Helm deployments, specify the registry in values.yaml:

   image:
     repository: registry.example.com:5000/mattermost/mattermost-enterprise-edition
     tag: latest
     pullPolicy: IfNotPresent
   
   imagePullSecrets:
     - name: regcred

Docker

Set up a self-hosted private container registry

1. Install Docker Registry:

   docker run -d -p 5000:5000 --restart=always --name registry registry:2

2. Configure persistent storage:

   docker run -d -p 5000:5000 --restart=always --name registry \
   -v /mnt/registry:/var/lib/registry \
   registry:2

3. Add TLS security (recommended):

   a. Generate self-signed certificates:

   mkdir -p certs
   openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
   -x509 -days 365 -out certs/domain.crt

   b. Run the registry with TLS:

   docker run -d -p 5000:5000 --restart=always --name registry \
   -v /mnt/registry:/var/lib/registry \
   -v $(pwd)/certs:/certs \
   -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
   -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
   registry:2

Populate your private registry

Ensure the required images from the Bill of Materials are downloaded and pushed to the private registry.

Configure Docker to use private image registries

Configure Docker on all hosts to trust and use your private registry.

1. Add your registry to Docker's trusted registries:

   Edit or create /etc/docker/daemon.json:

   {
     "insecure-registries": ["registry.example.com:5000"]
   }

   For registries using self-signed certificates:

   mkdir -p /etc/docker/certs.d/registry.example.com:5000
   cp domain.crt /etc/docker/certs.d/registry.example.com:5000/ca.crt

2. Restart Docker daemon:

   systemctl restart docker

3. Test the configuration:

   docker pull registry.example.com:5000/mattermost/mattermost-enterprise-edition:latest