mirrors/synapse-admin
1
0
Fork 0
mirror of https://github.com/etkecc/synapse-admin.git synced 2024-11-21 07:15:20 +03:00
Code Issues Projects Releases Packages Wiki Activity
synapse-admin/README.md
Aine dae6872fe8
add reverse proxy docs
2024-11-20 16:31:55 +02:00

14 KiB
Raw Permalink Blame History

Synapse Admin Logo

Synapse Admin
Community room
License

Feature-packed and visually customizable: A better way to manage your Synapse homeserver.

Login form showing dark and light modes Screenshots

Fork differences

With Awesome-Technologies/synapse-admin as the upstream, this fork introduces numerous enhancements to improve usability and extend functionality, including support for authenticated media, advanced user management options, and visual customization. The full list is described below in the Changes section.

Availability

Changes

The following changes are already implemented:

the list will be updated as new changes are added

Development

just run-dev to start the development stack (depending on your system speed, you may want to re-run this command if user creation fails)

This command initializes the development environment (local Synapse server and Postgres DB), and launches the app in a dev mode at http://localhost:5173

After that open http://localhost:5173 in your browser, login using the following credentials:

Support

If you have any questions or need help, feel free to join the community room or create an issue on GitHub.

Configuration

You can use config.json file to configure Synapse Admin instance, and /.well-known/matrix/client file to provide Synapse Admin configuration specifically for your homeserver. In the latter case, any instance of Synapse Admin will automatically pick up the configuration from the homeserver. Note that configuration inside the /.well-known/matrix/client file should go under the cc.etke.synapse-admin key, and it will override the configuration from the config.json file.

In case you use spantaleev/matrix-docker-ansible-deploy or etkecc/ansible, configuration will be automatically added to the /.well-known/matrix/client file.

Configuration options

The config.json can be injected into a Docker container using a bind mount.

services:
  synapse-admin:
    ...
    volumes:
      ./config.json:/app/config.json:ro
    ...

Prefilling login form

You can prefill username and homeserver fields on the login page using GET parameters, example:

https://matrix.example.com/synapse-admin/?username=admin&server=matrix.example.com

That way username and homeserver fields will be pre-filled with admin and https://matrix.example.com respectively.

Restricting available homeserver

You can restrict the homeserver(s), so that the user can no longer define it himself.

Documentation

Protecting appservice managed users

To avoid accidental adjustments of appservice-managed users (e.g., puppets created by a bridge) and breaking the bridge, you can specify the list of MXIDs (regexp) that should be prohibited from any changes, except display name and avatar.

Documentation

Adding custom menu items

You can add custom menu items to the main menu by providing a menu array in the config.

Documentation

Usage

Supported Synapse

It needs at least Synapse v1.116.0 for all functions to work as expected!

You get your server version with the request /_synapse/admin/v1/server_version. See also Synapse version API.

After entering the URL on the login page of synapse-admin the server version appears below the input field.

Prerequisites

You need access to the following endpoints:

  • /_matrix
  • /_synapse/admin

See also Synapse administration endpoints

Use without install

You can use the current version of Synapse Admin without own installation direct via admin.etke.cc.

Note: If you want to use the deployment, you have to make sure that the admin endpoints (/_synapse/admin) are accessible for your browser. Remember: You have no need to expose these endpoints to the internet but to your network. If you want your own deployment, follow the Step-By-Step Install Guide below.

Step-By-Step install

You have three options:

  1. Download the tarball and serve with any webserver
  2. Download the source code from github and run using nodejs
  3. Run the Docker container

Steps for 1)

  • make sure you have a webserver installed that can serve static files (any webserver like nginx or apache will do)
  • configure a vhost for synapse admin on your webserver
  • download the .tar.gz from the latest release
  • unpack the .tar.gz
  • move or symlink the synapse-admin into your vhosts root dir
  • open the url of the vhost in your browser

Reverse Proxy Documentation with Examples

Steps for 2)

  • make sure you have installed the following: git, yarn, nodejs
  • download the source code: git clone https://github.com/etkecc/synapse-admin.git
  • change into downloaded directory: cd synapse-admin
  • download dependencies: yarn install
  • start web server: yarn start

Steps for 3)

  • run the Docker container from the public docker registry: docker run -p 8080:80 ghcr.io/etkecc/synapse-admin or use the docker-compose.yml: docker-compose up -d

    note: if you're building on an architecture other than amd64 (for example a raspberry pi), make sure to define a maximum ram for node. otherwise the build will fail.

    services:
  synapse-admin:
    container_name: synapse-admin
    hostname: synapse-admin
    build:
      context: https://github.com/etkecc/synapse-admin.git
      args:
        - BUILDKIT_CONTEXT_KEEP_GIT_DIR=1
      #   - NODE_OPTIONS="--max_old_space_size=1024"
      #   - BASE_PATH="/synapse-admin"
    ports:
      - "8080:80"
    restart: unless-stopped

  • browse to http://localhost:8080

Serving Synapse Admin on a different path

The path prefix where synapse-admin is served can only be changed during the build step.

If you downloaded the source code, use yarn build --base=/my-prefix to set a path prefix.

If you want to build your own Docker container, use the BASE_PATH argument.

We do not support directly changing the path where Synapse Admin is served in the pre-built Docker container. Instead please use a reverse proxy if you need to move Synapse Admin to a different base path. If you want to serve multiple applications with different paths on the same domain, you need a reverse proxy anyway.

Example for Traefik:

docker-compose.yml

services:
  traefik:
    image: traefik:mimolette
    restart: unless-stopped
    ports:
      - 80:80
      - 443:443
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

  synapse-admin:
    image: ghcr.io/etkecc/synapse-admin:latest
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.synapse-admin.rule=Host(`example.com`)&&PathPrefix(`/admin`)"
      - "traefik.http.routers.synapse-admin.middlewares=admin,admin_path"
      - "traefik.http.middlewares.admin.redirectregex.regex=^(.*)/admin/?"
      - "traefik.http.middlewares.admin.redirectregex.replacement=$${1}/admin/"
      - "traefik.http.middlewares.admin_path.stripprefix.prefixes=/admin"

Development