Ben TITO

matrix

1
0
1
public
View on GitHub

Below is a clean, end-to-end Markdown documentation covering everything you’ve done from start to finish, written so that:

  • You (or anyone else) can reproduce the setup
  • It can live in a README.md
  • It reflects the final working state
  • It clearly notes where SSL was intentionally skipped for admin

📘 Matrix Server Deployment Documentation

Domain: snap.co.ke
Homeserver: matrix.snap.co.ke
Web Client: chat.snap.co.ke
Admin UI: admin.chat.snap.co.ke (HTTP only)

1. Overview

This document describes the complete setup of a self-hosted Matrix stack, consisting of:

  • Synapse (Matrix homeserver)
  • Element Web (end-user web client)
  • Synapse Admin UI (server administration dashboard)
  • Google SSO (OIDC) for authentication
  • Email verification for registrations
  • Nginx as the reverse proxy and static file server

⚠️ Note:
The Admin UI is intentionally served over HTTP only for now due to SSL/TLS configuration issues. This is acceptable for temporary/internal access, but HTTPS is recommended for production.

2. Server Prerequisites

  • Ubuntu / Debian server

  • Root or sudo access

  • DNS records pointing to server IP:

    matrix.snap.co.ke
chat.snap.co.ke
admin.chat.snap.co.ke

  • Installed packages:

    sudo apt update
sudo apt install -y nginx git curl nodejs npm
sudo npm install -g yarn

3. Matrix Homeserver (Synapse)

3.1 Installation

sudo apt install -y matrix-synapse-py3

During installation:

  • Set server name to: matrix.snap.co.ke

3.2 Core Configuration

File:

/etc/matrix-synapse/homeserver.yaml

Key settings enabled:

  • Open registration with email verification
  • SMTP email sending
  • Google SSO (OIDC)
  • Reverse-proxy support

Registration

enable_registration: true
enable_registration_without_verification: false

registrations_require_3pid:
  - email

Email (SMTP)

email:
  enable_notifs: true
  smtp_host: smtp.gmail.com
  smtp_port: 587
  smtp_user: your-email@gmail.com
  smtp_pass: APP_PASSWORD
  require_transport_security: true
  enable_tls: true
  notif_from: "Matrix <your-email@gmail.com>"

Public Base URL

public_baseurl: "https://matrix.snap.co.ke/"

3.3 Google Single Sign-On (OIDC)

oidc_providers:
  - idp_id: google
    idp_name: "Google"
    issuer: "https://accounts.google.com"
    client_id: GOOGLE_CLIENT_ID
    client_secret: GOOGLE_CLIENT_SECRET
    scopes: ["openid", "profile", "email"]

    user_mapping_provider:
      config:
        localpart_template: "{{ user.email.split('@')[0] }}"
        display_name_template: "{{ user.name }}"

    allow_existing_users: true

3.4 Create Admin User

sudo register_new_matrix_user \
  -c /etc/matrix-synapse/homeserver.yaml \
  http://localhost:8008
  • Choose username (e.g. superadmin)
  • Set Make admin: yes

4. Nginx Reverse Proxy for Synapse

File:

/etc/nginx/sites-available/matrix.snap.co.ke

server {
    listen 80;
    server_name matrix.snap.co.ke;

    location /_matrix {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /_synapse/admin {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable and reload:

sudo ln -s /etc/nginx/sites-available/matrix.snap.co.ke /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

5. Element Web (User Chat UI)

5.1 Build Element Web

cd /opt
git clone https://github.com/element-hq/element-web.git
cd element-web
yarn install
yarn dist

Deploy:

sudo mkdir -p /var/www/element
sudo rsync -a dist/ /var/www/element/
sudo chown -R www-data:www-data /var/www/element

5.2 Element Configuration

File:

/var/www/element/config.json

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.snap.co.ke",
      "server_name": "matrix.snap.co.ke"
    }
  },
  "disable_custom_urls": true,
  "disable_guests": true,
  "brand": "Snap Chat"
}

5.3 Nginx for Element Web

server {
    listen 80;
    server_name chat.snap.co.ke;

    root /var/www/element;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

6. Synapse Admin UI (Static, No Docker)

6.1 Build synapse-admin

cd /opt
git clone https://github.com/Awesome-Technologies/synapse-admin.git
cd synapse-admin
yarn install
yarn build

Output directory: dist/

Deploy:

sudo mkdir -p /var/www/synapse-admin
sudo rsync -a dist/ /var/www/synapse-admin/
sudo chown -R www-data:www-data /var/www/synapse-admin

6.2 Admin UI Runtime Config

File:

/var/www/synapse-admin/config.json

{
  "restrictBaseUrl": "https://matrix.snap.co.ke"
}

6.3 Nginx for Admin UI (HTTP ONLY)

File:

/etc/nginx/sites-available/admin.chat

server {
    listen 80;
    server_name admin.chat.snap.co.ke;

    root /var/www/synapse-admin;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location = /config.json {
        add_header Cache-Control "no-cache, no-store, must-revalidate";
        add_header Pragma "no-cache";
        add_header Expires 0;
        try_files $uri =404;
    }
}

Enable:

sudo ln -s /etc/nginx/sites-available/admin.chat /etc/nginx/sites-enabled/admin.chat
sudo nginx -t
sudo systemctl reload nginx

Access:

http://admin.chat.snap.co.ke

7. Final URLs

Service URL
Matrix Homeserver https://matrix.snap.co.ke
Element Web https://chat.snap.co.ke
Admin UI http://admin.chat.snap.co.ke

8. Notes & Next Steps

Known Limitations

  • Admin UI is HTTP only
  • Google SSO will not work on Admin UI without HTTPS
  • Fix SSL properly for admin.chat.snap.co.ke
  • Restrict admin access by IP or VPN
  • Set up TURN server for calls
  • Add backups for /var/lib/matrix-synapse

If you want, I can:

  • Export this as a README.md
  • Add architecture diagrams
  • Add troubleshooting section
  • Or write a production hardening checklist

Just say the word.

v0.3.3[beta]