컨테이너로 Mattermost 배포

기능 탐색, 테스트, 개발 목적으로 컨테이너 기술을 사용해 Mattermost 서버를 배포할 수 있습니다. 기반 인프라를 직접 관리하지 않고도 Mattermost 인스턴스를 빠르게 구성할 수 있기 때문입니다.

이 배포 방식은 클러스터 기반 배포나 고가용성(HA) 구성을 기본으로 지원하지 않으므로 프로덕션 환경에서는 사용하지 않아야 합니다.

구체적인 배포 방법은 아래에서 원하는 컨테이너 플랫폼을 선택해 확인하세요.

FIPS/STIG

Mattermost v11부터 각 릴리스는 FIPS 준수 빌드와 비FIPS 빌드 두 가지 변형으로 제공됩니다. 이를 통해 엄격한 컴플라이언스 요구 사항이 있는 조직은 FIPS 버전을 채택할 수 있고, 그 밖의 조직은 표준 릴리스를 계속 사용하면서도 두 빌드 모두 Mattermost의 전체 제품 수명 주기와 동기화된 상태를 유지합니다.

Mattermost의 FIPS 준수 Docker 이미지는 Chainguard의 FIPS 인증 기반 컨테이너로 빌드됩니다. 이 이미지는 FIPS(Federal Information Processing Standards) 준수를 보장하여 조직이 까다로운 보안 요구 사항을 충족하도록 돕습니다.

이러한 기반 위에서 Mattermost 제품 코드 자체도 FIPS 승인 암호화 알고리즘만 사용하도록 FIPS 요구 사항에 맞춰져 있습니다. 이로써 컨테이너 기반과 애플리케이션 계층 모두가 컴플라이언스 요구를 충족합니다.

또한 Chainguard 기반 이미지는 STIG로 강화되어 있으며 DISA General Purpose Operating System SRG를 기준으로 엄격하게 스캔되어, 견고하고 안전한 운영 태세를 제공합니다.

Mattermost FIPS 개요

Mattermost의 FIPS 준수 이미지는 두 가지 Chainguard 기반 이미지로 빌드됩니다.

• 빌드 타임 이미지: 컴파일된 Mattermost 바이너리가 CGO를 통해 OpenSSL을 호출하도록 하여 컴파일 시점의 FIPS 준수를 보장합니다.
• 런타임 이미지: 엄격한 OpenSSL 구성을 사용해 런타임 환경에서 FIPS 준수를 강제합니다.

모든 애플리케이션 수준 코드는 FIPS 승인 알고리즘만 사용하므로, 시스템의 모든 계층에서 암호화 요구 사항이 일관되게 적용됩니다.

Docker

이 가이드는 Docker 컨테이너를 사용해 Mattermost를 배포하는 단계별 방법을 안내합니다.

Docker 설치

Docker가 설치되어 있지 않다면 운영 체제에 맞는 아래 안내를 따르세요. Docker Engine과 Docker Compose(릴리스 1.28 이상)가 필요합니다.

Docker에 Mattermost 배포

이 섹션에서는 Docker Compose를 활용해 Docker에 Mattermost를 배포하는 빠른 시작 방법을 안내합니다.

1. 터미널 창에서 저장소를 클론하고 해당 디렉터리로 이동합니다.

   git clone https://github.com/mattermost/docker
   cd docker

2. env.example 파일을 복사하고 수정해 .env 파일을 만듭니다.

   cp env.example .env

   중요

   • 최소한 .env 파일의 DOMAIN 값을 Mattermost 서버의 도메인에 맞게 수정해야 합니다.
   • MM_SUPPORTSETTINGS_SUPPORTEMAIL을 통해 Support Email을 구성하는 것을 권장합니다. 사용자가 도움이 필요할 때 연락하는 이메일 주소입니다.

3. 필요한 디렉터리를 만들고 권한을 설정합니다.

   mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
   sudo chown -R 2000:2000 ./volumes/app/mattermost

4. (선택) NGINX용 TLS를 구성합니다. 포함된 NGINX 리버스 프록시를 사용하지 않는다면 이 단계는 건너뛰어도 됩니다.

새 인증서와 키 생성

