focalboard Documentation

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

26,147 stars TypeScript TypeScript 1 file · ~6,116 tokens #asana#collaboration#goal-tracking#golang#hacktoberfest#kanban-board#notion#project
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy focalboard on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name focalboard -p 80:80 --restart always mattermost-community/focalboard:latest
Configured Services & Ports
⚙️ app
image: build locally
🔌 Ports: 80:8000
docker-compose.yml
yaml (docker-compose.yml) 
version: "3"
services:
  app:
    build:
      context: ../
      dockerfile: docker/Dockerfile
    container_name: focalboard
    volumes:
      - fbdata:/opt/focalboard/data
    ports:
      - 80:8000
    environment:
      - VIRTUAL_HOST=focalboard.local
      - VIRTUAL_PORT=8000

volumes:
  fbdata:

File: README.md

[!WARNING]
This repository is currently not maintained. If you're interested in becoming a maintainer please let us know here.

This repository only contains standalone Focalboard. If you're looking for the Mattermost plugin please see mattermost/mattermost-plugin-boards.

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 two editions:

Try Focalboard

Personal Desktop (Windows, Mac or Linux Desktop)

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.

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

text
EXCLUDE_ENTERPRISE="1"

To build the server:

text
make prebuild
make

To run the server:

text
./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

File: docker/README.md

Deploy Focalboard with Docker

Docker

The Dockerfile gives a quick and easy way to build the latest Focalboard server and deploy it locally. In the example below,
the Focalboard database and files will be persisted in a named volumed called fbdata.

From the Focalboard project root directory:

bash
docker build -f docker/Dockerfile -t focalboard .
docker run -it -v "fbdata:/opt/focalboard/data" -p 80:8000 focalboard

Open a browser to localhost to start

Alternative architectures

From the Focalboard project root directory:

bash
docker build -f docker/Dockerfile --platform linux/arm64 -t focalboard .
docker run -it -v "fbdata:/opt/focalboard/data" -p 80:8000 focalboard

Docker-Compose

Docker-Compose provides the option to automate the build and run step, or even include some of the steps from the personal server setup.

To start the server, change directory to focalboard/docker and run:

bash
docker-compose up

This will automatically build the focalboard image and start it with the http port mapping. These examples also create a persistent named volume called fbdata.

To run Focalboard with a nginx proxy and a postgres backend, change directory to focalboard/docker and run:

bash
docker-compose -f docker-compose-db-nginx.yml up

File: docs/code-review.md

Code Review Checklist

Currently, all changes to the product must be reviewed by a core committer.

If you are a community member seeking a review

  1. Submit your pull request (PR).
  2. Wait for a reviewer to be assigned.
    • Product managers are on the lookout for new pull requests and usually handle this for you automatically.
    • If you have been working alongside a core committer, feel free to message them for help.
    • When in doubt, ask for help in the Focalboard channel on our community server.
    • If you are still stuck, please message Chen Lim (@chenilim on GitHub).
  3. Wait for a review.
    • Expect some interaction with at least one reviewer within 5 business days (weekdays, Monday through Friday, excluding statutory holidays).
    • Keep in mind that core committers are geographically distributed around the world and likely in a different time zone than your own.
    • If no interaction has occurred after 5 business days, please at-mention a reviewer with a comment on your pull request.
  4. Make any necessary changes.
    • If a reviewer requests changes, your pull request will disappear from their queue of reviews.
    • Once you've addressed the concerns, please at-mention the reviewer with a comment on your pull request.
  5. Wait for your code to be merged.
    • Larger pull requests may require more time to review.
    • Once all reviewers have approved your changes, they will handle merging your code.

If you are awaiting a review

  1. Wait patiently for reviews to complete.
    • Expect some interaction with each of your reviewers within 5 business days.
    • There is no need to explicitly mention them on the pull request or to explicitly reach out on our community server.
  2. Make any necessary changes.
    • If a reviewer requests changes, your pull request will disappear from their queue of reviews.
    • Once you've addressed the concerns, assign them as a reviewer again to put your pull request back in their queue.

