## File: README.md > [!WARNING] > This repository is currently not maintained. If you're interested in becoming a maintainer please [let us know here](https://github.com/mattermost-community/focalboard/issues/5038). > > This repository only contains standalone Focalboard. If you're looking for the Mattermost plugin please see [mattermost/mattermost-plugin-boards](https://github.com/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: * **[Personal Desktop](https://www.focalboard.com/docs/personal-edition/desktop/)**: A standalone, single-user [macOS](https://apps.apple.com/app/apple-store/id1556908618?pt=2114704&ct=website&mt=8), [Windows](https://www.microsoft.com/store/apps/9NLN2T0SX9VF?cid=website), or [Linux](https://www.focalboard.com/download/personal-edition/desktop/#linux-desktop) desktop app for your own todos and personal projects. * **[Personal Server](https://www.focalboard.com/download/personal-edition/ubuntu/)**: A standalone, multi-user server for development and personal use. ## Try Focalboard ### Personal Desktop (Windows, Mac or Linux Desktop) * **Windows**: Download from the [Windows App Store](https://www.microsoft.com/store/productId/9NLN2T0SX9VF) or download `focalboard-win.zip` from the [latest release](https://github.com/mattermost/focalboard/releases), unpack, and run `Focalboard.exe`. * **Mac**: Download from the [Mac App Store](https://apps.apple.com/us/app/focalboard-insiders/id1556908618?mt=12). * **Linux Desktop**: Download `focalboard-linux.tar.gz` from the [latest release](https://github.com/mattermost/focalboard/releases), 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](https://www.focalboard.com/download/personal-edition/ubuntu/). ### API Docs Boards API docs can be found over at ### Getting started Our [developer guide](https://developers.mattermost.com/contribute/focalboard/personal-server-setup-guide) has detailed instructions on how to set up your development environment for the **Personal Server**. You can also join the [~Focalboard community channel](https://community.mattermost.com/core/channels/focalboard) to connect with other developers. 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`](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](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/) 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](CHANGELOG.md) for the latest updates * **Bug Reports**: [File a bug report](https://github.com/mattermost/focalboard/issues/new?assignees=&labels=bug&template=bug_report.md&title=) * **Chat**: Join the [~Focalboard community channel](https://community.mattermost.com/core/channels/focalboard) --- ## 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](http://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](https://www.focalboard.com/download/personal-edition/ubuntu/). 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](core-committers.md). ## If you are a community member seeking a review 1. Submit your pull request (PR). * Follow the [contribution checklist](../contribution-checklist/). 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](https://community.mattermost.com/core/channels/focalboard) channel on our community server. * If you are still stuck, please message Chen Lim (@chenilim on GitHub). 3. [Wait for a review](#if-you-are-awaiting-a-review). * Expect some interaction with at least one reviewer within 5 business days (weekdays, Monday through Friday, excluding [statutory holidays](https://docs.mattermost.com/process/working-at-mattermost.html#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](https://github.blog/2011-03-23-mention-somebody-they-re-notified/) 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](http://www.mattermost.org/mattermost-contributor-agreement/), so you can be added to the Mattermost [Approved Contributor List](https://docs.google.com/spreadsheets/d/1NTCeG-iL_VS9bFqtmHSfwETo5f-8MQ7oMDE5IUYJi_Y/pubhtml?gid=0&single=true). 2. Your ticket is a Help Wanted GitHub issue for the project you're contributing to. - If not, follow the process [here](contributions-without-ticket.md). 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](https://github.com/mattermost/focalboard/blob/main/webapp/i18n/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](code-review.md). To learn about the review process for each project, read the [CONTRIBUTING.md](https://github.com/mattermost/focalboard/blob/main/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: - [Fix a formatting error in help text](https://github.com/mattermost/mattermost-server/pull/5640) - [Fix success typo in Makefile](https://github.com/mattermost/mattermost-server/pull/5809) - [Fix broken Cancel button in Edit Webhooks screen](https://github.com/mattermost/mattermost-server/pull/5612) - [Fix Android app crashing when saving user notification settings](https://github.com/mattermost/mattermost-mobile/pull/364) - [Fix recent mentions search not working](https://github.com/mattermost/mattermost-server/pull/5878) **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](https://community.mattermost.com/core/channels/focalboard) or [opening an issue in the GitHub repository](https://github.com/mattermost/focalboard/issues/new). --- ## 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: - **Scott Bishel** - @scott.bishel on [community.mattermost.com](https://community.mattermost.com/core/messages/@scott.bishel) and [@sbishel](https://github.com/sbishel) on GitHub - **Jesús Espino** - @jesus.espino on [community.mattermost.com](https://community.mattermost.com/core/messages/@jesus.espino) and [@jespino](https://github.com/jespino) on GitHub - **Doug Lauder** - @doug.lauder on [community.mattermost.com](https://community.mattermost.com/core/messages/@doug.lauder) and [@wiggin77](https://github.com/wiggin77) on GitHub - **Miguel de la Cruz** - @miguel.delacruz on [community.mattermost.com](https://community.mattermost.com/core/messages/@miguel.delacruz) and [@mgdelacroix](https://github.com/mgdelacroix) on GitHub - **Harshil Sharma** - @harshil.sharma on [community.mattermost.com](https://community.mattermost.com/core/messages/@harshil.sharma) and [@harshilsharma63](https://github.com/harshilsharma63) on GitHub - **Chen Lim** - @chen-i.lim on [community.mattermost.com](https://community.mattermost.com/core/messages/@chen-i.lim) and [@chenilim](https://github.com/chenilim) on GitHub --- ## 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](focalboard-dev-guide.md). ## Installation prerequisites Check that you have recent versions of the basic dependencies installed: * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) * On Windows, install [Git for Windows](https://gitforwindows.org/) and use the git-bash terminal shell * [Go](https://golang.org/doc/install) * [Node](https://nodejs.org/en/download/) (v10+) and [npm](https://www.npmjs.com/get-npm) On Windows: * Install [Mingw64](https://chocolatey.org/packages/mingw) via [Chocolatey](https://chocolatey.org/) On macOS, to build the Mac app: * Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) (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](https://github.com/mattermost/focalboard), and clone it locally. ## Build and run from the terminal Follow the steps in the [main readme file](https://github.com/mattermost/focalboard#building-the-server). In summary, to build and run the server: ``` 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](https://marketplace.visualstudio.com/items?itemName=golang.Go) and [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) VSCode extensions if you haven't already * Hit F5 and select `Go: Launch Server` * Or, press `Cmd+P` and type `debug ` 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](https://github.com/mattermost/focalboard) or our [Mattermost community channel](https://community.mattermost.com/core/channels/focalboard). 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](https://github.com/mattermost/focalboard/tree/main/mattermost-plugin) in the [Focalboard repo](https://github.com/mattermost/focalboard) 2. Upload it as a [custom plugin to your Mattermost server](https://developers.mattermost.com/integrate/admin-guide/admin-plugins-beta/#custom-plugins) Here are the steps in more detail: ### Building the Focalboard plugin Fork the [Focalboard repo](https://github.com/mattermost/focalboard), clone it locally, and follow the steps in the readme to set up your dev environment. Install dependencies: ``` # First-time setup dependencies cd mattermost-plugin/webapp npm install --no-optional cd ../.. make prebuild ``` Build the plugin: ``` # Build webapp make webapp # Build plugin cd mattermost-plugin make dist ``` Refer to the [dev-release.yml](https://github.com/mattermost/focalboard/blob/main/.github/workflows/dev-release.yml#L168) 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](https://developers.mattermost.com/integrate/admin-guide/admin-plugins-beta/#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](https://developers.mattermost.com/contribute/server/developer-setup/) to set up your environment * In particuler, make sure Docker is set up and running 2. Fork [mattermost-webapp](https://github.com/mattermost/mattermost-webapp), clone it locally, and `make build` 3. Fork [mattermost-server](https://github.com/mattermost/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](https://docs.mattermost.com/configure/configuration-settings.html#site-url)) * Set `ServiceSettings > EnableLocalMode` to `true` ([docs](https://docs.mattermost.com/configure/configuration-settings.html#enable-local-mode)) * Set `PluginSettings > EnableUploads` to `true` ([docs](https://developers.mattermost.com/integrate/admin-guide/admin-plugins-beta/#custom-plugins)) 5. Add an ENV var `MM_SERVICESETTINGS_SITEURL` with the same site URL used in the config 6. Run `make run-server` in Mattermost Now, to build and deploy the plugin: 1. Clone / fork [mattermost/focalboard](https://github.com/mattermost/focalboard) 2. Install the dependencies (see above) 3. Run: ``` make webapp cd mattermost-plugin make deploy ```