bash scripts/issue-certificate.sh -d <YOUR_MM_DOMAIN> -o ${PWD}/certs

인증서와 키를 포함하려면 .env 파일에서 다음 줄의 주석을 해제하고 해당 파일을 올바르게 가리키는지 확인하세요.

#CERT_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/fullchain.pem
#KEY_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/privkey.pem

기존 인증서와 키 사용

mkdir -p ./volumes/web/cert
cp <PATH-TO-PRE-EXISTING-CERT>.pem ./volumes/web/cert/cert.pem
cp <PATH-TO-PRE-EXISTING-KEY>.pem ./volumes/web/cert/key-no-password.pem

인증서와 키를 포함하려면 .env 파일의 다음 줄이 해당 파일을 올바르게 가리키는지 확인하세요.

CERT_PATH=./volumes/web/cert/cert.pem
KEY_PATH=./volumes/web/cert/key-no-password.pem

5. Mattermost를 배포합니다.

포함된 NGINX를 사용하지 않고 배포

docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d

새로 배포한 Mattermost에 접속하려면 브라우저에서 http://<YOUR_MM_DOMAIN>:8065/로 이동합니다.

배포를 종료하려면 다음과 같이 실행합니다.

docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml down

포함된 NGINX를 사용해 배포

docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d

새로 배포한 Mattermost에 HTTPS로 접속하려면 브라우저에서 https://<YOUR_MM_DOMAIN>/로 이동합니다.

배포를 종료하려면 다음과 같이 실행합니다.

docker compose -f docker-compose.yml -f docker-compose.nginx.yml down

6. 첫 번째 Mattermost 시스템 관리자 사용자를 만들고, 사용자를 더 초대한 뒤 Mattermost 플랫폼을 살펴보세요.

GitLab SSO 구성(선택)

자체 서명 인증서와 함께 GitLab SSO를 사용하려면 해당 인증 기관의 PKI 체인을 추가해야 합니다. Token request failed: certificate signed by unknown authority 오류를 피하기 위해 필요합니다.

PKI 체인을 추가하려면 .env 파일에서 다음 줄의 주석을 해제하고 pki_chain.pem 파일을 가리키도록 설정합니다.

#GITLAB_PKI_CHAIN_PATH=<path_to_your_gitlab_pki>/pki_chain.pem

그런 다음 docker-compose.yml 파일에서 다음 줄의 주석을 해제하고 동일한 pki_chain.pem 파일을 가리키도록 설정합니다.

# - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro

mattermost-docker에서 업그레이드

mattermost-docker GitHub 저장소는 더 이상 사용되지 않습니다. Mattermost의 공식 Docker 배포 솔루션은 mattermost/docker GitHub 저장소에서 확인하세요.

기존 mattermost/mattermost-prod-app 이미지에서 마이그레이션하려면, Mattermost가 공식 지원하는 mattermost/mattermost-enterprise-edition 또는 mattermost/mattermost-team-edition 이미지로 옮기는 것을 권장합니다. 이 이미지들은 커뮤니티에서 오랫동안 문제로 지적되어 온 PostgreSQL v11 이상 데이터베이스를 지원하며, 새 이미지로 이동해도 기능이 손실되지 않습니다.

추가 도움이나 문의가 필요하면 이 이슈를 참고하세요.

다른 버전의 Mattermost 설치

1. 배포를 종료합니다.

2. git pull을 실행해 저장소의 최근 변경 사항을 가져오고, env.example의 변경 여부를 확인합니다.

3. .env 파일의 MATTERMOST_IMAGE_TAG를 원하는 enterprise 또는 team 이미지 버전을 가리키도록 조정합니다.

   중요

   프로덕션 환경에서는 MATTERMOST_IMAGE_TAG=release-10 같은 일반 태그 대신 MATTERMOST_IMAGE_TAG=release-10.5처럼 특정 버전 태그를 사용하는 것을 권장합니다. 일반 release-x 태그는 개발 용도로만 의도되었으며, 해당 메이저 버전 내의 새 패치 릴리스를 자동으로 받지 않습니다. 특정 버전 태그를 사용하면 프로덕션 배포를 더 재현 가능하고 결정적인 환경으로 유지할 수 있습니다.

4. Mattermost를 다시 배포합니다.

문제 해결

Docker 배포 문제 해결

M1 Mac에 배포하면서 Docker 컨테이너에서 권한 문제가 발생한다면, 필요한 디렉터리를 만들고 권한을 설정하는 세 번째 단계를 다시 수행하되 다음 명령은 건너뛰세요.

sudo chown -R 2000:2000 ./volumes/app/mattermost

Docker 배포 전반에 문제가 있다면 docker 데몬이 활성화되어 실행 중인지 확인하세요.

sudo systemctl enable --now docker

Mattermost 배포의 모든 데이터와 설정을 제거하려면 다음과 같이 실행합니다.

sudo rm -rf ./volumes

PostgreSQL 문제 해결

빠른 시작 배포에서는 .env 파일에서 Postgres 사용자 이름 및/또는 비밀번호를 변경할 수 있습니다(권장). 데이터베이스를 외부에서 관리한다면 데이터베이스 관리 도구에서 비밀번호를 변경한 뒤, .env 파일을 새 자격 증명으로 업데이트해야 합니다.

TLS 및 NGINX 문제 해결

NGINX용 TLS 인증서와 키 구성에 대한 자세한 안내는 저장소의 이 문서를 참고하세요.

Docker Preview로 Mattermost 체험

단일 로컬 머신에서 Docker로 Mattermost를 평가할 방법을 찾고 있나요? Mattermost Docker Preview Image를 사용해 Preview 모드로 Mattermost를 설치하는 것을 권장합니다.

1. Docker를 설치합니다.

2. Docker가 준비되면 터미널 창에서 다음 명령을 실행합니다.

   docker run --name mattermost-preview -d --publish 8065:8065 --publish 8443:8443 mattermost/mattermost-preview

3. Docker가 이미지를 모두 가져오면 브라우저에서 http://localhost:8065/로 이동해 Mattermost를 미리 볼 수 있습니다.

4. 화면 오른쪽 상단의 Don't have an account를 선택해 미리보기 인스턴스용 계정을 만듭니다. 이 옵션이 보이지 않는다면 Enable open server 구성 설정이 활성화되어 있는지 확인하세요. 이 설정은 자체 호스팅 Mattermost 배포에서 기본적으로 비활성화되어 있습니다.

5. 사용자 자격 증명으로 미리보기 인스턴스에 로그인합니다.

미리보기 배포 문제 해결

Mattermost의 Preview 모드 Docker 인스턴스는 제품 평가용으로 설계되었으며, 이메일을 활성화하지 않고도 제품이 동작하도록 SendEmailNotifications=false를 설정합니다. 배포를 맞춤 구성하려면 구성 설정 문서를 참고하세요.

Mattermost 미리보기 이미지와 컨테이너를 업데이트하려면 먼저 기존 mattermost-preview 컨테이너를 중지하고 삭제해야 합니다. 다음 명령을 실행합니다.

docker pull mattermost/mattermost-preview
docker stop mattermost-preview
docker rm mattermost-preview

새 이미지를 받고 컨테이너를 중지·삭제한 뒤에는 위의 docker run 명령을 다시 실행해야 합니다.

컨테이너 내부 셸에 접근하려면 다음 명령을 실행합니다.

docker exec -ti mattermost-preview /bin/bash

Mattermost 배포 보안 강화

Docker 컨테이너를 사용한 Mattermost 배포는 HTTPS와 리버스 프록시를 적절히 구성하면 안전하게 운영할 수 있습니다.

이 가이드는 Mattermost 배포에 TLS와 NGINX 리버스 프록시를 설정해 사용자와 서버 간 통신을 안전하게 보호하는 단계를 설명합니다.

1. 리버스 프록시 역할을 할 NGINX 컨테이너를 설정합니다. NGINX는 별도 컨테이너로 사용하거나 호스트 머신에 설치해 사용할 수 있습니다.

2. NGINX 구성과 TLS 인증서용 볼륨을 바인딩합니다.

   • NGINX 구성 파일과 TLS 인증서를 위한 Docker 볼륨을 바인딩해 이 자산들이 영속적이고 안전하게 저장되도록 합니다.
   • TLS 키 같은 민감한 파일이 저장되는 호스트 디렉터리에는 권한 제한을 적용합니다.

3. 리버스 프록시와 HTTPS를 구성하기 위한 견고한 nginx.conf 파일을 작성해 NGINX 구성 파일을 만듭니다. 다음은 기본 예시입니다.

   server {
       listen 443 ssl;
       server_name your-domain.com;
   
       ssl_certificate /etc/nginx/certs/fullchain.pem;
       ssl_certificate_key /etc/nginx/certs/privkey.pem;
   
       ssl_protocols TLSv1.2 TLSv1.3;
       ssl_ciphers HIGH:!aNULL:!MD5;
   
       location / {
           proxy_pass http://mattermost:8065;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto https;
       }
   }

   적용하기 전에 nginx -t로 구성을 검증하세요.

4. TLS 인증서를 확보합니다.

   • 무료 자동 인증서를 원한다면 Let's Encrypt를 사용하세요. Certbot 같은 도구로 과정을 자동화할 수 있습니다.
   • 또는 신뢰할 수 있는 인증 기관(CA)에서 인증서를 구매하고, 중간 인증서와 루트 인증서 체인이 올바르게 설정되었는지 확인하세요.

   개인 키는 안전하게 보관하고 Docker 이미지 안에 직접 저장하지 마세요.

5. Docker 네트워킹으로 컨테이너를 연결합니다.

   • Docker의 네트워킹 기능을 사용해 컨테이너를 격리하고 연결합니다.

   • 안전한 통신을 위해 맞춤 Docker 브리지 네트워크를 만듭니다. 예를 들면 다음과 같습니다.

     docker network create mattermost-network

   • 같은 네트워크에서 Mattermost와 NGINX 컨테이너를 실행합니다.

     docker network connect mattermost-network mattermost
     docker network connect mattermost-network nginx

6. 도메인을 서버 IP 주소로 연결합니다.

   도메인(예: your-domain.com)이 서버의 공인 IP 주소를 가리키는지 확인하세요. IP가 동적이라면 원활한 연결을 위해 동적 DNS(DDNS) 설정을 고려하세요.

7. 인증서를 배치하고 구성을 업데이트한 뒤 NGINX 컨테이너를 재시작합니다.

8. 로그(docker logs nginx)를 사용해 컨테이너 동작을 확인하고 문제를 해결합니다.

9. 웹 브라우저에서 https://your-domain.com에 접속해 Mattermost가 HTTPS로 안전하게 실행되고 있는지 확인합니다.

10. SSL Labs(https://www.ssllabs.com/ssltest/) 같은 도구로 TLS 설정의 품질을 검증합니다.

11. NGINX 구성에서 HSTS(HTTP Strict Transport Security)를 활성화해 다운그레이드 공격을 방지합니다.

12. NGINX의 속도 제한 기능을 사용해 과도한 요청 같은 남용 트래픽을 제한합니다.

추가로 다음 사항도 고려하세요.

• Seccomp 프로필, AppArmor 같은 Docker 보안 기능을 사용해 컨테이너 런타임을 보호하세요.
• 컨테이너를 --privileged 권한으로 실행하지 말고 사용자 네임스페이스를 활용하세요.
• 서드파티 이미지의 취약점에 노출되지 않도록 항상 신뢰할 수 있는 이미지(예: 공식 NGINX 및 Mattermost 이미지)를 사용하세요.
• 알려진 취약점에 대한 패치가 적용되도록 Mattermost, NGINX, Docker를 정기적으로 최신 버전으로 업데이트하세요.
• 무단 접근을 제한하는 방화벽 규칙을 설정하고 Fail2Ban이나 Wazuh 같은 도구로 트래픽을 모니터링하세요.

이 단계를 따르면 Docker 컨테이너를 사용한 Mattermost 배포가 NGINX를 통한 효율적인 프록시와 함께 HTTPS로 안전하게 제공됩니다. 추가 보안 권장 사항까지 적용하면 진화하는 위협으로부터 환경을 한층 더 보호할 수 있습니다.