الاستضافة الذاتية والتطبيقات الأدلة التقنية

تثبيت Mattermost Team Edition مع PostgreSQL وترقيته بأمان

مساحة محادثة لفريقك على سيرفرك مع Mattermost، تبقى فيها الرسائل والملفات كاملة، فلا يحذفها حد للرسائل ولا خطة مجانية.

تثبيت Mattermost Team Edition مع PostgreSQL وترقيته بأمان

لنفرض أن نقاشات فريقك وقراراته والملفات التي يتبادلها موجودة اليوم على Slack أو Microsoft Teams، فسوف تجد أن هذا مريح جداً إلى أن تتغير الأسعار أو شروط الخطة المجانية Free Plan، أو تطلب منك سياسة مؤسستك أن تبقى المحادثات داخلها، وعندها تكتشف أن تاريخ فريقك كله محفوظ على سيرفر Server لا تملكه ولا تتحكم في مدة الاحتفاظ بما عليه.

📌
في 26 أغسطس 2024 بدأت Slack بحذف الرسائل والملفات التي مضى عليها أكثر من سنة من مساحات العمل Workspaces على الخطة المجانية، بعد أن كانت هذه الخطة تحصر البحث والعرض في آخر 90 يوماً فقط، فالفريق الذي اعتمد على الخطة المجانية لسنوات وجد أن نقاشاته القديمة وقراراته لم تعد مخفية فقط، وإنما أصبحت تحذف تباعاً. والدرس أن من يملك السيرفر هو الذي يقرر كم تبقى رسائلك، وليس أنت.

والحل الأول الذي يخطر على البال هو أن تبقى على الخدمة السحابية Cloud وتدفع الاشتراك، وهذا يعيد إليك التاريخ القديم ولكنه لا يغير الأصل، فالبيانات تبقى عند جهة أخرى والسعر يحدده غيرك. والحل الثاني هو أن تأخذ المستودع الرسمي mattermost/docker وتشغله كما هو، والمشكلة هنا أن هذا المستودع يستخدم افتراضياً الـ Docker Image الخاصة بـ Enterprise Edition، وهذه الـ Image عندما تعمل دون ترخيص License تتحول إلى خطة مجانية اسمها Mattermost Entry، وفيها ميزات أكثر ولكن مع حد قدره 10,000 رسالة على مستوى السيرفر كله، وما زاد عن ذلك يبقى في قاعدة البيانات Database ولكنه لا يظهر في القنوات ولا في البحث، والتوثيق نفسه يذكر أنها تناسب الفرق التي يقل عددها عن 50 مستخدماً.

لذلك فالحل الأنسب لفريق صغير أو متوسط يريد أن يبقى تاريخه كاملاً هو Mattermost بنسخة Team Edition، وهو منصة محادثة Chat مفتوحة المصدر Open Source تعمل بطريقة قريبة من Slack، ففيها الفرق Teams والقنوات Channels العامة Public والخاصة Private، والرسائل المباشرة Direct Messages وسلاسل الردود Threads والبحث Search في الرسائل، ولها تطبيقات لسطح المكتب Desktop والجوال Mobile، وتكاملات Integrations عبر الـ Webhooks والـ Slash Commands والـ Bots. ونسخة Team Edition مجانية ومرخصة بترخيص MIT، ولا يوجد فيها حد لعدد الرسائل، والرسائل والملفات كلها تبقى على سيرفرك.

وقد يتساءل البعض: لماذا لا أختار Entry ما دامت مجانية وفيها ميزات أكثر؟ والإجابة أن الأمر يتوقف على ما يحتاجه فريقك، فإذا كنت تحتاج تسجيل الدخول الموحد SSO المدعوم رسمياً عبر LDAP أو SAML أو OpenID Connect، أو حسابات الضيوف Guest Accounts، فهذه غير موجودة في Team Edition، حيث أعلنت Mattermost إزالة الدخول عبر GitLab منها في الإصدار 11.0، وتوقفت فيها Playbooks أيضاً، والتوثيق يحددها لفرق يقل عدد مستخدميها المفعلين Activated Users عن 250 ولا تحتاج SSO. ولكن مزود GitLab ما زال يعمل في كود السيرفر دون واجهة، وسوف نشرح في قسم الدخول الموحد أدناه كيف نستخدمه مع authentik وما حدود ذلك. وأما إذا كان المهم عندك أن يبقى تاريخ المحادثات كاملاً ويمكن البحث فيه، فـ Team Edition هي الخيار الصحيح، وهي التي سوف نستخدمها في هذا الدليل. ومتطلبات الامتثال Compliance المتقدمة، مثل eDiscovery وسياسات الاحتفاظ بالرسائل Message Retention، موجودة في الخطط المدفوعة Paid Plans فقط.

وسوف نناقش في هذا المقال ما يلي:

  • تثبيت Mattermost Team Edition باستخدام Docker Compose مع PostgreSQL، وشرح الأسطر المهمة في الملف.
  • ربط النطاق Domain مع شهادة TLS عبر الـ Reverse Proxy، وإنشاء أول مدير وأول فريق.
  • أهم إعدادات System Console: العنوان Site URL والبريد SMTP وتخزين الملفات File Storage والتسجيل Signup.
  • الدخول الموحد SSO في Team Edition عبر مزود GitLab مع authentik، وحدود هذه الطريقة.
  • تفعيل المكالمات Calls وفتح المنفذ 8443 وضبط ICE Host Override، وما تسمح به النسخة المجانية.
  • إرسال تنبيهات من أنظمتك عبر Incoming Webhook، ثم النسخ الاحتياطي Backup والاستعادة Restore.
  • الفرق بين إصدارات الدعم الممتد ESR والإصدارات الشهرية، والتحديث Upgrade بأمان، وأشهر المشكلات وحلولها.

ما تحتاجه قبل أن تبدأ Requirements

  • سيرفر Linux، ومتطلبات العتاد Hardware الرسمية تذكر أن سيرفراً واحداً بمعالج 1 vCPU وذاكرة RAM بحجم 2 GB يكفي حتى 1,000 مستخدم مسجل، ومعالجين 2 vCPU و4 GB من 1,000 إلى 2,000 مستخدم، ولأن PostgreSQL سوف تعمل على نفس السيرفر فاجعل الذاكرة 4 GB إذا استطعت. وأما المساحة Storage فتكفي 10 GB للبداية، وتزيد الحاجة مع الملفات المرفقة Attachments.
  • Docker Engine مع Compose v2، وإذا لم يكن مثبتاً فاتبع دليل تثبيت Docker.
  • نطاق فرعي Subdomain مثل chat.example.com يشير إلى السيرفر، وReverse Proxy يصدر شهادة TLS Certificate ويدعم WebSocket، مثل Nginx Proxy Manager.
  • حساب SMTP للإشعارات Notifications ودعوات Invitations المستخدمين واستعادة كلمات المرور Password Reset.
  • المنفذ Port رقم 8443 (UDP وTCP)، وتحتاجه فقط للمكالمات الصوتية والمرئية Voice and Video Calls عبر إضافة Plugin اسمها Calls، ولاحظ أن Team Edition تسمح بمكالمات ثنائية 1:1 ومشاركة الشاشة Screen Sharing لمدة أقصاها 40 دقيقة، وأما المكالمات الجماعية Group Calls فهي في الخطط المدفوعة، والتفصيل في قسم المكالمات أدناه.

تثبيت Mattermost خطوة بخطوة Installation

مجلد التثبيت وملف .env

أول خطوة هي أن ننشئ مجلداً للتثبيت:

sudo mkdir -p /opt/mattermost
cd /opt/mattermost

ثم نضع فيه ملف .env يحمل رقم الإصدار Version وكلمة مرور قاعدة البيانات، والسبب أننا لا نريد أن نكتب كلمة المرور داخل ملف Compose نفسه فتظهر في كل نسخة منه، ولذلك نولدها عشوائياً ونجعل الملف مقروءاً للمالك فقط:

cat > .env <<EOF
MM_TAG=11.11.1
POSTGRES_PASSWORD=$(openssl rand -hex 24)
EOF
chmod 600 .env

والإصدار 11.11.1 هو أحدث إصدار مستقر Stable Release حتى كتابة هذا الدليل، وهو من الإصدارات الشهرية Feature Releases، وأما إذا كنت تفضل أن تحدث السيرفر مرات أقل فاختر إصدار الدعم الممتد ESR، والتفصيل في قسم التحديث أدناه.

ملف docker-compose.yml وشرح ما فيه

هذا الملف مبني على المستودع الرسمي mattermost/docker مع بعض التعديلات التي سوف نشرحها بعد الملف، وتجد طريقة التثبيت الرسمية في دليل التثبيت عبر Containers. والملف سوف يكون كما يلي:

services:
  postgres:
    image: postgres:18.6-alpine
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    environment:
      POSTGRES_USER: mmuser
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}
      POSTGRES_DB: mattermost
      TZ: UTC
    volumes:
      # PostgreSQL 18 يحفظ بياناته تحت /var/lib/postgresql/18/docker
      - db:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mmuser -d mattermost"]
      interval: 10s
      timeout: 5s
      retries: 10

  mattermost:
    image: mattermost/mattermost-team-edition:${MM_TAG}
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      TZ: UTC
      MM_SQLSETTINGS_DRIVERNAME: postgres
      MM_SQLSETTINGS_DATASOURCE: postgres://mmuser:${POSTGRES_PASSWORD}@postgres:5432/mattermost?sslmode=disable&connect_timeout=10
      MM_SERVICESETTINGS_SITEURL: https://chat.example.com
      # يسمح بـ mmctl --local من داخل الـ Container (ويستخدمه الـ Healthcheck المدمج في الـ Image)
      MM_SERVICESETTINGS_ENABLELOCALMODE: "true"
    ports:
      - "127.0.0.1:8065:8065"
      # للمكالمات فقط (إضافة Calls)
      # - "8443:8443/udp"
      # - "8443:8443/tcp"
    volumes:
      - config:/mattermost/config
      - data:/mattermost/data
      - logs:/mattermost/logs
      - plugins:/mattermost/plugins
      - client-plugins:/mattermost/client/plugins
    networks:
      - default
      - proxy

volumes:
  db:
  config:
  data:
  logs:
  plugins:
  client-plugins:

networks:
  proxy:
    external: true

في الإعداد أعلاه لاحظ التالي:

  • الـ Image هي mattermost/mattermost-team-edition وليست mattermost-enterprise-edition التي يستخدمها المستودع الرسمي افتراضياً، والسبب هو حد الرسائل في Entry الذي شرحناه في البداية.
  • استخدمنا Volumes مسماة Named Volumes بدل المجلدات المربوطة Bind Mounts، والسبب أن Mattermost يعمل داخل الـ Container بالمستخدم UID 2000، والمستودع الرسمي يطلب منك لذلك أن تنفذ chown -R 2000:2000 على المجلدات قبل التشغيل، أما الـ Volume الجديد فيأخذ ملكية المجلد الموجود داخل الـ Image تلقائياً، فلا تحتاج إلى هذه الخطوة.
  • حذفنا الـ Volume الخاص بـ bleve-indexes والمتغير MM_BLEVESETTINGS_INDEXDIR الموجودين في المستودع الرسمي، والسبب أن Mattermost أزال البحث عبر Bleve في الإصدار 11.0، وأصبح البحث يعمل من قاعدة البيانات مباشرة.
  • منفذ الويب مربوط بالعنوان 127.0.0.1 فقط، والسبب أن الـ Reverse Proxy وحده هو الذي يصل إليه عبر الشبكة proxy، فلا يستطيع أحد أن يتجاوز شهادة TLS ويفتح Mattermost مباشرة على المنفذ 8065.
  • الصيغة ${POSTGRES_PASSWORD:?} تجعل Compose يتوقف برسالة خطأ إذا لم يجد المتغير في ملف .env، بدل أن يشغل قاعدة البيانات بكلمة مرور فارغة، والشرط service_healthy يجعل Mattermost ينتظر حتى تصبح PostgreSQL جاهزة فعلاً.
  • الـ Image الخاصة بـ PostgreSQL 18 تحفظ بياناتها تحت /var/lib/postgresql وليس /var/lib/postgresql/data كما في الإصدارات السابقة، ولذلك ربطنا الـ Volume بهذا المسار، والإصدار 18 مدعوم لأن الحد الأدنى في Mattermost هو PostgreSQL 14، ويصبح 15 بدءاً من الإصدار 12.0.

وكل إعداد في System Console تستطيع تثبيته بمتغير بيئة Environment Variable بحروف كبيرة على الصيغة MM_<SECTION>_<SETTING>، مثل MM_SERVICESETTINGS_SITEURL، كما في صفحة إعدادات التهيئة Configuration Settings، وعندها يظهر الإعداد في الواجهة Web UI مقفلاً Locked، وبجانبه العبارة «This setting has been set through an environment variable»، لذلك استخدم هذه الطريقة للقيم التي لا تريد أن يغيرها أحد من الواجهة.

ويجدر الإشارة هنا إلى أن التوثيق الرسمي يصنف التثبيت عبر Docker للتجربة والتطوير، والسبب أنه لا يدعم التشغيل على عدة سيرفرات Cluster ولا التوافرية Availability العالية High Availability، ويوصي بـ Kubernetes لمن يحتاجها. وهذا لا يمنعك من تشغيله لفريقك على سيرفر واحد، ولكن تذكر أن أي تحديث أو عطل في السيرفر يعني توقف المحادثات لدقائق.

تشغيل الخدمات Services

الآن سوف نقوم بإنشاء الشبكة المشتركة مع الـ Reverse Proxy، ثم تشغيل الخدمتين ومتابعة السجلات Logs:

docker network create proxy
docker compose up -d
docker compose logs -f mattermost

وإذا كانت الشبكة موجودة من قبل فسوف يفشل الأمر الأول برسالة أنها موجودة، وهذا لا يضر بشيء. وفي الـ Image فحص صحة Healthcheck مدمج يعتمد على الأمر mmctl system status --local، لذلك انتظر حتى يظهر الـ Container بالحالة healthy في مخرجات Output الأمر docker compose ps، ثم تحقق بهذا الأمر:

curl -s http://127.0.0.1:8065/api/v4/system/ping

والمخرج سوف يكون رداً Response فيه "status":"OK".

ربط النطاق Domain وشهادة TLS عبر الـ Reverse Proxy

