Project setup

1. Copy the source/ directory into your repository root, e.g. ./focalboard-server/.
2. Ensure your go.mod either references the focalboard module or copy the module contents into your own module using replace directives:

   replace github.com/mattermost/focalboard/server => ./focalboard-server
   

3. Create a config.json in your working directory (the server reads it at startup):

   {
     "serverRoot": "http://localhost:8000",
     "port": 8000,
     "dbtype": "sqlite3",
     "dbconfig": "./focalboard.db",
     "postgres_dbconfig": "",
     "useSSL": false,
     "webpath": "./pack",
     "filespath": "./files",
     "telemetry": false,
     "prometheusAddress": "",
     "session_expire_time": 2592000,
     "session_refresh_time": 18000,
     "localOnly": false,
     "enableLocalMode": true,
     "localModeSocketLocation": "/var/tmp/focalboard_local.socket"
   }
   

4. Set environment variables as needed:
   • FOCALBOARD_DB_TYPE - override dbtype (sqlite3 or postgres)
   • FOCALBOARD_DB_CONFIG - override dbconfig connection string
   • EXCLUDE_ENTERPRISE=1 - build without enterprise features
5. Build and run:

   cd source && go build -o bin/focalboard-server ./main && ./bin/focalboard-server
   

6. The API is available at http://localhost:8000/api/v2/.

Public API

Because no Go source excerpts were provided, the following documents the package-level structure visible from the file tree and standard Focalboard conventions. Only symbols clearly named in the directory structure are referenced.

app.App

// package app
type App struct { /* store, config, services wired at construction */ }

func NewApp(params Params) (*App, error)

The central application object. Instantiate via NewApp with a Params struct containing the store, config, and service dependencies. All business logic methods (GetBoard, CreateCard, ImportArchive, etc.) live on *App.

api.API

// package api
type API struct { /* wraps *app.App, registers HTTP routes */ }

func NewAPI(app *app.App, authService auth.AuthInterface, ...) *API
func (a *API) RegisterRoutes(r *mux.Router)

Thin HTTP layer that translates HTTP requests into app.App method calls. Call RegisterRoutes on a Gorilla mux.Router to attach all /api/v2/... endpoints. Use this when embedding Focalboard's REST surface into an existing Go HTTP server.

model.Board

// package model
type Board struct {
    ID          string            `json:"id"`
    TeamID      string            `json:"teamId"`
    CreatedBy   string            `json:"createdBy"`
    Title       string            `json:"title"`
    Type        BoardType         `json:"type"`
    Properties  map[string]any    `json:"properties"`
    CreateAt    int64             `json:"createAt"`
    UpdateAt    int64             `json:"updateAt"`
    DeleteAt    int64             `json:"deleteAt"`
}

Core data transfer object for a board. Passed to and returned from all board-related app.App methods and serialized directly to/from JSON in API responses. Use when constructing board payloads or parsing webhook events.

model.Block

// package model
type Block struct {
    ID       string         `json:"id"`
    BoardID  string         `json:"boardId"`
    ParentID string         `json:"parentId"`
    Type     BlockType      `json:"type"`
    Fields   map[string]any `json:"fields"`
    CreateAt int64          `json:"createAt"`
    UpdateAt int64          `json:"updateAt"`
    DeleteAt int64          `json:"deleteAt"`
}

Fundamental content unit. Cards, views, and text blocks are all Block variants distinguished by Type. Patch batches of blocks using the /api/v2/boards/{boardID}/blocks endpoints.

Working examples

Scenario - Embedding the server in an existing Go application

Start a Focalboard server alongside your own HTTP server by importing the server package and calling its constructor, then mount its router on a subpath.

package main

import (
    "log"
    "net/http"

    fbserver "github.com/mattermost/focalboard/server/server"
)

func main() {
    cfg, err := fbserver.ReadConfigFile("config.json")
    if err != nil {
        log.Fatal("config:", err)
    }

    srv, err := fbserver.New(fbserver.Params{
        Cfg:         cfg,
        SingleBoard: false,
    })
    if err != nil {
        log.Fatal("init:", err)
    }

    if err := srv.Start(); err != nil {
        log.Fatal("start:", err)
    }
    // Focalboard now listens on cfg.Port
    // Your own logic runs below:
    http.ListenAndServe(":9000", yourOwnMux())
}

Scenario - Using the Go client to create a board programmatically

Use the client package to talk to a running Focalboard instance from another Go service or a test harness.

package integration_test

import (
    "testing"

    fbclient "github.com/mattermost/focalboard/server/client"
    "github.com/mattermost/focalboard/server/model"
)

func TestCreateBoard(t *testing.T) {
    c := fbclient.NewClient("http://localhost:8000", "")

    // Login
    _, resp, err := c.Login(fbclient.LoginRequest{
        Type:     "normal",
        Username: "admin",
        Password: "password",
    })
    if err != nil || resp.StatusCode != 200 {
        t.Fatalf("login failed: %v", err)
    }

    board := &model.Board{
        TeamID: "0",
        Title:  "My New Board",
        Type:   model.BoardTypeOpen,
    }
    created, _, err := c.CreateBoard(board)
    if err != nil {
        t.Fatalf("create board: %v", err)
    }
    t.Logf("created board id=%s", created.ID)
}

