Set up a Fleetbase development environment — mount live source, link packages, and work on extensions with hot reload.

Development Setup

This guide is for contributors and extension developers who need to work directly on Fleetbase source code or link a local package into a running instance. If you just want to run Fleetbase locally without modifying its internals, see Running Locally instead.

Prerequisites

Docker v20.10+ and Docker Compose v2.0+
Git with submodule support
Node.js v18+ and pnpm — for running the console locally outside Docker
PHP 8.1+ and Composer — for backend package work outside Docker

Clone with Submodules

The Fleetbase repository uses Git submodules for its packages. Development setup requires pulling all submodules so the packages/ directory contains live source:

git clone https://github.com/fleetbase/fleetbase.git
cd fleetbase
git submodule update --init --recursive

This populates packages/ with the source for all first-party extensions (FleetOps, Storefront, Pallet, Ledger, and others). Each package contains two directories:

Directory	Contents
`addon/`	Ember.js frontend addon code
`server/`	Laravel backend package (service provider, models, routes, migrations)

Backend Development

Mount Source into Docker

To work on the API or packages with live source, add volume mounts in docker-compose.override.yml so your local files are used directly by the running containers:

services:
  application:
    environment:
      ENVIRONMENT: "development"
      APP_DEBUG: "true"
    volumes:
      - ./api:/fleetbase/api
      - ./packages:/fleetbase/packages

After updating the override file, restart the stack:

docker compose up -d

Link Backend Packages

To develop a backend package locally, add a path repository entry in api/composer.json for each package. Composer will symlink the local directory into the vendor tree:

{
  "repositories": [
    { "type": "path", "url": "../packages/fleetops/server" },
    { "type": "path", "url": "../packages/pallet/server" },
    { "type": "path", "url": "../packages/core-api" }
  ]
}

Then run Composer inside the application container to resolve the links:

docker compose exec application composer install

After Composer installs, run the deploy script to apply any new migrations from the linked packages:

docker compose exec application bash -c "./deploy.sh"

Octane and PHP Changes

Fleetbase runs Laravel Octane, which keeps the application in memory for performance. PHP file changes are not picked up automatically. After editing any PHP file, reload the Octane worker:

docker compose exec application php artisan octane:reload

If you add new migrations, run them directly:

docker compose exec application php artisan migrate

Frontend Development

There are two paths for frontend development: running the Ember dev server inside Docker, or running it locally on your machine. Both give you hot module replacement and live reload on file changes.

Path A — Docker (Dockerfile.server-build)

Dockerfile.server-build runs ember serve inside a container instead of doing a production build. This is useful if you want to keep everything in Docker without installing Node locally.

Override the console service in docker-compose.override.yml to build from the dev Dockerfile and mount your local source:

services:
  console:
    build:
      context: ./console
      dockerfile: Dockerfile.server-build
    volumes:
      - ./console:/console
      - /console/node_modules
    ports:
      - "4200:4200"

Then rebuild and start the console container:

docker compose up -d --build console

The console will be available at http://localhost:4200 with live reload on changes inside ./console/.

Path B — Local Ember Dev Server

Stop the console container and run the Ember dev server directly on your machine:

docker compose stop console
cd console
pnpm install
pnpm start:dev

The console will be available at http://localhost:4200. This is the fastest iteration path — the dev server watches console/, packages/*/addon/, and any link:-ed addons, and live-reloads on changes.

Make sure console/environments/.env.development has API_HOST pointing at your running API container before starting:

API_HOST=http://localhost:8000

Link Frontend Packages

To develop a frontend addon locally, open console/package.json and add a link: entry pointing to the package's root directory. The link: protocol tells the package manager to use your local filesystem copy instead of the published version:

{
  "dependencies": {
    "@fleetbase/fleetops-engine": "link:../packages/fleetops",
    "@fleetbase/pallet-engine": "link:../packages/pallet"
  }
}

Each linked package needs its own pnpm install first. Before the console can resolve a link: dependency, the linked package must have its own node_modules populated. If you skip this, pnpm install and pnpm build in the console will fail with missing-module errors.

cd packages/fleetops
pnpm install

cd ../pallet
pnpm install

Repeat for every package you've linked.

Then install dependencies in the console to resolve the links. Inside the console container (Path A):

docker compose exec console pnpm install

Or locally (Path B):

cd console
pnpm install

Working on a Package

With volumes mounted and packages linked, the typical workflow for editing an extension package is:

Backend changes (PHP — packages/your-package/server/)

Edit the PHP files directly. After saving, reload Octane so the worker picks up the changes:

docker compose exec application php artisan octane:reload

If you add new migrations, run them directly:

docker compose exec application php artisan migrate

Frontend changes (Ember — packages/your-package/addon/)

The Ember dev server (either Docker or local) watches linked addons and live-reloads automatically. No additional steps needed.

Building a New Extension

To scaffold a new extension from scratch, use the Fleetbase CLI:

npm install -g @fleetbase/cli
flb scaffold

The CLI runs interactively and prompts for the extension name, description, author, PHP namespace, and repository URL. It generates a new package with the correct structure (addon/, server/, package.json, composer.json) ready to link using the steps above.

You can also pass options directly to skip the prompts:

flb scaffold --name my-extension --namespace "MyCompany\\MyExtension"

See the flb scaffold command reference for all available flags, and the Extension Development Quickstart for a full walkthrough of building and registering a new extension.

Licensing

Fleetbase is licensed under the GNU Affero General Public License v3 (AGPL-3.0). If you modify Fleetbase or build extensions that run as part of a networked service, the AGPL requires that you make your modified source code publicly accessible to users of that service.

If you intend to keep your modifications or extensions private — for example, as part of a commercial product or internal platform — you will need a commercial license. Book a call to discuss licensing options, or visit the Licensing page for further information.

Development Setup

On this page