في Nginx Proxy Manager أضف مضيفاً Proxy Host للنطاق chat.example.com يوجه الطلبات Requests إلى الـ Container الخاص بـ mattermost على المنفذ 8065، وفعل Websockets Support، والسبب أن الرسائل الفورية Real-time Messages تمر عبر WebSocket، فإذا لم تفعله فلن تظهر الرسائل إلا بعد تحديث الصفحة. ثم اطلب شهادة Let's Encrypt مع Force SSL، وقم بزيادة حد الرفع Upload Limit في الإعدادات المتقدمة Advanced ليطابق حد الملفات في Mattermost، وهو 100 MB افتراضياً (راجع توثيق client_max_body_size ودليل إعداد NGINX لـ Mattermost):

client_max_body_size 100m;
proxy_read_timeout 600s;

وإذا كنت تستخدم Caddy فيكفي هذا:

chat.example.com {
    reverse_proxy mattermost-mattermost-1:8065
}

والسبب أن التوجيه Directive reverse_proxy في Caddy يمرر اتصالات WebSocket تلقائياً. وفي الحالتين تأكد أن قيمة MM_SERVICESETTINGS_SITEURL تطابق العنوان العام Public URL تماماً، وإلا فسوف تتعطل الروابط في الإشعارات ويفشل تسجيل الدخول Login من التطبيقات.

إنشاء أول مدير Admin وأول فريق

افتح https://chat.example.com/ واختر View in Browser، وتذكر أن أول حساب تنشئه يصبح مدير النظام System Admin، لذلك أنشئه فور التشغيل وقبل أن تنشر الرابط لأي أحد.

صفحة Create your account في Mattermost Team Edition مع البريد واسم المستخدم mmadmin
إنشاء الحساب الأول، وهو مدير النظام تلقائياً

بعد ذلك يطلب منك المعالج Wizard اسم المؤسسة، وينشئ به أول فريق Team مع قناتيه الافتراضيتين Town Square وOff-Topic، ثم يعرض عليك تكاملات اختيارية مثل GitHub وGitLab وJira وتستطيع تخطيها.

شاشة What's the name of your organization في معالج Mattermost مع اسم Example Engineering
يصبح اسم المؤسسة اسماً لأول فريق

أهم الإعدادات في System Console

افتح System Console من قائمة المنتجات Product Menu، وهي أيقونة المربعات في أعلى اليسار، وفيما يلي أهم الإعدادات بعد التثبيت.

العنوان العام Site URL

هذا الإعداد في Environment ← Web Server، وسوف تجده مقفلاً لأننا ضبطناه بمتغير بيئة، فاضغط Test Live URL لتتأكد أن العنوان يعمل.

صفحة Web Server في System Console مع Site URL مقفلاً لأنه مضبوط بمتغير بيئة
Site URL مضبوط بمتغير البيئة (العنوان في الصورة محلي)

إعداد البريد SMTP

في Environment ← SMTP أدخل عنوان سيرفر البريد والمنفذ، وفعل Enable SMTP Authentication مع اسم المستخدم Username وكلمة المرور، ثم اختر Connection Security: إما STARTTLS على المنفذ 587 أو TLS على المنفذ 465. واحفظ الإعدادات قبل أن تضغط على Test Connection، والسبب أن الاختبار يستخدم الإعدادات المحفوظة وليس ما كتبته في الحقول.

صفحة SMTP في System Console مع الخادم والمنفذ ورسالة نجاح اختبار الاتصال
نجاح اختبار SMTP

بعد ذلك فعل الإشعارات من Site Configuration ← Notifications، حيث تجعل Enable Email Notifications = true، وتضبط Notification From Address (مثل [email protected]) واسم المرسل. وتستطيع أيضاً تثبيت إعدادات البريد بمتغيرات البيئة كما يلي:

      MM_EMAILSETTINGS_SMTPSERVER: smtp.example.com
      MM_EMAILSETTINGS_SMTPPORT: "587"
      MM_EMAILSETTINGS_ENABLESMTPAUTH: "true"
      MM_EMAILSETTINGS_SMTPUSERNAME: [email protected]
      MM_EMAILSETTINGS_SMTPPASSWORD: ${SMTP_PASSWORD}
      MM_EMAILSETTINGS_CONNECTIONSECURITY: STARTTLS
      MM_EMAILSETTINGS_SENDEMAILNOTIFICATIONS: "true"
      MM_EMAILSETTINGS_FEEDBACKEMAIL: [email protected]

ونجاح الاختبار يعني أن Mattermost وصل إلى سيرفر البريد، وأما وصول الرسائل إلى صناديق البريد الحقيقية دون أن تذهب إلى الرسائل المزعجة Spam فيتوقف على مزود البريد Email Provider وعلى سجلات Records من نوع SPF وDKIM في النطاق كما شرحنا في شرح SPF وDKIM وDMARC للمبتدئين، لذلك أرسل دعوة إلى بريد تجريبي وتأكد أنها وصلت.

تخزين الملفات File Storage

الخيار الافتراضي في Environment ← File Storage هو Local File System في المسار ./data/، أي في الـ Volume المسمى data، وهو مناسب لسيرفر واحد. وإذا قمت بتعديل Maximum File Size فعدل حد الـ Reverse Proxy معه، وإلا فسوف يرفض الـ Reverse Proxy الملف قبل أن يصل إلى Mattermost.

وإذا كان لديك تخزين متوافق مع S3 (S3-compatible)، مثل MinIO أو خدمة سحابية، فاختر Amazon S3 وأدخل الـ bucket والمفاتيح Access Keys والـ endpoint، وعندها يصبح الـ bucket هو ما تنسخه احتياطياً بدل الـ Volume المسمى data.

صفحة File Storage في System Console مع Local File System ومجلد ./data/ والحد الأقصى 100 ميغابايت
التخزين المحلي للملفات والحد الأقصى لحجم المرفق

التسجيل Signup ودعوة الزملاء

في Authentication ← Signup اترك Enable Open Server معطلاً كما هو افتراضياً، والسبب أن تفعيله يسمح لأي شخص يصل إلى الرابط بإنشاء حساب، وقيد Restrict new system and team members to specified email domains بنطاق مؤسستك، ثم ادع زملاءك من قائمة الفريق ← Invite People.

الدخول الموحد SSO في النسخة المجانية عبر مزود GitLab مع authentik

لنفرض أن حسابات فريقك موجودة في authentik، ومعها المصادقة الثنائية MFA وسياسات الدخول، فسوف تجد أن إنشاء كلمة مرور جديدة لكل موظف في Mattermost يعيدك إلى المشكلة التي ثبت authentik من أجلها، وهي حسابات متفرقة لا تغلقها من مكان واحد عندما يغادر الموظف. والحل المعتاد هو أن تربط التطبيق عبر OpenID Connect أو SAML، ولكن Team Edition لا تدعم أياً منهما، ولا تدعم LDAP أيضاً، فكلها في Entry والخطط المدفوعة.

والحل الذي يعمل في Team Edition هو مزود GitLab نفسه، والسبب أن هذا المزود في الكود هو OAuth 2.0 عادي بثلاثة عناوين Endpoints يمكن ضبطها: عنوان التفويض Authorization Endpoint الذي يرسل إليه المستخدم ليسجل دخوله، وعنوان الرمز Token Endpoint الذي يستبدل فيه Mattermost الرمز Code بتوكن Access Token، وعنوان بيانات المستخدم User API Endpoint الذي يقرأ منه JSON فيه الحقول id وusername وemail وname كما يرسلها GitLab. وMattermost لا يتحقق من أن الطرف الآخر هو GitLab فعلاً، وبالتالي إذا جعلنا authentik يرد على العنوان الثالث بنفس الشكل فسوف يقبله Mattermost على أنه GitLab، وهذه هي الطريقة التي يشرحها دليل التكامل الرسمي في authentik لـ Mattermost Team Edition، وهو مصنف عندهم بمستوى دعم Community. وإذا أردت أن تفهم الفرق بين OAuth 2.0 وOpenID Connect قبل أن تبدأ فقد شرحناه في شرح OAuth وOpenID Connect للمبتدئين، والصورة التالية تبين مسار الدخول:

مسار الدخول من المتصفح إلى Mattermost ثم إلى authentik عبر authorize والعودة إلى signup/gitlab/complete ثم تبادل الرمز وقراءة userinfo بين السيرفرين
authentik يرد على عناوين مزود GitLab في Mattermost
⚠️
قبل أن تعتمد على هذه الطريقة اعرف وضعها الرسمي: في الإصدار 11.0 أعلنت Mattermost إزالة GitLab SSO من Team Edition، وصفحة GitLab SSO في التوثيق تذكر أنه متاح في Entry والخطط المدفوعة فقط. ولكن التعديل الذي نفذ ذلك كان في الواجهة: حذف صفحة GitLab من System Console، وأوقف إرسال الإعداد EnableSignUpWithGitLab إلى الواجهة دون ترخيص، فاختفى الزر من صفحة الدخول، أما المزود ومسارات OAuth فما زالت في كود السيرفر حتى الإصدار 11.11.1. وهذا يعني أن الطريقة تعمل اليوم ولكنها غير مدعومة رسمياً، وقد تتوقف في أي تحديث، لذلك احتفظ بحساب المدير بالبريد وكلمة المرور، واقرأ ملاحظات كل إصدار قبل أن تحدث، وإذا كان الدخول الموحد شرطاً أساسياً عندك فالخيار المدعوم هو Entry أو خطة مدفوعة.

الإعداد في authentik

لن نعيد هنا شرح تثبيت authentik، فقد شرحناه في دليل تثبيت authentik، وشرحنا إنشاء تطبيق OAuth2 بالتفصيل مع الصور في ربط Gitea مع authentik، وإذا أردت أن يدخل الموظف بحساب Google فراجع تسجيل الدخول بحساب Google في authentik. وما يختلف في Mattermost هو خطوتان.

الخطوة الأولى: ربط الخصائص Property Mapping. نقطة userinfo الافتراضية في authentik ترسل المعرف في الحقل sub كنص، ولا ترسل الحقل id الذي ينتظره مزود GitLab في Mattermost، والكود يرفض المستخدم إذا كان id صفراً أو كان البريد فارغاً، لذلك افتح Customization ← Property Mappings ← Create واختر Scope Mapping، واجعل الاسم mattermost-read-user واسم النطاق Scope Name read_user، والتعبير Expression كما في الدليل الرسمي:

username = request.user.username
return {
    "id": request.user.pk,
    "username": username,
    "login": username,
    "preferred_username": username,
    "email": request.user.email,
    "name": request.user.name or username,
}

والقيمة request.user.pk هي الرقم الداخلي للمستخدم في authentik، وهو ثابت لا يتغير إذا غير المستخدم اسمه أو بريده، ولذلك يحفظه Mattermost في الحقل AuthData ويتعرف به على المستخدم في كل دخول. ولاحظ أن كل مستخدم يجب أن يكون له بريد في authentik، وإلا فسوف يرفضه Mattermost.

الخطوة الثانية: التطبيق والمزود Application and Provider. افتح Applications ← Applications ← New Application، واختر OAuth2/OpenID Provider بنوع العميل Client Type Confidential، ثم:

  • Advanced protocol settings ← Scopes: أبق openid وأضف mattermost-read-user الذي أنشأناه.
  • انسخ Client ID وClient Secret، وسوف نضعهما في ملف .env.
  • في إعدادات التطبيق Application ضع في Launch URL العنوان https://chat.example.com/oauth/gitlab/login، والسبب سوف تجده في القسم التالي.

Redirect URIs: أضف العنوانين التاليين بنوع Strict وAuthorization كما في الدليل الرسمي:

https://chat.example.com/login/gitlab/complete
https://chat.example.com/signup/gitlab/complete

والعنوان الذي يرسله Mattermost فعلياً في الكود هو الثاني /signup/gitlab/complete، سواءً كان المستخدم جديداً أو قديماً، لذلك لا تحذفه.

الإعداد في Mattermost بمتغيرات البيئة Environment Variables

في الإصدارات حتى 10.11 كان هذا الإعداد في System Console ← Authentication ← GitLab، أما في الإصدار 11 فلم تعد هذه الصفحة متاحة للضبط في Team Edition، والدليل الرسمي في authentik يضبطه في الملف config.json تحت المفتاح GitLabSettings. ونحن سوف نضبطه بمتغيرات البيئة لأن كل مفتاح في config.json له متغير يقابله كما ذكرنا في شرح ملف Compose، وأسماؤها في صفحة إعدادات المصادقة Authentication Configuration Settings. الآن سوف نضيف المعرف والسر إلى ملف .env وليس إلى ملف Compose، حتى لا يظهر السر في كل نسخة من الملف:

cat >> .env <<'EOF'
GITLAB_SSO_CLIENT_ID=paste-client-id-here
GITLAB_SSO_CLIENT_SECRET=paste-client-secret-here
EOF

ثم نضيف هذه الأسطر إلى قسم environment في الخدمة mattermost:

      # الدخول الموحد عبر authentik في دور مزود GitLab
      MM_GITLABSETTINGS_ENABLE: "true"
      MM_GITLABSETTINGS_ID: ${GITLAB_SSO_CLIENT_ID:?}
      MM_GITLABSETTINGS_SECRET: ${GITLAB_SSO_CLIENT_SECRET:?}
      # يبقى فارغاً، فإذا احتوى openid انتقل Mattermost إلى مزود OpenID غير الموجود في Team Edition
      MM_GITLABSETTINGS_SCOPE: ""
      MM_GITLABSETTINGS_AUTHENDPOINT: https://auth.example.com/application/o/authorize/
      MM_GITLABSETTINGS_TOKENENDPOINT: https://auth.example.com/application/o/token/
      MM_GITLABSETTINGS_USERAPIENDPOINT: https://auth.example.com/application/o/userinfo/

ثم نعيد إنشاء الـ Container بالأمر docker compose up -d mattermost. في الإعداد أعلاه لاحظ التالي:

  • العناوين الثلاثة هي العناوين العامة لـ authentik، وتجدها في صفحة المزود Provider، وهي واحدة لكل التطبيقات في authentik، والذي يميز Mattermost عن غيره هو الـ Client ID.
  • العنوانان الثاني والثالث يتصل بهما سيرفر Mattermost نفسه وليس المتصفح، لذلك يجب أن يصل الـ Container إلى auth.example.com عبر HTTPS بشهادة صالحة، فإذا كان authentik على نفس السيرفر فتأكد أن النطاق يحل من داخل الـ Container إلى عنوان يصل إليه.
  • الحقل Scope فارغ كما يطلب الدليل الرسمي، والسبب في الكود أن Mattermost إذا وجد الكلمة openid فيه يتحول إلى مزود OpenID Connect، وهذا غير موجود في Team Edition فيفشل الدخول بالرسالة «Gitlab SSO through OAuth 2.0 not available on this server». وعندما يكون الحقل فارغاً يعطي authentik النطاقات التي اخترتها في المزود.
  • الصيغة ${GITLAB_SSO_CLIENT_SECRET:?} تجعل Compose يتوقف برسالة خطأ إذا نسيت السر في .env، كما فعلنا مع كلمة مرور قاعدة البيانات.

وقد يتساءل البعض: أين زر الدخول عبر authentik في صفحة الدخول؟ والإجابة أنه لن يظهر في الإصدار 11، لأن السيرفر لم يعد يرسل الإعداد EnableSignUpWithGitLab إلى الواجهة دون ترخيص، ولكن المسار نفسه يعمل، فالمستخدم يفتح الرابط https://chat.example.com/oauth/gitlab/login فيرسله Mattermost إلى authentik ثم يعود مسجلاً. ولهذا وضعنا هذا الرابط في Launch URL، فيضغط الموظف على أيقونة Mattermost في صفحة التطبيقات في authentik ويدخل مباشرة، وتستطيع أيضاً أن تضعه في رسالة الترحيب أو في مفضلة المتصفح Bookmark.

حدود الدخول عبر مزود GitLab

  • الحساب يسجل على أنه حساب GitLab: يحفظ Mattermost طريقة الدخول gitlab لكل حساب ينشأ بهذه الطريقة، ولا توجد للحساب كلمة مرور في Mattermost، فالدخول يكون عبر authentik فقط.
  • تطبيق الجوال Mobile App: يبني شاشة الدخول من نفس الإعداد EnableSignUpWithGitLab، فلا يظهر فيه خيار GitLab، وبالتالي لا يستطيع مستخدم SSO أن يدخل من تطبيق الجوال، أما المتصفح على الجوال فيعمل بالرابط المباشر.
  • الحسابات الموجودة بالبريد وكلمة المرور: إذا كان في Mattermost حساب بنفس البريد أنشئ بالبريد وكلمة المرور فسوف يرفض الدخول بالرسالة «There is already an account associated with that email address using a sign in method other than gitlab»، والتوثيق يذكر أن المستخدم يجب أن يغير طريقة دخوله أولاً، ولكن خيار التغيير في إعدادات الأمان Security يعتمد على نفس الإعداد المخفي، لذلك فعل الدخول الموحد قبل أن تدعو زملاءك، واجعل حساب البريد للمدير فقط.
  • الفرق Teams: المستخدم الجديد لا يضاف إلى أي فريق تلقائياً، فإما أن تفعل في إعدادات الفريق Allow any user with an account on this server to join this team فيختار الفريق بنفسه، أو أن تضيفه أنت، وتأكد أن Enable Account Creation في Authentication ← Signup مفعل لأن Mattermost يرفض إنشاء الحساب إذا كان معطلاً.
  • تعطيل الموظف Deactivation: إذا عطلت الحساب في authentik فلن يستطيع أن يسجل دخولاً جديداً، ولكن الجلسة Session المفتوحة في Mattermost تبقى إلى أن تنتهي مدتها حسب مدة جلسات SSO في Environment ← Session Lengths، لذلك عطل الحساب في Mattermost أيضاً من User Management ← Users، والتفصيل في إدارة الهوية والوصول IAM.

تفعيل المكالمات الصوتية والمرئية Calls

إضافة Calls مدمجة في Team Edition، والإصدار 11.11.1 يأتي بالإصدار v1.12.3 منها، وهي تعمل في الوضع المدمج Integrated Mode داخل سيرفر Mattermost نفسه، ودليل نشر Calls يذكر أن هذا الوضع يكفي للتجربة وللتثبيتات التي يقل عدد مستخدميها عن 50، ويوصي بخدمة RTCD المنفصلة للإنتاج Production فوق ذلك. وقد يتساءل البعض: إذا كان Mattermost يعمل خلف الـ Reverse Proxy على المنفذ 443، فلماذا يحتاج منفذاً آخر للمكالمات؟ والإجابة أن الانضمام إلى المكالمة Signaling يمر عبر WebSocket على المنفذ 443 كبقية الرسائل، أما الصوت Media فيذهب مباشرة إلى المنفذ 8443 بروتوكول UDP، والسبب أن الصوت يحتاج إلى أقل تأخير Latency ممكن، والـ Reverse Proxy الذي يمرر HTTP لا يمرر هذه الحركة، فإذا كان UDP محجوباً يحاول العميل TCP على نفس المنفذ، والصورة التالية تبين ذلك:

الإشارات تمر عبر المنفذ 443 والـ Reverse Proxy إلى Mattermost، والصوت يمر مباشرة إلى المنفذ 8443 UDP مع TCP احتياطي، وMattermost يعلن عنوان ICE Host Override للعميل
الإشارات عبر الـ Reverse Proxy، والصوت مباشرة إلى المنفذ 8443

ما الذي تسمح به Team Edition

  • المكالمات الثنائية 1:1 في الرسائل المباشرة Direct Messages مع مشاركة الشاشة Screen Sharing، ودليل النشر يحدد مدتها في Entry وTeam بـ 40 دقيقة.
  • المكالمات الجماعية Group Calls في القنوات والرسائل الجماعية تحتاج Professional على الأقل، وتوقف دعمها في السيرفرات دون ترخيص منذ الإصدار 10.0.
  • تسجيل المكالمات Recording والتفريغ النصي Transcription والترجمة الفورية Live Captions تحتاج Enterprise مع خدمة calls-offloader، فلا تبحث عنها في Team Edition.
  • الفيديو Video بالكاميرا تجريبي Experimental منذ الإصدار v1.12.0 من الإضافة، وهو في الرسائل المباشرة فقط ومن المتصفح وتطبيق سطح المكتب، ومعطل افتراضياً، وتفعله من Enable video calls in DMs (Experimental) أو بالمتغير MM_CALLS_ENABLE_VIDEO.

فتح المنفذ وضبط عنوان ICE Host Override

أول خطوة هي أن تزيل علامة التعليق Comment من سطري المنفذ 8443 في ملف docker-compose.yml كما في المستودع الرسمي، ثم تضيف عنوانك العام إلى ملف .env:

echo 'CALLS_PUBLIC_HOST=203.0.113.10' >> .env

ثم تضيف إعدادات الإضافة إلى قسم environment في الخدمة mattermost، وأسماؤها في صفحة إعدادات الإضافات Plugins Configuration Settings:

    environment:
      # ...
      MM_CALLS_UDP_SERVER_PORT: "8443"
      MM_CALLS_TCP_SERVER_PORT: "8443"
      MM_CALLS_ICE_HOST_OVERRIDE: ${CALLS_PUBLIC_HOST:?}
    ports:
      - "127.0.0.1:8065:8065"
      - "8443:8443/udp"
      - "8443:8443/tcp"

