mattermost/focalboard

Focalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.

Warning

Effective September 15th, 2023, Mattermost, Inc. staff are no longer reviewing or merging pull requests for either Focalboard or the Mattermost Boards plugin in this repository (mattermost/focalboard). We encourage the community to fork this repository for continued development and contributions.

The reason behind these changes is to focus Mattermost developer resources on improving the platform’s performance and core features to ensure Mattermost continues being resilient, stable, and best-in-breed for critical operations.

️💡 Learn more

Focalboard

Focalboard is an open source, multilingual, self-hosted project management tool that's an alternative to Trello, Notion, and Asana.

It helps define, organize, track and manage work across individuals and teams. Focalboard comes in three editions:

• Focalboard plugin: The Focalboard plugin integrates into an exsting Mattermost instance to combine project management tools with messaging and collaboration for teams of all sizes.

• Personal Desktop: A standalone, single-user macOS, Windows, or Linux desktop app for your own todos and personal projects.

• Personal Server: A standalone, multi-user server for development and personal use.

Try Focalboard

Mattermost Plugin

After downloading and installing the plugin in the System Console, select the menu in the top left corner and select Boards. Access the latest releases of the focalboard plugin by downloading the mattermost-plugin-focalboard.tar.gz file from the releases in this repository: https://github.com/mattermost/focalboard/releases

Personal Desktop (Windows, Mac or Linux Desktop)

• Windows: Download from the Windows App Store or download focalboard-win.zip from the latest release, unpack, and run Focalboard.exe.
• Mac: Download from the Mac App Store.
• Linux Desktop: Download focalboard-linux.tar.gz from the latest release, unpack, and open focalboard-app.

Personal Server

Ubuntu: You can download and run the compiled Focalboard Personal Server on Ubuntu by following our latest install guide.

API Docs

Boards API docs can be found over at https://htmlpreview.github.io/?https://github.com/mattermost/focalboard/blob/main/server/swagger/docs/html/index.html

Getting started

Our developer guide has detailed instructions on how to set up your development environment for the Personal Server. You can also join the ~Focalboard community channel to connect with other developers.

Clone mattermost-server into sibling directory.

Create an .env file in the focalboard directory that contains:

EXCLUDE_ENTERPRISE="1"

To build the server:

make prebuild
make

To run the server:

 ./bin/focalboard-server

Then navigate your browser to http://localhost:8000 to access your Focalboard server. The port is configured in config.json.

Once the server is running, you can rebuild just the web app via make webapp in a separate terminal window. Reload your browser to see the changes.

Building and running standalone desktop apps

You can build standalone apps that package the server to run locally against SQLite:

• Windows:
  • Requires Windows 10, Windows 10 SDK 10.0.19041.0, and .NET 4.8 developer pack
  • Open a git-bash prompt.
  • Run make prebuild
  • The above prebuild step needs to be run only when you make changes to or want to install your npm dependencies, etc.
  • Once the prebuild is completed, you can keep repeating the below steps to build the app & see the changes.
  • Run make win-wpf-app
  • Run cd win-wpf/msix && focalboard.exe
• Mac:
  • Requires macOS 11.3+ and Xcode 13.2.1+
  • Run make prebuild
  • The above prebuild step needs to be run only when you make changes to or want to install your npm dependencies, etc.
  • Once the prebuild is completed, you can keep repeating the below steps to build the app & see the changes.
  • Run make mac-app
  • Run open mac/dist/Focalboard.app
• Linux:
  • Tested on Ubuntu 18.04
  • Install webgtk dependencies
    • Run sudo apt-get install libgtk-3-dev
    • Run sudo apt-get install libwebkit2gtk-4.0-dev
  • Run make prebuild
  • The above prebuild step needs to be run only when you make changes to or want to install your npm dependencies, etc.
  • Once the prebuild is completed, you can keep repeating the below steps to build the app & see the changes.
  • Run make linux-app
  • Uncompress linux/dist/focalboard-linux.tar.gz to a directory of your choice
  • Run focalboard-app from the directory you have chosen
• Docker:
  • To run it locally from offical image:
    • docker run -it -p 80:8000 mattermost/focalboard
  • To build it for your current architecture:
    • docker build -f docker/Dockerfile .
  • To build it for a custom architecture (experimental):
    • docker build -f docker/Dockerfile --platform linux/arm64 .

Cross-compilation currently isn't fully supported, so please build on the appropriate platform. Refer to the GitHub Actions workflows (build-mac.yml, build-win.yml, build-ubuntu.yml) for the detailed list of steps on each platform.

Unit testing

Before checking in commits, run make ci, which is similar to the .gitlab-ci.yml workflow and includes:

• Server unit tests: make server-test
• Web app ESLint: cd webapp; npm run check
• Web app unit tests: cd webapp; npm run test
• Web app UI tests: cd webapp; npm run cypress:ci

Staying informed

• Changes: See the CHANGELOG for the latest updates
• Bug Reports: File a bug report
• Chat: Join the ~Focalboard community channel

focalboard's Issues

Text editor is black on white even in dark mode

Summary:
Adding card text shows a black-on-white text editor in dark mode.

Steps to reproduce the behavior:

1. Turn on dark mode
2. Open a card and tap "add content" at the bottom
3. Text editor appears black on white

Expected behavior:
Expect a dark mode text editor, with light text on dark background

Screenshots:

Platform:

• Chrome 88 on macOS 10.15.7

Feature Request: Offer download of compiled binaries for Focalboard Personal Desktop

Feedback from HackerNews: https://news.ycombinator.com/item?id=26499443

We can perhaps look at adding binaries from our build system for the desktop and server editions, and perhaps add some instructions too.

Wondering if the core committers produced the binaries, would there be people in the community interested in helping us draft the install guides for different platforms?

Internationalize hardcoded strings

There are hardcoded strings sprinkled throughout the app. These should be replaced with intl.FormatMessage calls to pull them from the translation tables.

• Easiest way to find hardcoded strings is to change the UI language to Spanish from the Settings menu, then look for strings that haven't changed.
• Remember to run cd webapp; npm run i18n-extract to extract newly added translations to the language tables.

View switches to the first one when searching text

Summary:
View changes when searching text

Steps to reproduce the behavior:

1. Open a board with 2 or more views, select the second one
2. Search for text
3. The view changes to the first one

Expected behavior:
The view remains the same

Platform:

• Chrome 88 on macOS 10.15.7

Website fonts are hard to see

Summary:

The top-right navigation bar's font is too thin to be readable, and the links inside the the presentation speech under the screenshot on the homepage are too low-contrast from the background.

Not able to register user on local server

Summary:
Getting error "invalid email format" when trying to register user in local server

Steps to reproduce the behavior:

1. Build server binary using steps provided in Readme
2. Try to register new user
3. Enter details
4. See error

Expected behavior:
Account registration should have been successful.

Screenshots:

Platform:

• Browser and version: Firefox
• OS and version: macOS

Keyboard support: Board view

Keyboard navigation is needed in general. This issue tracks the need to be able to use the board view / editor with just a keyboard. E.g.

• Activate viewHeader actions (sort, filter, etc.)
• Select card
• Open card
• Etc.

More complex actions:

• Select multiple cards (shift+arrow)
• Move card(s) to different columns
• Etc.

Property type: Email

Add an email property type

Mac App icon is hard to see

Summary:
The Mac app icon has a transparent background that is hard to see on dark or blue backgrounds

Expected behavior:
Icon has a contrasting background

Screenshots:

Platform:

• macOS 10.15.7

Add some `good first issue` tickets

@chenilim wondering your thoughts on adding some good first issue tickets? The below prompt came up when I checked out the repo this morning:

Also, @haardikdharma10, are there certain tickets you'd be interested in working on in this repo?

Read-only token removed from url when changing views

Summary:
After changing views on a read-only view, refreshing results in access denied.

** Steps to reproduce the behavior:**

1. Share a board with 2+ views
2. Open the share link in an incognito window
3. Use the view menu to change the view
4. Refresh the browser
5. Access denied error

Expected behavior
Expect the view to refresh

Platform:

• Chrome 88 on macOS 10.15.7

Additional context
Looks like the readonly token is stripped out of the URL

Clicking on the view name changes the input size, causing a jump

Make the default min-width wider

Feature: Snap / Flatpack package for Focalboard Desktop 🐧

It would be great to have a Snap package and/or a Flatpak package for easier installation and automatic upgrades.

PS: Thank you so much! Focalboard looks great! 🙏

Alternative installation options

Summary:

The installation steps are great, however it would be convenient for a lot of users if this could be encapsulated in a simple Dockerfile/image.

Steps to reproduce the behavior:

1. Install by following the instructions
2. Wish that you'd been able to execute docker run instead... ;)

