Add documentation on how to run Dimension locally

2024-10-01 01:05:53 -04:00 · 2021-12-07 12:46:04 -07:00 · 2021-12-07 12:46:04 -07:00 · 6c81711901
commit 6c81711901
parent 8010658e4b
1 changed files with 122 additions and 0 deletions
--- a/docs/local.md
+++ b/docs/local.md
@ -0,0 +1,122 @@
+# Developer/local environment setup
+
+**Disclaimer**: This guide assumes a fairly high level of pre-existing knowledge regarding development practices, Matrix,
+integration managers, and troubleshooting. The guide covers the happy path, though sometimes it doesn't work out that way.
+Troubleshooting the system is best before jumping into support rooms: it helps build context on how all this works.
+
+Prerequisites:
+* A local Synapse.
+* A local Element Web.
+* All the other dependencies which would be required by a production install.
+
+**Note**: As a local environment, you do not need to use https for any of the setup. In fact, it is recommended to stick
+to plain http as it involves less certificate issues. For added benefit, set your homeserver name to `localhost`.
+
+## Part 1: Configuration
+
+Copy the default configuration and give it an edit. The major settings will be the `web`, `homeserver`, and `admins`
+sections.
+
+It is recommended to run Dimension on `0.0.0.0:8184` for demonstration purposes. Your homeserver's `clientServerUrl`
+*and* `federationUrl` should be pointed to your local Synapse. This will bypass a lot of the federation-level stuff
+by pointing your Dimension directly at the Synapse instance rather than it trying to resolve `localhost` on the public
+federation.
+
+The `accessToken` should be a dedicated user **that has not ever opened Dimension**. Set this up now before configuring
+the client.
+
+```bash
+# Edit the configuration to your specifications.
+# Be sure to add yourself as an admin!
+cp config/default.yaml config/development.yaml
+nano config/development.yaml
+```
+
+## Part 2: Installation and running
+
+In a bash terminal:
+
+```bash
+npm install
+npm run start:apponly
+```
+
+If that starts up without issue (ie: doesn't crash) then open a second terminal with:
+
+```bash
+npm run start:web
+```
+
+You should now have **2** terminals, one for the web app and one for the backend. Both should live reload if you make
+changes to the respective layers.
+
+The web server will start on port `8082`.
+
+## Part 3: Element configuration
+
+In your local `config.json`, add/edit the following keys:
+
+```json
+{
+  "integrations_ui_url": "http://localhost:8082/element",
+  "integrations_rest_url": "http://localhost:8082/api/v1/scalar",
+  "integrations_widgets_urls": ["http://localhost:8082/widgets"],
+  "integrations_jitsi_widget_url": "http://localhost:8082/widgets/jitsi"
+}
+```
+
+## Part 4: Using Dimension
+
+If everything went according to plan, Dimension should now be accessible from the "Add widgets, bridges & bots" button on
+the room information card.
+
+You should see a cog/gear icon in the top right of the dialog window. This indicates that you are an admin. If you do not
+see this, fix the Dimension config and restart the `npm run start:apponly` process.
+
+## Part 5: Configuring integrations in Dimension
+
+Click the gear icon in the Dimension window within Element. The menu on the left side should guide you through the process
+of setting up and configuring integrations.
+
+**Danger**: Upstream (matrix.org) integrations will not work. Do not enable them in local environments.
+
+**Note**: Dimension enforces a maximum of one bridge instance per type. It does this by disabling buttons despite indicating
+that there's potential for multiple to be added. Adding a self-hosted bridge will disable all future options of adding a
+second bridge, but it should be possible to edit the added instance.
+
+For the purposes of this guide, we'll set up Hookshot and a custom bot.
+
+## Part 6: Hookshot
+
+First, set up a local instance of [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) within your test environment.
+It is recommended to proxy some of the endpoints through ngrok (or similar) to make external integration a lot easier.
+
+For testing purposes it's often best to use a single Hookshot instance, though Dimension will assume that you'll have
+multiple instances, one for each capable service, however it is perfectly fine to point all the Dimension configs at the
+same Hookshot instance.
+
+The Hookshot-capable bridges can be configured from here:
+![](https://i.imgur.com/42dTDuk.png)
+*UI may vary. Note the subtle difference in descriptions for the two webhook bridges.*
+
+Simply configure the bridges from that view and click "Browse integrations" in the top left to go work with the bridges.
+They should appear as integrations within Dimension.
+
+## Part 7: Custom bots
+
+Custom bots can be configured from the admin section under "Custom bots". Dimension will need an access token, and will
+assume that the bots do not need special power levels or invite handling - they will be required to operate at the default
+power level for rooms, and auto-accept invites on their own. Dimension will take care of removing the bot from the room
+when the time comes, and the bot should be okay with this happening outside of its process.
+
+Maubot bots are great options for inclusion here.
+
+## Part 8: Troubleshooting
+
+Occasionally the live reload functionality either doesn't work or causes problems. Re-open Dimension within Element to 
+fix most issues, and restart the relevant processes if needed.
+
+Note that Dimension will do its best to avoid crashing, but will produce cryptic errors if an integration is down or
+misconfigured.
+
+For all other troubleshooting, please visit the support room.