b310-digital/teammapper

Mindmapping made simple: Host and create your own mindmaps. Share your mindmap sessions with your team and collaborate on mindmaps.

TeamMapper

Mindmapping made simple: Host and create your own mindmaps. Share your mindmap sessions with your team and collaborate on mindmaps.

TeamMapper is based on mindmapp (https://github.com/cedoor/mindmapp , discontinued). In contrast to mindmapp, TeamMapper features shared mindmapping sessions for your team based on websockets. Try it: TeamMapper.org

Features:

• Creation: Host and create your own mindmaps
• Customization: Add images, pictograms*, colors, font properties and links to nodes
• Collaboration: Share your mindmap with friends and collegues, using either a view-only or modification invite!
• Interoperability: Import and export functionality (JSON, SVG, PDF, PNG...)
• Shareability: Use a QR Code or URL to share your maps
• GDPR Compliancy: By default, mindmaps are deleted after 30 days
• Usability: Redo / Undo, many Shortcuts

Getting started

Quick Start (without building the image)

Prepared docker image: docker pull ghcr.io/b310-digital/teammapper:latest

Docker compose

Attention: Add the missing password for postgres inside app_prod and postgres_prod!

docker compose up -d and visit localhost:80

version: "3.8"

services:
  app_prod:
    image: ghcr.io/b310-digital/teammapper:latest
    environment:
      MODE: PROD
      BINDING: "0.0.0.0"
      POSTGRES_DATABASE: teammapper-db
      POSTGRES_HOST: postgres_prod
      POSTGRES_PASSWORD:
      POSTGRES_PORT: 5432
      POSTGRES_SSL: false
      POSTGRES_SSL_REJECT_UNAUTHORIZED: false
      POSTGRES_USER: teammapper-user
      POSTGRES_QUERY_TIMEOUT: 100000
      POSTGRES_STATEMENT_TIMEOUT: 100000
      DELETE_AFTER_DAYS: 30
    ports:
      - 80:3000
    depends_on:
      - postgres_prod

  postgres_prod:
    image: postgres:12-alpine
    # Pass config parameters to the postgres server.
    # Find more information below when you need to generate the ssl-relevant file your self
    # command: -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key
    environment:
      PGDATA: /var/lib/postgresql/data/pgdata
      POSTGRES_DB: teammapper-db
      POSTGRES_PASSWORD:
      POSTGRES_PORT: 5432
      POSTGRES_USER: teammapper-user
    volumes:
      # To setup an ssl-enabled postgres server locally, you need to generate a self-signed ssl certificate.
      # See README.md for more information.
      # Mount the ssl_cert_file and ssl_key_file into the docker container.
      - ./ca/server.crt:/var/lib/postgresql/server.crt
      - ./ca/server.key:/var/lib/postgresql/server.key
      - postgres_prod_data:/var/lib/postgresql/data/pgdata

volumes:
  postgres_prod_data:

Development

• Start up app necessary services

  docker-compose up -d --build --force-recreate

• Start frontend and backend at once

  docker-compose exec app npm --prefix teammapper-backend run dev

  or start frontend and backend separately

  # Open two terminal sessions on your host machine
  
  # In first terminal session
  docker-compose exec app npm --prefix teammapper-backend start
  
  # In second terminal session
  docker-compose exec app npm --prefix teammapper-frontend start

• Visit the frontend in http://localhost:4200

Test

• Create a test database

  docker-compose exec postgres createdb -e -U teammapper-user -W teammapper-backend-test

• Execute the tests

  docker-compose exec app npm -prefix teammapper-backend run test:e2e

Production

• Duplicate and rename .env.default

  cp .env.default .env.prod

• Adjust all configs in .env.prod, e.g. database settings, ports, enable ssl env vars if necessary

• Start everything at once (including a forced build):

  docker-compose --file docker-compose-prod.yml --env-file .env.prod up -d --build --force-recreate

• Go to http://localhost:3011 (if default port is used in .env.prod) to open up teammapper. Happy mapping!

• Optional commands:

  If you want to make sure to include the most recent updates, run first:

  docker-compose --file docker-compose-prod.yml --env-file .env.prod build --no-cache

  then:

  docker-compose --file docker-compose-prod.yml --env-file .env.prod up -d --force-recreate

  If you want to remove old data, including cached node packages and stored databases (DANGER!):

  docker-compose --file docker-compose-prod.yml --env-file .env.prod down -v

  If you want to run prod migrations (again):

  docker-compose exec app_prod npm -prefix teammapper-backend run prod:typeorm:migrate

Postgres and SSL

If needed, you can make the connection to Postgres more secure by using a SSL connection.

• Generate self-signed ssl sertificate for the postgres server on the host machine; the generated files are mounted into the docker container

  mkdir -p ./ca
  openssl req -new -text -passout pass:abcd -subj /CN=localhost -out ./ca/server.req -keyout ./ca/privkey.pem
  openssl rsa -in ./ca/privkey.pem -passin pass:abcd -out ./ca/server.key
  openssl req -x509 -in ./ca/server.req -text -key ./ca/server.key -out ./ca/server.crt
  chmod 600 ./ca/server.key
  test $(uname -s) = Linux && chown 70 ./ca/server.key

  And uncomment the line:

   # command: -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key

  within the docker-compose-prod file.

Running jobs

Trigger delete job (also executed daily with cron task scheduler):

docker-compose --file docker-compose-prod.yml --env-file .env.prod exec app_prod npm --prefix teammapper-backend run prod:data:maps:cleanup

Running further queries

Example of running sql via typeorm:

docker-compose --file docker-compose-prod.yml --env-file .env.prod exec app_prod npx --prefix teammapper-backend typeorm query "select * from mmp_node" --dataSource ./teammapper-backend/dist/data-source.js

Frontend feature flags

See file /teammapper-frontend/src/envrionments/environment.prod.ts to configure feature flags:

• featureFlagPictograms: Disables/Enables the pictogram feature (default: enabled). Note: You have to set this flag before build time!

Further details

• Once this docker volume is initialized after the first docker-compose up, the database-related variables in .env.prod will not have any effect; please have this in mind => you will then need to setup your database manually

Contributing

1. Fork it
2. Create your feature branch (git checkout -b fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin fooBar)
5. Create a new Pull Request

Testimonials

kits is a project platform hosted by a public institution for quality development in schools (Lower Saxony, Germany) and focusses on digital tools and media in language teaching. TeamMapper is used in workshops to activate prior knowledge, and collect and structure ideas. In addition, TeamMapper can be found on https://kits.blog/tools and can be used by schools for free.

Logos and text provided with courtesy of kits.

Acknowledgements

• *Pictograms author: Sergio Palao. Origin: ARASAAC (http://www.arasaac.org). License: CC (BY-NC-SA). Owner: Government of Aragon (Spain)
• Mindmapp: https://github.com/cedoor/mindmapp (discontinued)
• mmp: https://github.com/cedoor/mmp (discontinued)
• D3: https://github.com/d3/d3
• DomPurify: https://github.com/cure53/DOMPurify

teammapper's Issues

update dependencies with npm audit

Update d3 library

Add the possibility to add text elements (without a node)

Add the possibility to add simple text elements to annotate a note. Alternative: text is not placed directly on the map, but appears if a certain node is clicked on. Like a node description.

fix frontend lint errors

Enable redo/undo functionality again?

• How to make this user friendly and not confusing?
• Test the functionality
• Add the buttons back, I removed them but the functionality is already there.

mobile safari: image upload does not support make image

Open modal instead of opening a new page for about infos

notify other clients when map is deleted

Lock node text input if currently edited by other user

Other users shouldn't be allowed to control text input when the node is already been edited.

Bug: Fix delete job

Idea: Add server-side encryption?

This could be done by using the # (URL Fragment) which is only interpreted on the client side. E.g.: https://some_server.com/ABC#KEY

The key is never sent to the server but can be shared within the team. However, i would propose not to encrypt everything, but images and names of nodes.

improve prod readme

finalize angular setting, fix manifest console error

Improve documentation

• Add image of teammapper on start page
• double check docker and dev start commands - always show two possibilities (running outside / inside of container)
• double check production ssl documentation, as it seems confusing for some parts
• ...

remove webmanifest entries in angular.json

Node with non valid parent breaks map

When two users are concurrently editing a node branch and one is deleting the parent node and one is adding a node, a node without a proper parent is created which breaks the whole map.

Use a transaction when creating the map with existing nodes

Currently, existing nodes are deleted before the json is imported. Thats fine but should be wrapped inside a transaction block. Otherwise the import fails and the map is completly empty.

Add option to delete a mindmap

introduce query timeout in config

By default, the Postgres adapter seems to not use any timeout for Postgres. Should be adjusted with a proper value. See also

• https://node-postgres.com/api/client
• https://github.com/typeorm/typeorm/blob/68a5c230776f6ad4e3ee7adea5ad4ecdce033c7e/src/driver/postgres/PostgresDriver.ts#L1361

Make QR codes downloadable

fix cursor jumping out of node but while editing empty nodes

Fix upload problem which results in stolen nodes

Update angular version

Update npm to next minor version

New minor version of npm available! 8.1.2 -> 8.5.1

Add index to node table for foreign key on mapId

Add support for links e.g. with markdown syntax

https://github.com/markedjs/marked

• remove markdown support for image
• fix bug with not updating node size when editing
• convert old buttons to support new markdown syntax instead of using html

closed by #63

Link creation with support for mobile safari

Links inside a foreign object element seem not to work on mobile safari. Therefore, the link creation strategy has to leverage native svg link elements instead of making use of foreign object. This requires bigger changes in the underlying map lib. The alternative would be to add an onclick element, but this leaves room for possible XSS exploits.

Using native svg links means, that not these node are not editable anymore.

Pressing hotkey N results in strange behaviour

renaming

fix null values in backend mapping which breaks frontend

closed by #52

Improve start page

Related to #163 we can now easily fetch the last created mindmaps.

• Check German and other translations for start page - some seem to be missing
• Add section with last created maps
• ...

delete redirects to local map instead of start screen

Add wss to CSP

broken pdf export in safari

Refactor: Remove deletedAt from typescript interface and test data

add job to trigger delete of old maps

Bug: Failed random import due to order of nodes and delete bugs

Fix copy paste branch color bug for root node

Copy pasted nodes attached to the root node are colored black. When adding new nodes to these, random colors are used.

Remove status bar

Optimize hotkeys

• Enter: Should start text editing mode when a node is selected
• n: Should create a new map instead of redirecting to home

Show share link within the share modal without extra button click

Select all text when double clicking a node

parametrize the sql timeout with docker

Add a readonly invite link and qr code

This would enable teams to either add people just to view a mindmap (guest mode), or to edit one.

Add QR code to share modal

• Unify all options in the share modal which should be used for everyone
• Include a QR code
• Include other share options

UX Spike: Change node creation workflow

1. Create a node
2. Automatically select that node
3. Move camera to node

delete job does not work properly on some servers without errors

This might be caused to async function code in the cron job. Idea: Await result and log errors properly

Better defaults for more security

• Postgres port is mapped to host by default (there is even a warning above it, disable it by default!) [1]
• The mapped volume for postgres should have an identifiable name, with an app prefix. Otherwise, apps will overwrite each other for the db directory
• Currently, if no env file is provided, database default values are used. This could be a big security risk, if one forgets to overwrite it via .env file. Better throw an error.
• A comment is missing in the readme to disable SSL CA check, otherwise the app wont start with a self created Certificate

optimize info modal

• different fonts are used here
• content is too big for mobile to fit on the screen
• version number wrong
• ...

Remove PWA support due to server need