An online whiteboard. Think of it as very poor man's Miro that's open source, free to use and which you can also host yourself. Feel free to try at https://www.ourboard.io/

In this Readme:

User guide
API
Development instructions
Hosting Ourboard

Features and User Guide

The user guide here is bound to be incomplete and out-of-date. Feel welcome to improve it!

Basics

Setting your nickname or sign in

Click on the top right corner nickname field to change your nickname
Optionally, log in with your Google user account. This allows you to create private boards and to track your favorite boards across devices

Adding items

Drag from palette
Double click to add a new note
Use keyboard shortcuts below

Adding links

Paste a link to text, it'll automatically converted to a hyperlink
Select text and paste a link to convert the text to a link

Adding images

Add by dragging a file from your computer or from a browser window
Add by pasting an image from the clipboard using Command-V

Organizing your board

Create an Area and drag items on it to keep them together. When you move the Area, the items move with it!
Use Areas, lines, connections and images to give a visual structure to your board
Lock items in place to prevent accidental moves of static items and lines
Use "structured stickies": 1. Create an Area to be used as a template, choose a nice color 2. Add template content, e.g.. labels like "size" 3. Lock the labels in place. Now you can clone the whole area with a single click on the Clone button (or Cmd-D).

Copy and paste

You can cut/copy/paste contents on the board using keyboard shortcuts
Copy-paste works across boards, so you can do a "backup" by selecting all notes and pasting on another board
You should be able to paste text and images on the board from other applications as well
You can create a full clone of your current board by clicking on the Clone button beside board name

Keyboard shortcuts

These are for Mac. For other Linux/Windows, replace Command with Control.

DEL/Backspace       Delete item
A                   Create new area
N                   Create new note
T                   Create new text box
C                   Select the Connect tool
Esc                 Select the default tool
H                   Hide contents of an area
Command-A           Select all items
Command-V           Paste
Command-C           Copy
Command-X           Cut
Command-Z           Undo
Command-Shift-Z     Redo
Command-D           Duplicate
Command-Minus       Zoom out
Command-Plus        Zoom in
Command-Zero        Reset zoom
Arrow keys          Move selected items. SHIFT for big steps, ALT for fine-tuning.

Pro tips

You can drag the toolbar / palette around, if it gets in your way at the top-center position

Board access controls

All boards created accessible to anyone with the link by default. If you Sign In using Google authentication, you'll also be able to create boards with restricted access. It's possible to grant access to certain emails or to people with an email in a given domain.

API

Ourboard has a limited HTTP API for creating, exporting and updating boards.

All POST and PUT endpoints accept application/json content.

API requests against boards with restricted access require you to supply an API_TOKEN header with a valid API token. The token is returned in the response of the POST request used to create the board.

POST /api/v1/board

Creates a new board. Payload:

{
    "name": "board name as string",
}

You can also specify board access policy, including individual users by email and user email domains:

{
    "name": "board name as string",
    "accessPolicy": {
        "allowList": [
            { email: "coolgirl@reaktor.com" },
            { domain: "reaktor.fi" }
        ]
    }
}

Response:

{
    "id": "board id",
    "accessToken": "************"
}

The accessToken returned here is required for further API calls in case you set an access policy. So, make sure to save the token.

PUT /api/v1/board/:boardId

Changes board name and, optionally, access policy. Payload is similar to the POST request above.

This endpoint always requires the API_TOKEN header.

POST /api/v1/board/:boardId/item

Creates a new item on given board. If you want to add the item onto a specific area/container element on the board, you can find the id of the container by inspecting with your browser.

To create a new item inside a container element:

{
    "type": "note",
    "text": "text on note",
    "container": "container element text or id",
    "color": "hexadecimal color code"
}

To create a new item using coordinates:

{
    "type": "note",
    "text": "text on note",
    "color": "hexadecimal color code",
    "x": 100,
    "y": 100,
    "width": 100,
    "height": 100
}

Response:

{
    "id": "ITEM_ID"
}

