nordeck / matrix-neoboard

A collaborative whiteboard widget for Matrix

NeoBoard

A collaborative whiteboard widget for Element, based on Matrix. Use it to collaborate in real-time with your peers, by keeping full control of your data and keep it secure with end-to-end encryption.

All data is stored in the Matrix rooms. Learn more about the architecture in the Model or the Architecture Decision Records.

Demo

Click here and follow the instructions to see it in action and experience it yourself. You need at least Moderator permissions (power level >50) in the room so it might be a good idea to test it in a new Matrix room at first.

This is only a demo deployment that is not suited for production use. See the Deployment section on how you can host the widget on your own.

💡 Import the NeoBoard quick start pack for some demo content to get started right away.

Getting Started

Development on the widget happens at GitHub.

How to Contribute

Please take a look at our Contribution Guidelines. Check the following steps to develop for the widget:

Requirements

You need to install Node.js (>= 20.0.0, prefer using an LTS version) and run yarn to work on this package. The minimal Element version to use this widget is 1.11.8.

Installation

After checkout, run yarn install to download the required dependencies

Warning Do not use npm install when working with this package.

Configuration

Rename the provided .env.local.default to .env.local and fill it with your configuration. For a list of available options, see Configuration.

Running the Widget Locally

Follow the instructions to run the widget locally. Visit the widget url follow the further instructions: http(s)://localhost:3000/

Available Scripts

In the project directory, you can run:

• yarn dev: Start the widget for development.
• yarn start: Start the widget for development with a self-signed HTTPS certificate.
• yarn build: Build the production version of the widget.
• yarn test: Watch all files for changes and run tests.
• yarn tsc: Check TypeScript types for errors in the widget.
• yarn lint: Run eslint on the widget.
• yarn prettier:write: Run prettier on all files to format them.
• yarn depcheck: Check for missing or unused dependencies.
• yarn deduplicate: Deduplicate dependencies in the yarn.lock file.
• yarn changeset: Generate a changeset that provides a description of a change.
• yarn translate: Update translation files from code.
• yarn generate-disclaimer: Generates license disclaimer and include it in the build output.
• yarn docker:build: Builds a container from the output of yarn build and yarn generate-disclaimer.
• yarn docker:run: Runs the container and serves the widget at http://localhost:3000.

Versioning

This package uses automated versioning. Each change should be accompanied by a specification of the impact (patch, minor, or major) and a description of the change. Use yarn changeset to generate a new changeset for a pull request. Learn more in the .changeset folder.

Once the change is merged to main, a “Version Packages” pull request will be created. As soon as the project maintainers merged it, the package will be released and the container is published.

Architecture Decision Records

We use Architecture Decision Records (ADR)s to document decisions for our software. You can find them at /docs/adrs.

Deployment

Yon can run the widget using Docker:

docker run --rm -e REACT_APP_HOME_SERVER_URL=https://matrix-client.matrix.org -p 8080:8080 ghcr.io/nordeck/matrix-neoboard-widget:latest

We also provide a HELM chart.

Important: The collaboration features require you to configure TURN servers in your Homeserver. It can work without them, but there is a high chance that it won't! The official matrix.org homeserver will work; see for example how to configure them for Synapse.

Verify the Container Images

The container images releases are signed by cosign using identity-based ("keyless") signing and transparency. Execute the following command to verify the signature of a container image:

cosign verify \
--certificate-identity-regexp https://github.com/nordeck/matrix-neoboard/.github/workflows/publish-release.yml@refs/tags/v \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/nordeck/matrix-neoboard-widget:<version> | jq

License

This project is licensed under APACHE 2.0.

The disclaimer for other OSS components can be accessed via the /NOTICE.txt endpoint. The list of dependencies and their licenses are also available in a machine readable format at /usr/share/nginx/html/licenses.json in the container image.

Sponsors

         

This project is part of the dPhoenixSuite by Dataport.

matrix-neoboard's Issues

Widget crash when opening a NeoBoard for the first time

Describe the bug

Steps To Reproduce

Steps to reproduce the behavior:
0. I use Element Web on Firefox 122.

1. Got an invitation to a room with a NeoBoard. (!pQsOZaCCFWWaVfIknH:nordeck.io)
2. Opened NeoBoard via the toggle icon in the room header.

Expected behavior
NeoBoard opens without any issues.

Screenshots / Videos

NS@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:1136917
DG@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:1681454
ua@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:553097
qa@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:562664
Gu@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:606388
Is@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:592640
Os@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:592568
_s@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:592429
bs@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:589395
534/Yo/<@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:538889
3095/t.unstable_runWithPriority@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:649827
Ho@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:538666
Yo@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:538836
Ko@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:538769
hs@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:586772
Aa@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:558424
na/l</<@https://neoboard.widget.nordeck.io/static/js/main.58356e60.js:2:797932