Scenario - Subscribing to real-time updates via WebSocket

Connect to the WebSocket endpoint to receive live block-change events for a board.

package main

import (
    "encoding/json"
    "log"

    "github.com/gorilla/websocket"
    "github.com/mattermost/focalboard/server/model"
)

func watchBoard(token, boardID string) {
    conn, _, err := websocket.DefaultDialer.Dial(
        "ws://localhost:8000/ws/onchange", nil,
    )
    if err != nil {
        log.Fatal("ws dial:", err)
    }
    defer conn.Close()

    // Authenticate
    conn.WriteJSON(map[string]string{"action": "auth", "token": token})

    // Subscribe to board
    conn.WriteJSON(map[string]any{
        "action":  "subscribe",
        "boardId": boardID,
    })

    for {
        _, msg, err := conn.ReadMessage()
        if err != nil {
            log.Println("ws read:", err)
            return
        }
        var event map[string]any
        json.Unmarshal(msg, &event)
        log.Printf("event: %+v", event)
    }
}

File walkthrough

• admin-scripts/ - Bash utilities for ops tasks; reset-password.sh resets a user's password directly against the DB.
• api/ - One file per resource group (boards.go, blocks.go, cards.go, etc.); each registers its routes and delegates to app.
• app/ - Mirror of api/ at the business logic level; contains the actual query/mutation logic and unit tests (*_test.go).
• assets/ - Embedded static files (images, default templates) compiled into the binary.
• auth/ - Session creation, token validation, and MFA helpers.
• client/ - Typed Go HTTP client wrapping every REST endpoint; useful for tests and CLIs.
• integrationtests/ - Black-box tests that spin up a real server and exercise the full stack.
• main/ - main.go only; parses flags, loads config, calls server.New, calls server.Start.
• model/ - All shared structs (Board, Block, Card, User, Team, Category, etc.) and their JSON tags.
• server/ - Server struct, constructor, Start/Stop lifecycle, TLS, and HTTP listener setup.
• services/ - Interfaces and implementations for pluggable concerns: store (SQLite/Postgres), permissions, notifications, telemetry.
• swagger/ - swagger.yml OpenAPI spec and pre-rendered HTML documentation.
• utils/ - String helpers, ID generation, time utilities shared by all packages.
• web/ - webHandler that serves the compiled React SPA from disk or embedded FS.
• ws/ - WebSocket hub: manages client connections, subscriptions, and fan-out of block-change events.

Common pitfalls and fixes

• CGo disabled / SQLite build failure: cgo: C compiler "gcc" not found - fix by installing build-essential (Linux) or Xcode CLI tools (macOS), or switch dbtype to postgres for a pure-Go path.
• config.json not found at runtime: The server looks for config.json in the current working directory, not the binary's directory - fix by cd-ing to the project root before running, or pass --config /absolute/path/config.json.
• Port 8000 already in use: Default port collides with other dev servers - change "port" in config.json and ensure serverRoot URL matches.
• WebSocket connections rejected with 403: The WS endpoint requires a valid session token passed as {"action":"auth","token":"..."} immediately after connect - clients that skip the auth frame are silently dropped.
• make prebuild fails because Node version is too old: The React frontend requires Node 16+; nvm use 18 before running make prebuild.
• Postgres schema not initialized: On first run against a new Postgres DB the server auto-migrates, but the DB user must have CREATE TABLE privileges - grant with GRANT ALL PRIVILEGES ON DATABASE focalboard TO fbuser;.

Vibe-coding prompt template

I have a copy of the Focalboard backend server source in the `source/` directory
of this project. I also have a USAGE.md file that documents its structure,
public API, and working examples.

Please help me integrate the Focalboard backend (upstream: mattermost/focalboard,
source root: server/) into my existing Go project step by step:

1. Read USAGE.md fully before writing any code.
2. Check source/server/, source/app/, source/api/, and source/model/ for the
   real struct and function names - do not invent any symbols.
3. Add the necessary replace directives to my go.mod so my module can import
   from source/.
4. Create or update config.json with sensible defaults for my environment
   (DB type, port, file paths).
5. Show me how to instantiate the server using server.New / server.Start and
   mount it alongside my existing HTTP mux.
6. Show me how to use source/client/ to create a board and add blocks from a
   separate Go service.
7. Show me how to connect to the WebSocket endpoint in source/ws/ to receive
   live updates.
8. Point out any CGo / SQLite build requirements I need to satisfy.

Use only APIs that appear in the file tree and USAGE.md. Produce complete,
compilable Go code snippets with correct import paths.

License and credit

Focalboard is released under the MIT License (see source/LICENSE if present; also confirm in the upstream repository). The original project is developed by Mattermost, Inc. and the community.

Upstream repository: https://github.com/mattermost/focalboard

Note: As of the upstream README, this repository is no longer actively maintained. For the Mattermost plugin variant see mattermost/mattermost-plugin-boards.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

HTML5, JavaScript & Web Widgets

$4