ثم نفذ docker compose up -d mattermost، وتستطيع أن ترى الإعدادات نفسها وتعدلها من الواجهة في System Console ← Plugins ← Calls، حيث تجد Enable Plugin وهو مفعل افتراضياً، وRTC Server Port (UDP) وRTC Server Port (TCP) وقيمتهما الافتراضية 8443، وICE Host Override. في الإعداد أعلاه لاحظ التالي:

  • داخل Docker يرى Mattermost عنوان الـ Container الداخلي مثل 172.18.0.3، وإذا أعلن هذا العنوان للعميل فلن يصل إليه أحد من الإنترنت، ولذلك نضبط ICE Host Override بالعنوان العام Public IP للسيرفر، أو باسم نطاق DNS يشير إليه، والتوثيق يوصي بعنوان ثابت لمن يصل من الإنترنت، ويذكر أن تركه فارغاً يجعل الإضافة تكتشف العنوان العام عبر سيرفر STUN الخاص بـ Mattermost، وهذا يناسب العناوين المتغيرة.
  • إذا استخدمت اسم نطاق فاجعله سجلاً يشير إلى السيرفر مباشرة ولا يمر عبر Proxy مثل Cloudflare، والسبب أن هذا الـ Proxy يمرر حركة HTTP فقط ولا يمرر UDP على المنفذ 8443.
  • المنفذ 8443 مفتوح على كل العناوين وليس على 127.0.0.1 مثل منفذ الويب، والسبب أن العملاء يتصلون به مباشرة دون الـ Reverse Proxy، وهذا المنفذ لا يخدم إلا حركة المكالمات.

بعد ذلك افتح المنفذ 8443 بنوعيه UDP وTCP في جدار الحماية Firewall عند مزود السيرفر، وإذا كان السيرفر في البيت خلف الراوتر Router فأضف قاعدة توجيه المنافذ Port Forwarding كما شرحنا في فتح المنافذ في الـ Router، وإذا لم تكن فكرة الترجمة بين العنوان العام والعنوان الداخلي واضحة فراجع شرح NAT للمبتدئين. ولاحظ أنك إذا كنت خلف CGNAT أو تنشر Mattermost عبر نفق يمرر HTTP فقط مثل Cloudflare Tunnel، فلن تستطيع أن تفتح هذا المنفذ، وعندها تحتاج إلى سيرفر TURN يمرر الصوت أو إلى VPS بعنوان عام.

كيف تختبر المكالمة Call

  1. افتح رسالة مباشرة مع زميل، أو مع حساب ثان في متصفح آخر، واضغط زر Start call في رأس القناة Channel Header، أو اكتب الأمر /call start.
  2. اجعل الطرف الثاني على شبكة مختلفة، مثل جوال على شبكة 4G وليس على نفس الشبكة المحلية LAN، والسبب أن المكالمة داخل الشبكة نفسها قد تنجح حتى لو كان المنفذ مغلقاً من الخارج.
  3. تحدث وتأكد أن الصوت يصل في الاتجاهين، ثم جرب مشاركة الشاشة من المتصفح أو تطبيق سطح المكتب.
  4. أثناء المكالمة اكتب الأمر /call stats، فيعرض لك معلومات التشخيص Diagnostics عن الاتصال.

إرسال رسائل من أنظمتك عبر Incoming Webhooks

الـ Incoming Webhook هو أبسط أنواع التكامل، وهو عنوان سري Secret URL يستقبل بيانات JSON وينشرها رسالة في قناة، وبالتالي فهو مناسب لتنبيهات Alerts الـ CI/CD والمراقبة Monitoring والنسخ الاحتياطي. تأكد أولاً أن Integrations ← Integration Management ← Enable Incoming Webhooks مفعل، وهو مفعل افتراضياً، ثم افتح من قائمة الفريق Integrations ← Incoming Webhooks ← Add Incoming Webhook:

نموذج إضافة Incoming Webhook بعنوان CI notifications وقناة Town Square
إنشاء webhook وارد وربطه بقناة

فعل Lock to this channel، والسبب أن الـ Webhook دون هذا الخيار يستطيع النشر في أي قناة يكون منشئه عضواً فيها إذا أرسل الحقل channel. وبعد الحفظ تحصل على عنوان مثل https://chat.example.com/hooks/xxxxxxxxxxxxxxxxxxxxxxxxxx، فاحمه كما تحمي كلمة المرور، لأن كل من يعرفه يستطيع النشر في قناتك. الآن سوف نرسل رسالة، والنص يدعم Markdown والجداول Tables:

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"text":"#### :white_check_mark: Build succeeded\n| Repository | Branch | Commit |\n|:--|:--|:--|\n| gitadmin/demo-app | main | 59d070b9 |\n[Open the run](https://git.example.com/gitadmin/demo-app/actions/runs/2)"}' \
  https://chat.example.com/hooks/xxxxxxxxxxxxxxxxxxxxxxxxxx

والمخرج سوف يكون كلمة ok مع رمز الحالة Status Code رقم 200، والرسالة تظهر في القناة كما يلي:

رسالة Build succeeded مع جدول المستودع والفرع والـ commit في قناة Town Square
الرسالة كما وصلت عبر الـ webhook

ولاحظ أن Mattermost يتجاهل الحقلين username وicon_url في الـ JSON إلا إذا فعلت Enable integrations to override usernames وprofile picture icons في Integration Management، ولذلك تظهر الرسالة باسم منشئ الـ Webhook مع شارة Badge مكتوب فيها BOT.

وفي Gitea Actions (راجع دليل Gitea Actions) احفظ الرابط في سر Secret، واستدعه في الخطوة Step الأخيرة مع if: always() حتى يصلك التنبيه سواءً نجح البناء أو فشل.

كيف تتأكد أن كل شيء يعمل Verification

  • الأمر docker compose ps يعرض الـ Containers الاثنين بالحالة healthy.
  • الأمر curl -s https://chat.example.com/api/v4/system/ping يعيد "status":"OK".
  • الرسائل تصل فوراً بين متصفحين Browsers دون تحديث الصفحة، وهذا يعني أن اتصال WebSocket يمر عبر الـ Reverse Proxy.
  • رفع ملف بحجم 20 MB في قناة ينجح.
  • Test Connection في إعدادات SMTP ينجح، ورسالة الدعوة تصل إلى بريد تجريبي.
  • الإصدار المتوقع يظهر في قائمة المنتجات ← About Mattermost.
  • إذا فعلت الدخول الموحد: الرابط https://chat.example.com/oauth/gitlab/login ينقلك إلى authentik ثم يعيدك مسجلاً، والحساب الجديد يحمل البريد والاسم من authentik.
  • إذا فعلت المكالمات: مكالمة في رسالة مباشرة مع جهاز على شبكة أخرى، مثل جوال على 4G، تنقل الصوت في الاتجاهين.

النسخ الاحتياطي Backup والاستعادة Restore

النسخة الكاملة تتكون من قاعدة البيانات، ففيها الرسائل والمستخدمون والقنوات، ومن الـ Volume المسمى data وفيه الملفات المرفقة، وconfig وفيه الملف config.json بكل ما ضبطته من الواجهة، وplugins وفيه الإضافات التي ثبتها من الـ Marketplace، ومعها الملفان .env وdocker-compose.yml. ولاحظ أن أسماء الـ Volumes على القرص Disk تبدأ باسم المشروع Project Name، مثل mattermost_data، والأوامر كما يلي:

cd /opt/mattermost
mkdir -p backups
docker compose exec -T postgres pg_dump -U mmuser -d mattermost -Fc > backups/mattermost-db-$(date +%F).dump
docker run --rm \
  -v mattermost_config:/v/config:ro \
  -v mattermost_data:/v/data:ro \
  -v mattermost_plugins:/v/plugins:ro \
  -v "$PWD/backups:/backup" \
  alpine:3 tar czf /backup/mattermost-files-$(date +%F).tar.gz -C /v config data plugins

ولا تحتاج إلى إيقاف Mattermost أثناء النسخ، ولكن الملفات التي ترفع في تلك اللحظة قد لا تدخل النسخة، لذلك اجعل النسخ في الليل. وفي تثبيت جديد يكون ملف pg_dump بحجم 200 KB تقريباً، وأرشيف Archive الملفات بحجم 86 MB تقريباً، ومعظمها للإضافات المدمجة، ثم انقل النسختين خارج السيرفر، لأن النسخة التي تبقى على نفس القرص تضيع معه.

الاستعادة تكون كما يلي:

cd /opt/mattermost
docker compose up -d postgres
docker compose exec -T postgres pg_restore -U mmuser -d mattermost --clean --if-exists --no-owner < backups/mattermost-db-2026-09-26.dump
docker run --rm \
  -v mattermost_config:/v/config \
  -v mattermost_data:/v/data \
  -v mattermost_plugins:/v/plugins \
  -v "$PWD/backups:/backup" \
  alpine:3 sh -c 'tar xzf /backup/mattermost-files-2026-09-26.tar.gz -C /v && chown -R 2000:2000 /v'
docker compose up -d

في الأوامر أعلاه لاحظ التالي:

  • نستعيد قاعدة البيانات بالأداة pg_restore قبل تشغيل Mattermost، والخياران --clean --if-exists يحذفان الجداول الموجودة قبل إنشائها من النسخة.
  • نعيد ضبط المالك إلى 2000:2000 بعد فك الأرشيف، والسبب أن Mattermost يعمل داخل الـ Container بالمستخدم UID 2000، فإذا بقيت الملفات باسم root فسوف يتوقف بخطأ صلاحيات Permissions.
  • الاستعادة تكون على نفس إصدار Mattermost الذي أخذت منه النسخة، ثم تحدث بعدها إذا أردت.

التحديث Upgrade إلى إصدار أحدث

تحديث Mattermost

تصدر Mattermost نوعين من الإصدارات: إصدار شهري Feature Release يدعم لمدة ثلاثة أشهر تقريباً، فالإصدار 11.11 مثلاً صدر في سبتمبر 2026 وينتهي دعمه في 15 ديسمبر 2026، وإصدار الدعم الممتد Extended Support Release واختصاراً ESR يدعم لمدة سنة تقريباً، مثل الإصدار 11.7 الذي ينتهي دعمه في 15 مايو 2027. فإذا اخترت الإصدارات الشهرية فعليك أن تحدث كل شهر أو شهرين، وأما إذا اخترت ESR فتحدث مرة في السنة من ESR إلى الذي يليه، والتوثيق يذكر أن هذا المسار مدعوم ومختبر بالكامل.

وعندما تشغل الإصدار الجديد يقوم Mattermost بترحيل Migrate قاعدة البيانات تلقائياً إلى الشكل الجديد، وبين الإصدارات الثانوية Minor Versions، مثل 11.10 إلى 11.11، يكون التحديث مباشراً، وأما إذا كنت تقفز عبر عدة إصدارات أو إلى إصدار رئيسي Major Version، مثل 11 إلى 12، فاقرأ قبله Important Upgrade Notes، والسبب أن بعض الترحيلات يأخذ وقتاً طويلاً على القواعد الكبيرة، وبعضها يحتاج خطوات يدوية، وفي الإصدار 11.0 مثلاً توقف دعم MySQL وأصبح الحد الأدنى PostgreSQL 14. والإجراء الرسمي تجده في صفحة تحديث السيرفر، وأما في Docker فالخطوات كما يلي:

  1. أنشئ نسخة احتياطية كاملة كما في القسم السابق.

تحقق من الإصدار الجديد:

curl -s "https://chat.example.com/api/v4/config/client?format=old" | grep -o '"Version":"[^"]*"'

اسحب Pull الـ Image، وأعد إنشاء الـ Container الخاص بالتطبيق وحده، وراقب السجل:

docker compose pull mattermost
docker compose up -d mattermost
docker compose logs -f mattermost

اختر الوسم Tag الجديد، وغيره في .env:

sed -i 's/^MM_TAG=.*/MM_TAG=11.11.1/' .env

وبهذه الخطوات، من 11.10.2 إلى 11.11.1، يعود الـ Container إلى الحالة healthy خلال دقيقة تقريباً، وتبقى الرسائل والـ Webhooks كما هي، وتتحدث الإضافات المدمجة تلقائياً.

نافذة About Mattermost تعرض Server Version 11.11.1 وDatabase Schema Version 213
بعد الترقية: الإصدار 11.11.1

وبعد أن تتأكد من سلامة التحديث احذف الـ Image القديمة بالأمر docker image prune. وإذا فشل التحديث فأوقف التطبيق، واستعد نسخة قاعدة البيانات، ثم ارجع إلى الوسم القديم، ولا تقم بتشغيل الإصدار القديم على قاعدة بيانات رحلها الإصدار الجديد، والسبب أن الإصدار القديم لا يعرف شكل الجداول الجديد، وفي الإصدار 11 مثلاً تغيرت طريقة تخزين كلمات المرور إلى PBKDF2، فالمستخدم الذي سجل دخوله بعد التحديث لا يستطيع الدخول إذا رجعت إلى إصدار أقدم من 11.

ويجدر بك أن تعرف أن الإصدار 12.0 مجدول في 14 أكتوبر 2026، وسوف يرفع الحد الأدنى إلى PostgreSQL 15، وهذا لا يؤثر على الملف أعلاه لأنه يستخدم PostgreSQL 18، ولكن انتظر الإصدار التصحيحي الأول منه واقرأ ملاحظاته قبل أن تنتقل إليه.

تحديث PostgreSQL إلى إصدار رئيسي جديد

تغيير وسم PostgreSQL من إصدار رئيسي إلى آخر، مثل 17 إلى 18، لا يكفي وحده، والسبب أن ملفات البيانات غير متوافقة بين الإصدارين، فسوف يتوقف الـ Container بالرسالة «database files are incompatible with server». والطريقة الآمنة كما في توثيق التحديث في PostgreSQL هي أن تفرغ Dump قاعدة البيانات كاملة، ثم تستعيدها في Volume جديد:

cd /opt/mattermost
docker compose stop mattermost
docker compose exec -T postgres pg_dumpall -U mmuser > backups/all-before-pg-upgrade.sql
docker compose rm -sf postgres
docker volume rm mattermost_db

بعد ذلك غير وسم postgres في docker-compose.yml إلى الإصدار الجديد، وانتبه إلى أن الـ Image الخاصة بـ PostgreSQL 18 تستخدم المسار /var/lib/postgresql، وليس المسار /var/lib/postgresql/data الذي استخدمته الإصدارات السابقة، ثم نفذ:

docker compose up -d postgres
docker compose exec -T postgres psql -U mmuser -d postgres < backups/all-before-pg-upgrade.sql
docker compose up -d mattermost

والرسالة «role mmuser already exists» أثناء الاستعادة طبيعية، لأن الـ Image أنشأت المستخدم عند أول تشغيل، وpg_dumpall يحفظ كلمة مرور المستخدم فتبقى مطابقة لما في .env. ولا تقم بحذف الـ Volume القديم قبل أن تتأكد أن ملف التفريغ موجود وأن حجمه منطقي.

