Skip to main content

Personal server setup guide

This guide will help you configure your developer environment for the Focalboard Personal Server. For most features, this is the easiest way to get started working against code that ships across editions. For working with Mattermost Boards (Focalboard as a plugin), please refer to the Mattermost Boards Plugin Guide.

Install prerequisites​

All​

Windows​

Mac​

  • Install Xcode (v12+)
  • Install the Xcode Command Line Tools via xcode-select --install

Linux​

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

Fork the project repositories​

Fork the Focalboard GitHub repository and Mattermost GitHub repository. Clone both repositories locally in sibling directories.

Build via the terminal​

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.

Build and run 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.

Set up VS Code​

  • Open a VS Code terminal window in the project folder.
  • Run make prebuild to install packages. Do this whenever dependencies change in webapp/package.json.
  • Run cd webapp && npm run watchdev to automatically rebuild the web app when files are changed. It also includes source maps from JavaScript to TypeScript.
  • Install the Go and ESLint VS Code extensions (if you haven't already).
  • Launch the server:
    • Windows: Ctrl+P, type debug, press the Space key, and select Go: Launch Server.
    • Mac: Cmd+P, type debug, press the Space key, and select Go: Launch Server.
    • If you do not see Go: Launch Server as an option, check your ./.vscode/launch.json file and make sure you are not using a VS Code workspace.
  • Navigate a browser to http://localhost:8000

You can now edit the web app code and refresh the browser to see your changes efficiently.

Debugging the web app: As a starting point, add a breakpoint to the render() function in BoardPage.tsx and refresh the browser to walk through page rendering.

Debugging the server: As a starting point, add a breakpoint to handleGetBlocks() in server/api/api.go and refresh the browser to see how data is retrieved.

Rebuild translations​

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).

Access the database​

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

Unit tests​

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

Unit tests for Focalboard are similar to the web app and server testing requirements.

Staying informed​

Are you interested in influencing the future of the Focalboard open source project? Please read the Focalboard Contribution Guide. We welcome everyone and appreciate any feedback. ❤️ There are several ways you can get involved: