TENSE MOVEMENT

공식 mattermost/docker 저장소를 Apple Silicon(M1/arm64) Mac에서 설치·실행하며 겪은 문제와 해결 과정을 정리한 글입니다. 공식 저장소: https://github.com/mattermost/docker

이 환경의 실제 구성

저장소 경로: ~/projects/your-project/mattermost/docker/

Compose 구조: docker-compose.yml(base) + override 파일 택1

이미지 태그(.env): POSTGRES_IMAGE_TAG=18-alpine, MATTERMOST_IMAGE=mattermost-enterprise-edition, MATTERMOST_IMAGE_TAG=11.7.0

포트(.env): APP_PORT=8065, CALLS_PORT=8443

개요

이 저장소는 base + override 패턴을 씁니다.

파일	역할
`docker-compose.yml`	base. postgres + mattermost 정의. 포트 발행(`ports:`) 없음
`docker-compose.without-nginx.yml`	override. `APP_PORT:8065`를 호스트에 직접 노출 (localhost 접속용)
`docker-compose.nginx.yml`	override. nginx 리버스 프록시를 붙여 80/443으로 서비스

핵심: base 파일만 docker compose up 하면 mattermost는 컨테이너 내부에서만 8065를 열고 호스트로는 노출되지 않습니다. override를 반드시 함께 지정해야 합니다.

최소 경로: 0 → 1 → 2 → 3

0. 사전 준비 (필수)

Docker Desktop Apple Silicon 버전이 설치되어 있어야 합니다.

docker --version
docker compose version

1. arm64 매니페스트 에러 해결 (M1 필수)

M1에서 docker compose ... up을 하면 아래 에러가 날 수 있습니다.

no matching manifest for linux/arm64/v8 in the manifest list entries

원인

지정한 이미지 태그(예: postgres:18-alpine, mattermost-enterprise-edition:11.7.0)에 arm64 레이어가 없는 경우입니다. Docker가 현재 플랫폼(arm64)에 맞는 매니페스트를 찾지 못해 실패합니다.

해결 — `platform: linux/amd64` 명시

docker-compose.yml의 두 서비스에 amd64 플랫폼을 강제해, M1에서 에뮬레이션(Rosetta)으로 amd64 이미지를 돌립니다.

services:
  postgres:
    platform: linux/amd64        # ← 추가
    image: postgres:${POSTGRES_IMAGE_TAG}
    ...

  mattermost:
    depends_on:
      - postgres
    platform: linux/amd64        # ← 추가
    image: mattermost/${MATTERMOST_IMAGE}:${MATTERMOST_IMAGE_TAG}
    ...

참고: 에뮬레이션이라 네이티브 arm64보다 다소 느립니다. 동작에는 문제 없으며, 로컬 개발/테스트 용도로는 충분합니다.

2. 실행 — override로 8065 노출 (필수)

docker compose up만으로는 8065가 안 열립니다. override를 붙여야 접속됩니다.

cd ~/projects/your-project/mattermost/docker

# localhost:8065로 바로 접속 (nginx 없이)
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d

실행 명령	localhost:8065	설명
`docker compose up`	❌	base엔 `ports:` 발행이 없음
`... -f docker-compose.without-nginx.yml up -d`	✅	8065를 호스트에 직접 노출
`... -f docker-compose.nginx.yml up -d`	80/443	nginx 리버스 프록시 경유

접속: http://localhost:8065

볼륨 디렉터리 주의: mattermost 컨테이너가 ./volumes/...를 마운트합니다. 이 디렉터리가 없으면 기동에 실패할 수 있으니, 기동 후 상태를 확인하세요.

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

3. 첫 로그인 · 회원가입 동작 (중요)

첫 계정 = 시스템 관리자

Mattermost는 맨 처음 만든 계정 하나를 자동으로 System Admin(시스템 관리자)으로 승격합니다. 이 계정으로 이후 모든 사용자·설정을 관리합니다.

두 번째 가입이 막히는 이유

첫 계정 이후 self-signup(자유 가입)은 config.json의 아래 값에 지배됩니다.

"EnableUserCreation": true,       // 계정 생성 기능 자체 (켜짐)
"EnableOpenServer": false,        // ← 이게 false면 초대 없이는 가입 불가
"EnableSignUpWithEmail": true,    // 이메일 가입 방식 (켜짐)
"EnableSignInWithEmail": true

정상 동작입니다. 첫 계정은 서버 부트스트랩용이라 항상 생성되고, 그 다음부터는 EnableOpenServer: false 때문에 초대 링크 없이는 두 번째 가입이 막힙니다.

config 경로: ./volumes/app/mattermost/config/config.json

두 번째 이후 사용자 추가 — 3가지 방법

방법 1 — 초대 링크 (권장, 설정 그대로)

첫 계정(관리자)으로 로그인
팀 이름 옆 ⋮ → "Invite People"
나온 초대 링크로 새 사용자가 가입

방법 2 — 관리자가 직접 생성

System Console → User Management → Users → Add User

방법 3 — 자유 가입 열기 (아무나 가입 허용)

System Console → Site Configuration → Users and Teams → Enable Open Server → true

또는 config.json에서 "EnableOpenServer": true로 바꾼 뒤 재시작:

docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml restart mattermost

내부 팀/소규모 운영이면 방법 1(초대)이 가장 안전합니다. 공개 서비스로 열 거면 방법 3을 쓰되, 스팸 가입에 주의하세요.

4. 점검 · 운영 (선택, 필요 시)

# 컨테이너 상태
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml ps

# 로그
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml logs -f mattermost

# 재시작
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml restart mattermost

# 종료 (컨테이너 제거, 데이터 볼륨은 유지)
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml down

명령이 길어 매번 치기 번거로우면 alias를 등록해 두면 편합니다.
echo "alias mmc='docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml'" >> ~/.zshrc
source ~/.zshrc
# 이후: mmc up -d / mmc ps / mmc logs -f mattermost

요약 체크리스트

Docker Desktop (Apple Silicon) 설치 확인
docker-compose.yml의 postgres·mattermost에 platform: linux/amd64 추가 (arm64 에러 대응)
-f docker-compose.yml -f docker-compose.without-nginx.yml up -d로 실행 (8065 노출)
http://localhost:8065 접속 → 첫 계정 = 관리자
두 번째 사용자는 초대 링크 또는 System Console에서 추가 (기본값 EnableOpenServer: false)

개요