matrix-dimension/docs/installing.md
Travis Ralston 557e7a39c3
Merge pull request #412 from johannes-krude/master
docs/installing.md: `npm install` on update
2021-11-24 13:11:11 -07:00

169 lines
5.4 KiB
Markdown

## Installing Dimension
**Note**: Dimension is only supported in Element Web and Desktop at the moment. With some effort,
it can be used in other clients or Element iOS/Android, though is not guaranteed to work. In future,
this should be handled by [an integration manager specification](https://github.com/turt2live/matrix-dimension/issues/262).
There are several options for installing Dimension. The easiest is dependent on how you have Element
and your homeserver set up. If you're using [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy),
there are already options for configuring Dimension.
### Step 0: Requirements
You will need a functioning homeserver (such as [Synapse](https://github.com/matrix-org/synapse)) and
a client to access Dimension with. Currently, that means using [Element Web or Desktop](https://element.io).
Additionally, you will need to be able to host Dimension on a dedicated domain. If your homeserver
is set up for example.org, we recommend using dimension.example.org for Dimension.
Finally, this guide assumes you are running nginx as a webserver for Element, your homeserver, and
Dimension. A basic configuration before setting up Dimension would be:
```conf
server {
# Simple configuration for Synapse. Consult the Synapse documentation for however you would
# like to run your homeserver.
server_name example.org;
listen 443 ssl;
listen [::]:443 ssl;
location /_matrix {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8008;
}
}
server {
# Simple configuration for serving Element
server_name chat.example.org;
listen 443 ssl;
listen [::]:443 ssl;
root /var/www/html;
index index.html;
location / {
try_files $uri $uri/ =404.html;
}
}
```
The SSL options are not shown. Using [Let's Encrypt with nginx](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-18-04)
is fairly straightforward, however.
**Note**: If you're running Dimension in an unfederated environment, you'll have some additional setup
to do. See [unfederated.md](./unfederated.md) for more information.
### Step 1: Picking between Docker and building Dimension yourself
Docker images are provided as `turt2live/matrix-dimension` and require fewer resources than building
it yourself.
If you're using Docker, create a directory at `/etc/dimension` (or wherever you'd like - just remember
where it is!).
To build Dimension yourself, you'll need Node 10+, npm 6+, and 2-4gb of RAM. The following steps are enough
to get you started:
```bash
# Download dimension
git clone https://github.com/turt2live/matrix-dimension.git
cd matrix-dimension
# Install dependencies
npm install
# Build it
npm run build
```
### Step 2: Configuring Dimension
**Docker**: Using [the default config](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml)
as an example, create a file at `/etc/dimension/config.yaml`.
**Building**: Copy `config/default.yaml` to `config/production.yaml`
After creating the file, open it in an editor like `nano` and start filling in the details. Don't forget
to add your user ID as an admin in the configuration - this is important later!
If you're using Docker, leave the `web` `port` and `address` as-is. Dimension supports SQLite and PostgreSQL as the database. Make sure to configure the `database` section to look like this for SQLite:
```yaml
database:
file: "/data/dimension.db"
botData: "/data/bot.json"
```
or for PostgreSQL:
```yaml
database:
uri: "postgres://admin:password@localhost:5432/matrix-dimension"
botData: "/data/bot.json"
```
### Step 3: Running Dimension
**Docker**:
```bash
docker run -d --name dimension -p 127.0.0.1:8184:8184 -v /etc/dimension:/data turt2live/matrix-dimension
```
**Building**:
```bash
NODE_ENV=production npm run start:app
```
If all went well, Dimension should now be running - there's still a bit more configuration to
go though.
### Step 4: Configuring nginx
Create a new server definition for your nginx server:
```conf
server {
server_name dimension.example.org;
listen 443 ssl;
listen [::]:443 ssl;
root /var/www/html;
index index.html;
location / {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8184;
}
}
```
Reload or restart nginx after creating the configuration.
### Step 5: Final steps
If everything went according to plan, you should be able to visit `https://dimension.example.org`
and see instructions for configuring Element. If you don't, your configuration isn't working as
intended - double check that all the configuration is set up and visit [#dimension:t2bot.io](https://matrix.to/#/#dimension:t2bot.io)
for further help.
After configuring Element, click the integrations button (4 squares in the top right of any room) and
then click the gear icon. If you don't see a gear icon, you're not an admin in the config. This is
where you'll configure different integrations as Dimension doesn't ship with anything enabled by
default - click around and start enabling things.
### Step 6: Updating and restarting Dimension
**Docker**:
```bash
docker pull turt2live/matrix-dimension
docker restart dimension
```
**Building**:
```bash
# Kill the running Dimension process, then...
git pull
npm install
npm run build
NODE_ENV=production npm run start:app
```