If you are a core committer asked to give a review

  1. Respond promptly to requested reviews.
    • Assume the requested review is urgent and blocking unless explicitly stated otherwise.
    • Try to interact with the author within 2 business days.
    • Configure the GitHub plugin to automate notifications.
    • Review your outstanding requested reviews daily to avoid blocking authors.
    • Prioritize earlier milestones when reviewing to help with the release process.
    • Responding quickly doesn't necessarily mean reviewing quickly! Just don't leave the author hanging.
  2. Feel free to clarify expectations with the author.
    • If the code is experimental, they may need only a cursory glance and thumbs up to proceed with productizing their changes.
    • If the review is large or complex, additional time may be required to complete your review. Be upfront with the author.
    • If you are not comfortable reviewing the code, avoid "rubber stamping" the review. Be honest with the author and ask them to consider another core committer.
  3. Never rush a review.
    • Take the time necessary to review the code thoroughly.
    • Don't be afraid to ask for changes repeatedly until all concerns are addressed.
    • Feel free to challenge assumptions and timelines. Rushing a change into a patch release may cause more harm than good.
  4. Avoid leaving a review hanging.
    • Try to accept or reject the review instead of just leaving comments.
  5. Merge the pull request.
    • Do not merge if there are outstanding changes requested.
    • Merge the pull request, and delete the branch if not from a fork.

File: docs/contribution-checklist.md

Contribution Checklist

Thanks for your interest in contributing code!

Follow this checklist for submitting a pull request (PR):

  1. You've signed the Contributor License Agreement, so you can be added to the Mattermost Approved Contributor List.
  2. Your ticket is a Help Wanted GitHub issue for the project you're contributing to.
    • If not, follow the process here.
  3. Your code is thoroughly tested, including appropriate unit tests, and manual testing.
  4. If applicable, user interface strings are included in the localization file (en.json)
    • In the webapp folder, run npm run i18n-extract to generate the new/updated strings.
  5. The PR is submitted against the main branch from your fork.
  6. The PR title begins with the GitHub Ticket ID (e.g. [GH-394]) and the summary template is filled out.

Once submitted, the automated build process must pass in order for the PR to be accepted. Any errors or failures need to be addressed in order for the PR to be accepted. Next, the PR goes through code review. To learn about the review process for each project, read the CONTRIBUTING.md file of that GitHub repository.

File: docs/contributions-without-ticket.md

Contributions Without Ticket

Contributions for minor corrections and improvements without a corresponding Help Wanted ticket are welcome. For example, a pull request for a bug or incremental improvement, with less than 20 lines of code change, is usually accepted if the change to existing behaviour is minor.

All pull requests submitted without a corresponding ticket will first be reviewed by a core team product manager. Some examples of minor corrections and improvements include:

Note: For pull requests greater than 20 lines of code, a Help Wanted ticket should be opened by the core team. This helps ensure that everything going into the project aligns with a unified vision. Core committers who review the PR are entitled to reject it if there isn't a Help Wanted ticket and feel it significantly changes behavior or user expectations.

The best way to discuss opening a Help Wanted ticket with the core team is by starting a conversation in Contributors channel or opening an issue in the GitHub repository.

File: docs/core-committers.md

Core Committers

A core committer is a maintainer on the Focalboard project who has merge access to the repositories. They are responsible for reviewing pull requests, cultivating the developer community, and guiding the technical vision of Focalboard. If you have a question or need some help, these are the people to ask.

Core Committers

Below is the list of core committers working on Focalboard:

File: docs/dev-tips.md

Developer Tips and Tricks

These tips and tricks apply to developing the standalone Personal Server of Focalboard. For most features, this is the easiest way to get started working against code that ships across editions.

For working with the Focalboard plugin, refer to the Focalboard Plugin Developer's Guide.

Installation prerequisites

Check that you have recent versions of the basic dependencies installed:

On Windows:

On macOS, to build the Mac app:

  • Install Xcode (v12+)
  • Install the Xcode commandline tools, via the IDE or run xcode-select --install

On Linux, to build the Linux app:

  • sudo apt-get install libgtk-3-dev
  • sudo apt-get install libwebkit2gtk-4.0-dev
  • sudo apt-get install autoconf dh-autoreconf

Fork and clone the project source code

Fork the Focalboard GitHub repo, and clone it locally.

Build and run from the terminal

Follow the steps in the main readme file. In summary, to build and run the server:

text
make prebuild
make
 ./bin/focalboard-server

Then open a browser to http://localhost:8000 to access it. The port is configured in config.json.

Once the server is running, you can rebuild just the webapp with make webapp (in a separate terminal window), then reload the browser.

VSCode setup

