## 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 ```