Expected behavior:

Add a Dockerfile to the repo as a first step, with publication of the image on Github/DockerHub/other as a second step.

Screenshots:
N/A

Platform:
N/A

Additional context:
This looks like an amazing project, easier installation/runtime would be really appreciated!

Make doesn't build the webapp

Summary:
Just running make on a fresh clone doesn't build the webapp.

Steps to reproduce the behavior:

1. Run make prebuild
2. Run make
3. Start the server
4. See 404 error

Expected behavior:
See webpage

Platform:

• Chrome 89 on macOS 10.15.7

Additional context:
Make should build the webapp and server

Fix Dark Mode select colors

Summary:
The select option colors are unreadable.

Steps to reproduce the behavior:

1. Change to dark mode
2. Notice select option colors

Expected behavior:
Text is easy to read

Screenshots:

Platform:

• Chrome 88 on Mac 10.15.7

Property type: Checkbox

Add a checkbox property type (true or false state)

Add a "Share feedback | View Source Code" links in the UI

Add a "Share feedback | View Source Code" links in the UI.

Point both links to a re-direct under focalboard.com so we can change the links at any time (important for those that are self-hosting older versions if we want to change links)

View Source Code redirect to https://github.com/mattermost/focalboard

Share feedback re-direct to https://github.com/mattermost/focalboard/wiki/Share-your-feedback!

We want to focus traffic on the GitHub page initially so we get more star ratings and interactions from community.

The installation instructions for the server install don't seem to work.

Bug report from HackerNews: https://news.ycombinator.com/reply?id=26500833&goto=item%3Fid%3D26499062%2326500833

The installation instructions for the server install don't seem to work.
> wget https://releases.mattermost.com/focalboard/0.5.0/focalboard-...

> tar -xvzf focalboard-server-linux-amd64.tar.gz

The file is actually a zip with the tar.gz inside:

focalboard-server-linux-amd64.tar.gz: Zip archive data, at least v2.0 to extract

$ unzip -l focalboard-server-linux-amd64.tar.gz

Archive: focalboard-server-linux-amd64.tar.gz

Length Date Time Name

--------- ---------- ----- ----

12461347 02-02-2021 00:38 focalboard-server-linux-amd64.tar.gz

-------- -------

12461347 1 files

Running tar directly (as written in the instructions) will fail with:

$ tar -tzvf focalboard-server-linux-amd64.tar.gz

tar: invalid magic

tar: short read

It seems like there's something unintentionally producing a zip at the end of the build process.

Add docker-compose definition

• There's now a docker image available for the server: #76
• There's an issue open to add CD to the docker image: #92

once the image is available on docker hub it could be great to have a little docker-compose.yml with all dependencies (postresql, nginx/traefik, etc...) bundled, so that end users may get started as simple as running docker-compose up.

Making the compose file would be as simple as following this guide: https://www.focalboard.com/download/personal-edition/ubuntu/

Keyboard Navigation: Sidebar

Keyboard navigation is needed in general. This issue tracks the need to be able to use the sidebar with just a keyboard. E.g.

• Select board to view
• Activate board actions menu
• Add new board
• Settings menu
• Etc.

Keyboard support: Table view

Keyboard navigation is needed in general. This issue tracks the need to be able to use the table editor with just a keyboard. E.g.

• Activate view header actions (sort, filter, etc.)
• Navigate cells with arrow keys
• Change select-property cells
• Activate column header actions menu
• Etc.

Where to report Security Vulnerabilities?

Summary:
I need to report a security vulnerability. Where can I do that?

Sharing doesn't work until token is regenerated

Summary:
Sharing a board doesn't work when it's enabled

Steps to reproduce the behavior:

1. Open a board
2. Click on ... and pick "Share board"
3. Turn on the switch and copy the link
4. Paste the link in a new anonymous window

Access denied error

Expected behavior:
The board appears

Platform:

• Chrome 89 on macOS 10.15.7

Additional context:
Note that the token (r querystring) is empty. Regenerating the token, then copying the new link works.

Add Cypress tests: Login actions

Simulate user creation, login, and logout actions

• Register user
• Login
• Change password
• Logout

Mac app doesn't render title completely on first load

Summary:
When opening the Mac app to an existing board, the title is cut off until clicking on it.

Steps to reproduce the behavior:

1. Open Mac app v0.6.0 with a previous board
2. Notice the title is cut off

Expected behavior:
The title is show correctly.

Screenshots:

Platform:

• macOS 10.15.7
• Focalboard 0.6.0

Additional context:
Appears to be a rendering artifact of the web view.

Property type: URL

Add a URL property type

Property type: Phone number

Add a phone number property type

Feature Request (Enterprise Edition): Federated authentication: SAML/OAuth/LDAP/RADIUS

Support some kind of federated authentication, well-known external user authentication.

It can be

• https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol
• https://en.wikipedia.org/wiki/RADIUS
• https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language
• https://en.wikipedia.org/wiki/OAuth

Use cases I am thinking about are

• On-premises Microsoft Active Directory
• https://azure.microsoft.com/en-us/services/active-directory/
• https://www.okta.com/
• https://auth0.com/
• https://aws.amazon.com/cognito/
• https://duendesoftware.com/products/identityserver
• https://jumpcloud.com/

On Focalboard.com change "Home" to "View Source" pointing to https://github.com/mattermost/focalboard

View Source is one of our biggest differentiators, and we should drive traffic to our GitHub page and get more star rating and community engagement.

Logo on the left brings people to the home page, so we don't lose functionality.

Keyboard navigation: Card dialog

Keyboard navigation is needed in general. This issue tracks the need to be able to use the card editor with just a keyboard. E.g.

• Navigate property fields
• Add comment
• Add / edit content
• Etc.

Missing Edit icon

Summary

The Edit and Delete options are misaligned when selecting a new board template.

Steps to reproduce

1. Click on Add Board.
2. Click on ... on the right hand side of any template.

Observed behaviour (that appears unintentional)

Expected behaviour

Edit and Delete should be aligned. (Maybe add an icon for Edit)

Feature request: personal/private boards

It would be helpful to be able to create boards that are not shared with all users.

Windows App clicking on "+New" doesn't work

Summary:
Windows App clicking on "+New" doesn't work

Steps to reproduce the behavior:

1. Install Windows app on Windows 10
2. Go to +Add Board > Roadmap
3. Click '+New'

Expected behavior:
New row created

Observed behavior:
Nothing happens

Screenshots:
If applicable, add screenshots to help explain your problem.

Platform:

• OS and version: Windows 10

Additional context:
Also, notice there's no version number in the top left--wondering if this is an old build on Windows...

Server Unit tests: websocket APIs

Add unit tests for the websocket APIs

Documentation for linux personal desktop is incorrect

Summary:
The information for downloading and installing linux personal desktop at https://www.focalboard.com/download/personal-edition/desktop/ is incorrect. On downloading and extracting focalboard-linux.tar.gz from github (for 0.6.1 at least) the directory listing is as shown in the screenshot below.

Rather than "Open focalboard from within the focalboard folder" , you have to run focalboard-app from the focalboard-app folder.

Expected behavior:
The documentation should match the folder and file name provided in the download

Screenshots:

Platform:

• Ubuntu 20.04

Feature request: scrum/sprints

I really love the project you have going on, and I see myself using it.

It would be very helpful to have scrum/sprints management feature for big projects, which could make Focalboard an alternative to OpenProject.
Is it part of your roadmap to make something similar to this feature ? Or would accept a PR?

Download file is a zip file, not a tar.gz as documented

Summary:

https://www.focalboard.com/download/personal-edition/ubuntu/#install-focalboard states that a user should download and unpack a file named https://releases.mattermost.com/focalboard/0.5.0/focalboard-server-linux-amd64.tar.gz however this file is actually a zip file with the tar.gz file inside it named the same.

Steps to reproduce the behavior:

1. https://www.focalboard.com/download/personal-edition/ubuntu/#install-focalboard
2. Download the installation archive
3. Try to unpack it with tar -zxvf focalboard-server-linux-amd64.tar.gz
4. See error

Expected behavior:
File should be a .tar.gz or a .zip file, not one inside the other with incorrect file endings.

Property type: Date

Add a date property type
P2: Add date picker UI

Duplicate board should be added below the original board in the sidebar.

Summary

When adding a duplicate board, it should be added below the original board and not above it.

UPDATE: This happens when adding an empty board as well. It is added above the existing boards.

Steps to reproduce

1. Add a new board (E.g Meeting notes)
2. From the sidebar, click on the ... icon and select duplicate board.

Observed behaviour (that appears unintentional)

Expected behaviour

The duplicate board ('Copy of Meeting Notes') should be added below the original board and not above it.