JavaScript: Console export:
console-export-2024-2-15_18-1-9.txt

Environment:

• OS: Manjaro Linux, based on the Arch Linux btw
• Browser: Firefox 122.0

Additional context

• On the second try of opening this widget, it loaded without an issue.
• Sadly, I don't have a non-minimized version of the error's trace stack.
• If the JS-Console output doesn't help, just close the ticket, I guess. 🤷

Broken GitHub Page

Describe the bug

The GitHub Page https://nordeck.github.io/matrix-neoboard/ is just white.

Steps To Reproduce

Steps to reproduce the behavior:

1. Go to https://nordeck.github.io/matrix-neoboard/

Expected behavior

• Instructions to install this widget via Element Web.
• Or an error message that scripts couldn't be loaded.

Screenshots / Videos

After the setup, the widget registration has to be repaired

Describe the bug

When setting up a new NeoBoard, https://nordeck.github.io/matrix-neoboard/ provides an Element command that requires fixing NeoBoard afterwards.

Steps To Reproduce

1. Go to https://github.com/nordeck/matrix-neoboard?tab=readme-ov-file#readme

2. Click on Click here
   

3. In Element, open a Matrix room and paste /addwidget https://nordeck.github.io/matrix-neoboard/

4. Open the widget
   

5. Click "Repair widget"

Expected behavior

In step 2, the website should have provided a working Element command.

Screenshots / Videos

Environment:

• OS: Manjaro Linux
• Browser: Firefox 123

Additional context

Immediate editing of stroke after drawing with the pen makes multiple strokes difficult

Screencast.from.2024-05-17.16-11-45.webm

Currently trying to use the whiteboard with a graphics tablet and the pen tool is rather frustrating. Upon drawing a stroke, the editing pop-up is opened. This makes it impossible to draw in the area that the pop-up is covering.

In addition, when the pop-up is there, the stroke can seemingly be resized by dragging on the edges (even though there is no resize UI present).

My suggestion would be to hide this edit UI entirely unless the pointer tool is selected and the user clicks on a specific stroke.

Demo site isn't working

If I try open https://nordeck.github.io/matrix-neoboard/ it shows me this:

Only runs as a widget

You need to register this URL as a widget, it's not possible to use it standalone. Run this command in the matrix room you want to register the widget in:

/addwidget https://nordeck.github.io/matrix-neoboard/

how to make a custom widget collaborative

I am using a url for an inage editor and would like this to be collaborative. is there a matrix documentation on how to make a cystom widget collaborative with users inside that room.

or how we can adapt this repo to a custom url.

Cannot select colour of shape until it is created

I'd like to be able to select a colour before I create shapes and objects. The current behaviour is most jarring when trying to draw with the pen. Needing to create a stroke, then select the colour on the first stroke, and then continuing to draw in order to get the colour I wanted to use is confusing:

Screencast.from.2024-05-17.16-22-17.webm

"I want to draw in blue..."

This issue will be exacerbated by fixing #437, requiring switching to the pointer tool in order to select the stroke, and then select the colour.

A potential solution is to put a colour picker tool in the bottom toolbar, which would also help indicate the currently selected default colour for new objects. Something like the following:

Simplify getting started (collection of ideas)

Discovery

• Fix https://nordeck.io/neoboard not showing any content
• Use https://neoboard.io for something

URLs

• Have an easy, permanent URL to give to people at meetups or conferences
• https://neoboard.nordeck.io should redirect to this URL
• https://nordeck.io/neoboard should redirect to this URL

ReadMe

• Start with a summary and a good screenshot
  • Bonus: Show collaboration
  • Bonus: Take a screenshot that looks like actual use instead of a demo
• Demo Link (that actually works)
• Add a all-in-one docker run command (or docker compose) for an easy local trial
• Tell people how they can add Neoboard to their Matrix

Within the demo

• If not started through Element, start the standalone version
• Startup modal
  • State that it's a demo instance and its limitations
  • Link pricing/contact of the hosted/supported version
  • Link GitHub repo as the "code and issue list"
  • Offer to import a template
• Tell people how they can add Neoboard to their Matrix
• Within NeoBoard, offer a few templates to import (e.g. template gallery in a startup modal)
  • Ideas:
    • Retro
    • Company Meetup (progress presentations)
    • Calendar (Month, Quarter, Year) (leave room to mark dates)

Docker image

• If not started through Element, start the standalone version

Can't run in subpath

Describe the bug

Neoboard can't be run in a subpath proxied by nginx because the link to bundle.js seems to contain absolute path.

Steps To Reproduce

1. Run Neoboard node /usr/bin/yarn start
2. Proxy it with nginx:

location /neoboard/ {
        proxy_pass https://127.0.0.1:3000;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
}

3. Go to https://your-server/neoboard
4. Get white screen and 404 as the index page tries to get to /bundle.js which should be /neoboard/bundle.js

Expected behavior

Widget warning showing up