مشكلات شائعة وحلولها Troubleshooting

يتوقف الـ Container بالخطأ «permission denied» على /mattermost/config أو data

وهذا يحدث مع المجلدات المربوطة Bind Mounts، والسبب أن Mattermost يعمل بالمستخدم UID 2000 والمجلد على السيرفر ملك لمستخدم آخر، والحل أن تنفذ sudo chown -R 2000:2000 ./volumes/app/mattermost، أو أن تستخدم Volumes مسماة كما في هذا الدليل.

لا تظهر الرسائل إلا بعد تحديث الصفحة، أو تظهر الرسالة «Cannot connect to the server»

والسبب أن اتصال WebSocket لا يمر عبر الـ Reverse Proxy، والحل أن تفعل Websockets Support في NPM، أو تتحقق من الترويستين Headers Upgrade وConnection في Nginx.

روابط الإشعارات تشير إلى localhost، أو يظهر التحذير «Site URL is not set»

والسبب أن المتغير MM_SERVICESETTINGS_SITEURL غير مضبوط أو خاطئ، فاضبطه على العنوان العام مع https، ثم نفذ docker compose up -d.

Test Connection يظهر الرسالة «Please save unsaved changes first»

والسبب أن الاختبار يستخدم الإعدادات المحفوظة، فاضغط Save أولاً ثم أعد الاختبار.

يبقى الـ Container بالحالة unhealthy مع أن الموقع يعمل

والسبب أن الـ Healthcheck في الـ Image يعتمد على mmctl --local، وهذا يحتاج MM_SERVICESETTINGS_ENABLELOCALMODE=true. ولا تقلق من تفعيله، لأن الوضع المحلي Local Mode يعمل عبر مقبس Socket من نوع Unix داخل الـ Container فقط، ولا يفتح أي منفذ خارجي.

الخطأ «413 Request Entity Too Large» عند رفع ملف

والسبب هو حد حجم الطلب في الـ Reverse Proxy، والحل أن ترفع قيمة client_max_body_size لتطابق Maximum File Size في Mattermost.

الدخول عبر authentik يظهر الرسالة «Gitlab SSO through OAuth 2.0 not available on this server»

والسبب إما أن MM_GITLABSETTINGS_ENABLE ليس true، أو أن الحقل Scope فيه الكلمة openid فانتقل Mattermost إلى مزود OpenID Connect غير الموجود في Team Edition، والحل أن تجعل MM_GITLABSETTINGS_SCOPE فارغاً ثم تنفذ docker compose up -d mattermost.

الرسالة «Could not parse auth data out of gitlab user object» بعد الدخول في authentik

والسبب أن رد userinfo لا يحمل الحقل id أو البريد، والحل أن تتأكد أن الـ Scope Mapping باسم mattermost-read-user مختار في Advanced protocol settings ← Scopes في المزود، وأن للمستخدم بريداً في authentik.

authentik يعرض «Redirect URI Error»

والسبب أن العنوان الذي أرسله Mattermost لا يطابق ما في المزود حرفاً حرفاً، والحل أن تضيف https://chat.example.com/signup/gitlab/complete بالضبط، وأن تتأكد أن MM_SERVICESETTINGS_SITEURL هو نفس النطاق مع https، لأن Mattermost يبني العنوان منه.

الرسالة «There is already an account associated with that email address»

والسبب أن في Mattermost حساباً بنفس البريد أنشئ بالبريد وكلمة المرور، فلا يربطه Mattermost بحساب authentik تلقائياً، والحل أن يبقى هذا المستخدم على البريد وكلمة المرور، أو أن تغير بريد الحساب القديم من System Console حتى ينشئ له SSO حساباً جديداً، والأفضل أن تفعل SSO قبل أن تدعو الفريق.

المكالمة تتصل ولكن لا يصل الصوت، أو تنقطع بعد ثوان

والسبب في الغالب أن العميل لا يصل إلى المنفذ 8443، فإما أن ICE Host Override فارغ أو يحمل عنواناً داخلياً، فيعلن Mattermost عنوان الـ Container للعميل، أو أن UDP 8443 محجوب في جدار الحماية أو الراوتر ومعه TCP 8443 فيفشل البديل أيضاً كما يذكر دليل نشر Calls. والحل أن تضبط العنوان العام، وأن تفتح المنفذ بنوعيه، ثم تعيد الاختبار من شبكة أخرى وتراجع مخرجات /call stats.

زر بدء المكالمة لا يظهر في قناة عامة أو رسالة جماعية

والسبب أن المكالمات الجماعية Group Calls تحتاج ترخيص Professional، وTeam Edition تسمح بالمكالمات في الرسائل المباشرة 1:1 فقط، وإذا لم يظهر الزر في الرسائل المباشرة أيضاً فتأكد أن Enable Plugin مفعل في System Console ← Plugins ← Calls.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • الخدمة السحابية تقرر نيابة عنك كم تبقى رسائلك، والـ Image الخاصة بـ Enterprise Edition دون ترخيص تخفي ما زاد عن 10,000 رسالة، ولذلك فـ Team Edition هي الخيار المناسب لفريق يقل عن 250 مستخدماً ولا يحتاج SSO مدعوماً رسمياً.
  • مزود GitLab مع authentik يعطيك الدخول الموحد في Team Edition عبر الرابط المباشر، ولكنه غير مدعوم رسمياً منذ الإصدار 11.0، فاحتفظ بحساب مدير بالبريد واقرأ ملاحظات كل تحديث.
  • المكالمات في Team Edition ثنائية في الرسائل المباشرة، وتحتاج المنفذ 8443 UDP وTCP مفتوحاً مباشرة إلى الـ Container، وICE Host Override بالعنوان العام.
  • اربط منفذ الويب بالعنوان 127.0.0.1 خلف الـ Reverse Proxy مع تفعيل WebSocket، واضبط MM_SERVICESETTINGS_SITEURL بدقة لأن منه تبنى كل الروابط.
  • أنشئ حساب المدير فور التشغيل، واترك Open Server معطلاً، وفعل Lock to this channel لكل Webhook واحفظ رابطه كما تحفظ كلمة المرور.
  • خذ نسخة pg_dump ونسخة الـ Volumes وانقلهما خارج السيرفر، ولا تشغل إصداراً أقدم على قاعدة بيانات رحلها إصدار أحدث.
  • اختر بين الإصدارات الشهرية وESR حسب عدد المرات التي تستطيع أن تحدث فيها، واقرأ Important Upgrade Notes قبل كل تحديث رئيسي.

سجل التحديثات Changelog

  • سبتمبر 2026: كتابة الدليل واختباره على Mattermost 11.11.1 (مع ترقية مجربة من 11.10.2).
  • أكتوبر 2026: مراجعة الدليل، وحذف إعدادات Bleve التي أزيلت في الإصدار 11.0، وتصحيح متطلبات العتاد، وإضافة الفرق بين Team Edition وEntry وحدود المكالمات، وشرح الإصدارات الشهرية وESR والإصدار 12.0.
  • أكتوبر 2026: إضافة الدخول الموحد عبر مزود GitLab مع authentik في النسخة المجانية، وتفعيل المكالمات Calls.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.