Here's a recommended dev-test loop using VSCode:

  • Open a bash terminal window to the project folder
  • Run make prebuild to npm install
    • Do this again when dependencies change in webapp/package.json
  • Run cd webapp && npm run watchdev
    • This will auto-build the webapp on file changes
  • Open VSCode
    • Install the Go and ESLint VSCode extensions if you haven't already
  • Hit F5 and select Go: Launch Server
    • Or, press Cmd+P and type debug <space> and pick the option
  • Open a browser to http://localhost:8000
    • The port is configured in config.json

You can now edit the webapp code and refresh the browser to see your changes.

Debugging the web app

You can use your favorite browser to debug the webapp code. With Chrome, open the dev tools with Cmd+Alt+I (Ctrl+Alt+I in Windows).

  • npm run watchdev builds the dev package, which includes source maps from js to typescript
  • In the Chrome devtools source tab, press Cmd+P to jump to a source file

As a starting point, add a breakpoint to the render() function in BoardPage.tsx, then refresh the browser to walk through page rendering.

Debugging the server

Debug the Go code in VSCode. This is set up automatically when you launch the server from there.

To start, add a breakpoint to handleGetBlocks() in server/api/api.go, then refresh the browser to see how data is retrieved.

Localization/Internationalization/Translation

We use i18n to localize the web app. Localized string generally use intl.formatMessage. When adding or modifying localized strings, run npm run i18n-extract in webapp to rebuild webapp/i18n/en.json.

Translated strings are stored in other json files under webapp/i18n, e.g. es.json for Spanish.

Database

By default, data is stored in a sqlite database focalboard.db. You can view and edit this directly using sqlite3 focalboard.db from bash.

Unit tests

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

  • Server unit tests: make server-test
  • Webapp eslint: cd webapp; npm run check
  • Webapp unit tests: make webapp-test
  • Webapp UI tests: cd webapp; npm run cypress:ci

Running into problems or have questions?

If you run into any issues with the steps here, or have any general questions, please don't hesitate to reach out either on GitHub or our Mattermost community channel.

We welcome everyone, and appreciate any feedback.

glhf! :)

File: docs/focalboard-dev-guide.md

Focalboard Plugin Developer's Guide

Important: Effective September 15th, 2023, Mattermost Boards transitions to being fully community supported as the Focalboard Plugin. Mattermost will no longer be maintaining this plugin - this includes bug fixes and feature additions. Instead, the plugin is open-sourced and made available indefinitely for community contributions in GitHub.

To build your own version of it:

  1. Build mattermost-plugin in the Focalboard repo
  2. Upload it as a custom plugin to your Mattermost server

Here are the steps in more detail:

Building the Focalboard plugin

Fork the Focalboard repo, clone it locally, and follow the steps in the readme to set up your dev environment.

Install dependencies:

text
# First-time setup dependencies
cd mattermost-plugin/webapp
npm install --no-optional
cd ../..
make prebuild

Build the plugin:

text
# Build webapp
make webapp

# Build plugin
cd mattermost-plugin
make dist

Refer to the dev-release.yml workflow for the up-to-date commands that are run as part of CI.

Uploading the plugin to your server

You can manually upload the plugin to your Mattermost Server:

  1. Enable custom plugins by setting PluginSettings > EnableUploads to true in the Mattermost config.json file
  2. Navigate to System Console > Plugins > Management and upload the generated .tar.gz package in your mattermost-plugin/dist directory
  3. Enable it (if needed)

Alternatively, you can install Mattermost locally and use make deploy to auto-deploy it for you:

First, build and run Mattermost locally:

  1. Follow the Mattermost Developers Guide to set up your environment
  • In particuler, make sure Docker is set up and running
  1. Fork mattermost-webapp, clone it locally, and make build
  2. Fork mattermost-server and clone it locally
  3. Run make config-reset to generate the config/config.json file
  4. Edit config/config.json:
  • Set ServiceSettings > SiteURL to http://localhost:8065 (docs)
  • Set ServiceSettings > EnableLocalMode to true (docs)
  • Set PluginSettings > EnableUploads to true (docs)
  1. Add an ENV var MM_SERVICESETTINGS_SITEURL with the same site URL used in the config
  2. Run make run-server in Mattermost

Now, to build and deploy the plugin:

  1. Clone / fork mattermost/focalboard
  2. Install the dependencies (see above)
  3. Run:
text
make webapp
cd mattermost-plugin
make deploy

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#asana Browse asana catalog → #collaboration Browse collaboration catalog → #goal-tracking Browse goal-tracking catalog → #golang Browse golang catalog → #hacktoberfest Browse hacktoberfest catalog → #kanban-board Browse kanban-board catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →