Docs · Getting started

Run Mosaic

The hosted service, a download you unzip, or Docker — and what each one needs.

There are three ways to run Mosaic. They are the same product; they differ in who operates it and where your data sits.

#Hosted

Go to cloud.getdatamosaic.com and create an account. You get a workspace of your own and there is nothing to install.

Choose this if you want to try Mosaic today, or if your data is reachable from the internet. Your licence, plan and the self-hosting download all live under Tenancy → Plan in the account menu once you are in.

#On your own machine

Choose this when the systems you need to read are inside your network — which, for most retail estates, they are. Mosaic only needs outbound access; nothing has to be opened to it from outside.

The download is one package for Windows, macOS and Linux. There is no installer: it is a folder you unzip and two commands.

npm install --omit=dev --ignore-scripts
npm start

Mosaic then listens on 127.0.0.1:4317. Open that in a browser and you are at first sign-in.

The package deliberately ships without node_modules, because the Oracle and SQLite drivers are compiled per platform and have to be fetched on the machine that will run them. That first npm install is what does it, and it is why the folder grows to roughly 400 MB.

#What you need

#Keeping it running

To run Mosaic as a background service rather than a terminal window:

node scripts/service.mjs install
node scripts/service.mjs status

#Docker

From a clone of the repository:

cd infrastructure/docker
cp .env.example .env
docker compose up -d

Mosaic answers on http://localhost:4317. Data persists in a named volume, mosaic-data, mounted at /var/lib/mosaic.

The compose file ships no Redis and no Postgres on purpose — the job queue is a table, so a single-container install has nothing else to operate.

#Settings worth knowing

Nothing has to be set to start a local install. Every one of these has a working default.

#Where your data lives

A local install keeps everything in one directory — the one MOSAIC_DATA_DIR names. Inside it are mosaic.db, the SQLite database, and secret.key, which encrypts stored credentials. There is no shared state anywhere else on the machine, which is what makes the install a folder you can move or delete.

Back up that directory and you have backed up Mosaic.

#Backing up

Mosaic takes a copy of its database every day on its own, and owners can take one, download it or restore it under Storage → Backups (see Storage and audit). Those copies sit on the same disk, so also copy them somewhere else. If you back up the folder yourself:

• Both files, together. mosaic.db without secret.key restores every check, but every stored database password and API key in it is unreadable, and there is no way to recover them.
• Not a plain copy while Mosaic is running. The database is written continuously, and a file copied mid-write can be unusable. Either stop the service for the copy, or use SQLite's own online backup, which is safe while Mosaic runs:

sqlite3 mosaic.db ".backup 'mosaic-backup.db'"

• On Postgres, back up the database with your usual tooling (pg_dump, or your provider's backups), and keep MOSAIC_MASTER_KEY with it, in a separate place.
• Try a restore now and then: point a spare install's MOSAIC_DATA_DIR at a copy and sign in. A backup nobody has restored is a hope, not a backup.

For a deployment that runs more than one instance, point MOSAIC_DB_DRIVER at postgres and give it a DATABASE_URL. SQLite is a file, so it is single-host by construction.

#Next

First sign-in — claiming the installation and finding your way around.