Fix server lint issues

Run make server-lint to see the list of Go lint issues. We should incrementally fix them.

`session_expire_time` and `session_refresh_time` not present in the bundle and needs a better default value when it is not found.

Summary:
When I login, no error is shown but the page is refreshed back to the login page
I tested on purpose with a wrong login and an error is shown

Steps to reproduce the behavior:

1. Start the server, everything looks fine:

./focalboard-server 
2021/03/18 06:00:44 Focalboard Server
2021/03/18 06:00:44 Version: 0.6.0
2021/03/18 06:00:44 Edition: linux
2021/03/18 06:00:44 Build Number: 644234983
2021/03/18 06:00:44 Build Date: Thu Mar 11 21:47:39 UTC 2021
2021/03/18 06:00:44 Build Hash: b9667151fce025228a82d3ab73c5c3ecca9be3f0
2021/03/18 06:00:44 readConfigFile
2021/03/18 06:00:44 {ServerRoot:http://localhost:8088 Port:8088 DBType:sqlite3 DBConfigString:./focalboard.db UseSSL:false WebPath:./pack FilesPath:./files Telemetry:true WebhookUpdate:[] Secret: SessionExpireTime:0 SessionRefreshTime:0 LocalOnly:true EnableLocalMode:false LocalModeSocketLocation:/var/tmp/focalboard_local.socket}
2021/03/18 06:00:44 connectDatabase
{"level":"info","ts":1616043644.5071993,"caller":"server/server.go:168","msg":"Server.Start"}
2021/03/18 06:00:44 http server started on :8088

2. Create an account on http://localhost:8088/login
3. Try to login
4. The homepage of Focalboard loads half a second then is refreshed back to http://localhost:8088/login
5. The terminal shows these error messages:

2021/03/18 06:01:18 Single User: false
2021/03/18 06:01:18 API ERROR 401, err: unable to get the session for the token: sql: no rows in result set

Expected behavior:
Being able to login

Platform:

• Browser and version: Firefox 86.0.1 (64-bit) and Chromium Version 88.0.4324.182
• OS and version: Debian 10 (stable)

Additional context:
I deactivated the Firefox extensions Noscript and Ublock origin

Feature request: Kanboard importer

Enhancement idea for a Kanboard importer from mandiantBob on HackerNews:

I just downloaded and tested the standalone desktop app. It has a very pretty and responsive interface compared to Kanboard.
I have been self hosting Kanboard on my rpi for my own work, and I think that Kanboard still has many 'poweruser' features that Focalboard is missing.

If there is an easy way for me to migrate my Kanboard data over to Focalboard, I would definitely give it a shot as a daily driver.

Make label colors configurable per theme, and darken for dark theme

The label colors are defined in variables.scss. Should be able to override these in theme.ts.

Currently, the "dark theme" label colors are too light. Need to adjust these to be darker, so the text is readable.

Extend import scripts

Right now, we have scripts to import basic info from popular systems like Trello, Asana, and Notion. They can pull in the card titles, descriptions, and basic properties from a single board. Expand these further to do things like:

• Import advanced properties (e.g. dates, text, numbers)
• Handle multiple boards
• Handle Trello PowerUp properties
• Handle sub-tasks in Asana
• Use the Notion API to import rich data
• Import from other popular systems

This high-level issue can be split into smaller ones to handle targeted improvements

Build and publish Docker container

The Docker container should be build and uploaded to Docker Hub using github actions, perhaps a develop tag which would be for the latest HEAD and latest tag which points to tagged versions in Git.

Change link on Focalboard.com to point straight to Github repo

Reason:

Focalboard.com was trending #2 on HackerNews (which is awesome!) and it was difficult to find the repo from the Focalboard main page. In future, we would want the GitHub repo to trend to get more stars and engagement. All said, though, super awesome to be trending!!

Documentation on building/running Docker container

There should be some information on how to build and run the Docker container in the README.

File \ New on Mac app opens a blank window

Summary:
New windows are blank, and can't be used

Steps to reproduce the behavior:

1. Open Mac App
2. Select File \ New (or press Cmd+N)
3. A blank window appears

Expected behavior:
A window with boards appear

Platform:

• macOS 10.15.7

Save card title when closing card

Repro:

• Edit a card
• Click on the title and enter some text
• Click on the background to close the card

Expected:

• The modified title is saved

Actual:

• The modified title is not saved