Improve debian package and docs (#26618)

This commit is contained in:
Michael Telatynski 2023-11-21 16:28:28 +00:00 committed by GitHub
parent 94228574d4
commit 802571176e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 86 additions and 80 deletions

View file

@ -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: |

View file

@ -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
released version of Element:
To host your own instance of Element see [Installing Element Web](docs/install.md).
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.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.
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:
- @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.
The [configuration docs](docs/config.md#desktop-app-configuration) show how to override the desktop app's default settings if desired.
# config.json

2
debian/conffiles vendored
View file

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

View file

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

78
docs/install.md Normal file
View file

@ -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.