Improve debian package and docs (#26618)

.github/workflows/build_debian.yaml

@@ -33,10 +33,11 @@ jobs:
               run: |
                   mkdir -p debian/tmp/DEBIAN
                   find debian -maxdepth 1 -type f -exec cp "{}" debian/tmp/DEBIAN/ \;
-                  mkdir -p debian/tmp/usr/share/element-web/
+                  mkdir -p debian/tmp/usr/share/element-web/ debian/tmp/etc/element-web/
 
                   tar -xf "element-$VERSION.tar.gz" -C debian/tmp/usr/share/element-web --strip-components=1 --no-same-owner --no-same-permissions
-                  mv debian/tmp/usr/share/element-web/config{.sample,}.json
+                  mv debian/tmp/usr/share/element-web/config.sample.json debian/tmp/etc/element-web/config.json
+                  ln -s /etc/element-web/config.json debian/tmp/usr/share/element-web/config.json
 
             - name: Write changelog
               run: |

README.md

@@ -41,29 +41,9 @@ The easiest way to test Element is to just use the hosted copy at <https://app.e
 The `develop` branch is continuously deployed to <https://develop.element.io>
 for those who like living dangerously.
 
-To host your own copy of Element, the quickest bet is to use a pre-built
+To host your own instance of Element see [Installing Element Web](docs/install.md).
-released version of Element:
 
-1. Download the latest version from <https://github.com/vector-im/element-web/releases>
+To install Element as a desktop application, see [Running as a desktop app](#running-as-a-desktop-app) below.
-1. Untar the tarball on your web server
-1. Move (or symlink) the `element-x.x.x` directory to an appropriate name
-1. Configure the correct caching headers in your webserver (see below)
-1. Configure the app by copying `config.sample.json` to `config.json` and
-   modifying it. See the [configuration docs](docs/config.md) for details.
-1. Enter the URL into your browser and log into Element!
-
-Releases are signed using gpg and the OpenPGP standard, and can be checked against the public key located
-at <https://packages.riot.im/element-release-key.asc>.
-
-Note that for the security of your chats will need to serve Element
-over HTTPS. Major browsers also do not allow you to use VoIP/video
-chats over HTTP, as WebRTC is only usable over HTTPS.
-There are some exceptions like when using localhost, which is
-considered a [secure context](https://developer.mozilla.org/docs/Web/Security/Secure_Contexts)
-and thus allowed.
-
-To install Element as a desktop application, see [Running as a desktop
-app](#running-as-a-desktop-app) below.
 
 # Important Security Notes
 
@@ -161,61 +141,7 @@ To build it yourself, follow the instructions at <https://github.com/vector-im/e
 
 Many thanks to @aviraldg for the initial work on the Electron integration.
 
-Other options for running as a desktop app:
+The [configuration docs](docs/config.md#desktop-app-configuration) show how to override the desktop app's default settings if desired.
-
--   @asdf:matrix.org points out that you can use nativefier and it just works(tm)
-
-```bash
-yarn global add nativefier
-nativefier https://app.element.io/
-```
-
-The [configuration docs](docs/config.md#desktop-app-configuration) show how to
-override the desktop app's default settings if desired.
-
-# Running from Docker
-
-The Docker image can be used to serve element-web as a web server. The easiest way to use
-it is to use the prebuilt image:
-
-```bash
-docker run -p 80:80 vectorim/element-web
-```
-
-To supply your own custom `config.json`, map a volume to `/app/config.json`. For example,
-if your custom config was located at `/etc/element-web/config.json` then your Docker command
-would be:
-
-```bash
-docker run -p 80:80 -v /etc/element-web/config.json:/app/config.json vectorim/element-web
-```
-
-To build the image yourself:
-
-```bash
-git clone https://github.com/vector-im/element-web.git element-web
-cd element-web
-git checkout master
-docker build .
-```
-
-If you're building a custom branch, or want to use the develop branch, check out the appropriate
-element-web branch and then run:
-
-```bash
-docker build -t \
-    --build-arg USE_CUSTOM_SDKS=true \
-    --build-arg REACT_SDK_REPO="https://github.com/matrix-org/matrix-react-sdk.git" \
-    --build-arg REACT_SDK_BRANCH="develop" \
-    --build-arg JS_SDK_REPO="https://github.com/matrix-org/matrix-js-sdk.git" \
-    --build-arg JS_SDK_BRANCH="develop" \
-    .
-```
-
-# Running in Kubernetes
-
-The provided element-web docker image can also be run from within a Kubernetes cluster.
-See the [Kubernetes example](docs/kubernetes.md) for more details.
 
 # config.json
 

debian/conffiles

@@ -1 +1 @@
-/usr/share/element-web/config.json
+/etc/element-web/config.json

docs/SUMMARY.md

@@ -9,6 +9,7 @@
 
 # Setup
 
+-   [Install](install.md)
 -   [Config](config.md)
 -   [Custom home page](custom-home.md)
 -   [Kubernetes](kubernetes.md)

docs/install.md

@@ -0,0 +1,78 @@
+# Installing Element Web
+
+**Familiarise yourself with the [Important Security Notes](../README.md#important-security-notes) before starting, they apply to all installation methods.**
+
+_Note: that for the security of your chats will need to serve Element over HTTPS.
+Major browsers also do not allow you to use VoIP/video chats over HTTP, as WebRTC is only usable over HTTPS.
+There are some exceptions like when using localhost, which is considered a [secure context](https://developer.mozilla.org/docs/Web/Security/Secure_Contexts) and thus allowed._
+
+## Release tarball
+
+1. Download the latest version from <https://github.com/vector-im/element-web/releases>
+1. Untar the tarball on your web server
+1. Move (or symlink) the `element-x.x.x` directory to an appropriate name
+1. Configure the correct caching headers in your webserver (see below)
+1. Configure the app by copying `config.sample.json` to `config.json` and
+   modifying it. See the [configuration docs](docs/config.md) for details.
+1. Enter the URL into your browser and log into Element!
+
+Releases are signed using gpg and the OpenPGP standard,
+and can be checked against the public key located at <https://packages.element.io/element-release-key.asc>.
+
+## Debian package
+
+Element Web is now also available as a Debian package for Debian and Ubuntu based systems.
+
+```shell
+sudo apt install -y wget apt-transport-https
+sudo wget -O /usr/share/keyrings/element-io-archive-keyring.gpg https://packages.element.io/debian/element-io-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/element-io-archive-keyring.gpg] https://packages.element.io/debian/ default main" | sudo tee /etc/apt/sources.list.d/element-io.list
+sudo apt update
+sudo apt install element-web
+```
+
+Configure the app by modifying `/etc/element-web/config.json`. See the [configuration docs](docs/config.md) for details.
+
+## Docker
+
+The Docker image can be used to serve element-web as a web server. The easiest way to use
+it is to use the prebuilt image:
+
+```bash
+docker run -p 80:80 vectorim/element-web
+```
+
+To supply your own custom `config.json`, map a volume to `/app/config.json`. For example,
+if your custom config was located at `/etc/element-web/config.json` then your Docker command
+would be:
+
+```bash
+docker run -p 80:80 -v /etc/element-web/config.json:/app/config.json vectorim/element-web
+```
+
+To build the image yourself:
+
+```bash
+git clone https://github.com/vector-im/element-web.git element-web
+cd element-web
+git checkout master
+docker build .
+```
+
+If you're building a custom branch, or want to use the develop branch, check out the appropriate
+element-web branch and then run:
+
+```bash
+docker build -t \
+    --build-arg USE_CUSTOM_SDKS=true \
+    --build-arg REACT_SDK_REPO="https://github.com/matrix-org/matrix-react-sdk.git" \
+    --build-arg REACT_SDK_BRANCH="develop" \
+    --build-arg JS_SDK_REPO="https://github.com/matrix-org/matrix-js-sdk.git" \
+    --build-arg JS_SDK_BRANCH="develop" \
+    .
+```
+
+## Kubernetes
+
+The provided element-web docker image can also be run from within a Kubernetes cluster.
+See the [Kubernetes example](docs/kubernetes.md) for more details.