Flotilla

Flotilla is the main point of access for operators to interact with multiple robots in multiple facilities. The application consists of a frontend in React, a backend in ASP.NET, and a Mosquitto MQTT broker.

Prerequisites

Tool	Version	Needed for
Docker and Docker Compose	latest	Full stack (make compose) + Tilt broker/Postgres
Tilt	latest	Running the stack locally (make run)
uv	latest	Preflight + Key Vault scripts
Azure CLI	latest	Fetching local secrets (az login)
.NET SDK	10.x	Running the backend
Node.js	24.x	Running the frontend
pnpm	latest	Frontend package management
make	any	The shorthand commands below

Installing make on MacOS

brew install make

Installing make on Windows

choco install make

Quick start

For development, fork the repository first. Then clone it:

git clone https://github.com/equinor/flotilla
cd flotilla

Log in to Azure so the stack can fetch its local secrets from Key Vault, then start everything with Tilt:

az login
make run          # runs preflight, then `tilt up`

make run brings up a self-contained local stack — MQTT broker and PostgreSQL in Docker, and the backend and frontend as hot-reloading host processes:

Service	URL
Frontend	http://localhost:3001
Backend Swagger	http://localhost:8000/swagger
Tilt UI	http://localhost:10350

Press Ctrl+C to stop it; make run automatically runs make down before exiting. Press Ctrl+C again to cancel cleanup. You can still run make down directly, or make clean to also wipe the database volume.

Authentication uses Microsoft Entra ID, so az login is required; there is no offline auth option yet. To drive a mission, run an ISAR robot on the host pointed at this stack's broker (localhost:1883) and backend (localhost:8000).

The example database includes one offline Placebot at KAA / K-Lab with ISAR ID 00000000-0000-0000-0000-000000000000. A standalone ISAR instance using that ID and installation KAA connects to this robot without manual inspection-area assignment. For older ISAR versions defaulting to HUA, set ISAR_PLANT_SHORT_NAME=KAA. Other IDs still self-register and need an inspection area assigned. Robotics' Tilt instances use distinct IDs and automate that assignment. This seed applies to an empty database; it does not add the robot to an existing one.

The Tilt definition lives in tilt/ and is reused by the robotics local-orchestration stack, which imports flotilla_stack() from tilt/flotilla.tilt and runs it alongside SARA, ISAR and the rest of the platform.

To run a single component instead, see the frontend, backend, and broker guides.

Configuration

Each component reads its configuration from a .env file. The matching .env.example file is the source of truth for the available variables.

Component	File	Template	Notes
Frontend	frontend/.env	frontend/.env.example	Variables must be prefixed with VITE_ to reach the application.
Backend	backend/api/.env	backend/api/.env.example	Set Local__DevUserId to your own user id for local development.
Broker	broker/.env	broker/.env.example	TLS_SERVER_KEY is a secret and is found in our key vault.

Note: these .env files configure the Docker Compose targets (make broker, make keycloak, …) and running a component directly. The Tilt path (make run) does not use them — it sets the backend and frontend environment itself and fetches secrets from Key Vault. The backend container started by compose does not load backend/api/.env either — docker-compose.yml reads AZURE_CLIENT_SECRET from a .env file in the repository root, which setup.sh does not create. To run the full stack against Azure AD you currently have to add AZURE_CLIENT_SECRET=... to a root .env yourself.

Other make commands

make run is the recommended way to develop locally. The remaining targets in the root Makefile drive the production-shaped container images through Docker Compose (independent of the Tilt path, still configured via ./setup.sh and the per-component .env files):

make compose         # run the full stack in Docker
make broker          # run only the MQTT broker
make broker-aspire   # run the broker, OpenTelemetry collector, and Aspire dashboard
make keycloak        # run a local OpenID Connect issuer instead of Entra ID

Per-component commands live in the backend Makefile and frontend Makefile.

make keycloak starts the same realm the integration tests use, so the backend can be run without Entra ID. It needs a little configuration in backend/api/.env — see Running against a local Keycloak.

Deployments

We currently have 3 environments (Development, Staging, and Production) deployed to AKS under robotics.equinor.com.

Environment	Deployment	Status
Development	Frontend Backend
Staging	Frontend Backend
Production	Frontend Backend

Contributions

Equinor welcomes all kinds of contributions, including code, bug reports, issues, feature requests, and documentation. Please initiate your contribution by creating an issue or by forking the project and making a pull request. Commit messages shall be written according to this guide.