PUT /api/v1/board/:boardId/item/:itemId

Creates a new item on given board or updates an existing one. If you want to add the item onto a specific area/container element on the board, you can find the id of the container by inspecting with your browser.

Payload:

{
    "type": "note",
    "text": "text on note",
    "container": "container element text or id",
    "color": "hexadecimal color code",
    "replaceTextIfExists": boolean,      // Override text if item with this id exists. Defaults to false.
    "replaceColorIfExists": boolean,     // Override color if item with this id exists. Defaults to false.
    "replaceContainerIfExists": boolean, // Override container in item with this id exists. Defaults to true.
}

{
    "x": "integer",
    "y": "integer",
    "type": "note",
    "text": "text on note",
    "color": "hexadecimal color code",
    "width": "integer",
    "height": "integer",
}

GET /api/v1/board/:boardId

Return board current state as JSON.

GET /api/v1/board/:boardId/hierarchy

Return board current state in a hierarchical format (items inside containers)

GET /api/v1/board/:boardId/csv

Return board current state in CSV format, where

A container containing only leaf items (note, text) creates a row and each item in that container gets its own column
Container name is a column on the left
Any wrapping containers also add a column on the left

GET /api/v1/board/:boardId/history

Returns the full history of given board as JSON.

Github Issues Integration

Create a board and an Area named "new issues" (case insensitive) on the board.
Add a webhook to a git repo, namely
1. Use URL https://www.ourboard.io/api/v1/webhook/github/{board-id}, with board-id from the URL of you board.
2. Use content type to application/json
3. Select "Let me select individual events" and pick Issues only.
Create a new issue or change labels of an existing issue.
You should see new notes appear on your board

Development

Running locally requires docker-compose which is used for starting the local PostgreSQL database. The script below starts the database, but you must make sure you have a working docker setup on your machine, of course.

Running locally:

yarn install
yarn dev

Run end-to end Playwright tests

yarn test:playwright to run tests once
yarn test:playwright --ui to open the Playwright UI

Connect to the local PostgreSQL database

yarn psql

Tech stack

TypeScript
Harmaja frontend library
WebSockets (express-ws / uWebSockets.js both!)
Express server
Typera for HTTP API

Developing with production data

Do not run your local server against the production database, or you'll corrupt production. The server's in memory state will be out of sync with DB and bad things will happen.

Instead, do this.

Capture a backup and download it: heroku pg:backups:capture, then heroku pg:backups:download.
Restore the backup to your local database: pg_restore --verbose --clean --no-acl --no-owner -d postgres://r-board:secret@localhost:13338/r-board latest.dump
Start you local server using yarn dev

If you need the local state for a given board in localStorage, you can

extract the content in the browser devtools, when viewing production site in browser, using localStorage["board_<boardid>"]
Copy that string to clipboard
Run the following in your localhost site console:

localStorage["board_32de1a50-09a6-4453-9b9e-ed10c56afa99"]=JSON.stringify( <paste content here> )

Copy the result string, navigate to your localhost site and paste the same value to the same localStorage key. Refresh and enjoy.

Building and pushing the raimohanska/ourboard docker image

docker login
docker build . -t raimohanska/ourboard:latest
docker push raimohanska/ourboard:latest

Hosting

OurBoard is made to be easy to deploy and host. It consists of a single Node.js process that needs a PostgreSQL database for storing data. Using environment variables (see below) you can set the URL for the database and optionally configure OurBoard to use S3 for image assets and Google for authentication. By default it comes without authentication / authorization and stores image assets in the local file system.

Heroku

If it suits you, Heroku is likely to be the easiest way to host your own OurBoard server. You should be able to host your own OurBoard instance pretty easily in Heroku. This repository should be runnable as-is, provided you set up some environment variables, which are listed below.

Docker

OurBoard is available as a Docker image so you can deploy it with Docker or your favorite container environment of choice. To get an OurBoard docker image, you can either:

Use the raimohanska/ourboard image in Docker Hu

Ourboard

Install / Use

README