From b7f8e038947e067ba3efbd88d0794b4ef9bdcc43 Mon Sep 17 00:00:00 2001 From: Aine Date: Wed, 25 Sep 2024 19:26:26 +0300 Subject: [PATCH] update README --- README.md | 257 +++++++++++++++++++++++++++++------------------------- 1 file changed, 139 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index a7b3c46..590d839 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,32 @@ # Synapse Admin UI [![GitHub license](https://img.shields.io/github/license/Awesome-Technologies/synapse-admin)](https://github.com/Awesome-Technologies/synapse-admin/blob/master/LICENSE) +![Screenshots](./screenshots.jpg) + This project is built using [react-admin](https://marmelab.com/react-admin/). + + +* [Fork differences](#fork-differences) + * [Available via CDN](#available-via-cdn) + * [Changes](#changes) + * [Development](#development) +* [Configuration](#configuration) + * [Restricting available homeserver](#restricting-available-homeserver) + * [Protecting appservice managed users](#protecting-appservice-managed-users) + * [Providing support URL](#providing-support-url) +* [Usage](#usage) + * [Supported Synapse](#supported-synapse) + * [Prerequisites](#prerequisites) + * [Use without install](#use-without-install) + * [Step-By-Step install](#step-by-step-install) + * [Steps for 1)](#steps-for-1) + * [Steps for 2)](#steps-for-2) + * [Steps for 3)](#steps-for-3) + * [Serving Synapse-Admin on a different path](#serving-synapse-admin-on-a-different-path) +* [Development](#development-1) + + + ## Fork differences With [Awesome-Technologies/synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) as the upstream, this @@ -49,122 +74,6 @@ After that open `http://localhost:5173` in your browser, login using the followi * Password: admin * Homeserver URL: http://localhost:8008 -## Usage - -### Supported Synapse - -It needs at least [Synapse](https://github.com/element-hq/synapse) v1.93.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](https://element-hq.github.io/synapse/latest/admin_api/version_api.html). - -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](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints) - -### Use without install - -You can use the current version of Synapse Admin without own installation direct -via [GitHub Pages](https://awesome-technologies.github.io/synapse-admin/). - -**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](#step-by-step-install) below. - -### Step-By-Step install - -You have three options: - -1. [Download the tarball and serve with any webserver](#steps-for-1) -2. [Download the source code from github and run using nodejs](#steps-for-2) -3. [Run the Docker container](#steps-for-3) - -#### 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: https://github.com/Awesome-Technologies/synapse-admin/releases/latest -- unpack the .tar.gz -- move or symlink the `synapse-admin-x.x.x` into your vhosts root dir -- open the url of the vhost in your browser - -#### Steps for 2) - -- make sure you have installed the following: git, yarn, nodejs -- download the source code: `git clone https://github.com/Awesome-Technologies/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 awesometechnologies/synapse-admin` or use the [docker-compose.yml](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. - - ```yml - services: - synapse-admin: - container_name: synapse-admin - hostname: synapse-admin - build: - context: https://github.com/Awesome-Technologies/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` - -```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: awesometechnologies/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" -``` - ## Configuration You can use `config.json` file to configure synapse-admin @@ -223,9 +132,121 @@ Synapse-Admin provides a support link in the main menu - `Contact support`. By d } ``` -## Screenshots +## Usage -![Screenshots](./screenshots.jpg) +### Supported Synapse + +It needs at least [Synapse](https://github.com/element-hq/synapse) v1.93.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](https://element-hq.github.io/synapse/latest/admin_api/version_api.html). + +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](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints) + +### Use without install + +You can use the current version of Synapse Admin without own installation direct +via [admin.etke.cc](https://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](#step-by-step-install) below. + +### Step-By-Step install + +You have three options: + +1. [Download the tarball and serve with any webserver](#steps-for-1) +2. [Download the source code from github and run using nodejs](#steps-for-2) +3. [Run the Docker container](#steps-for-3) + +#### 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](https://github.com/etkecc/synapse-admin/releases/latest) +- unpack the .tar.gz +- move or symlink the `synapse-admin` into your vhosts root dir +- open the url of the vhost in your browser + +#### 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.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. + + ```yml + 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` + +```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: 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