Run with Node.js and the local demo

Running Frontdoor from source is the way to develop on it or to explore it on your own machine. For a real deployment, use Docker.

Requirements

• Node.js 24 or newer.
• A checkout of the Frontdoor repository.
• A Microsoft Entra app registration, or Dev Login (see below).

Start in development mode

# 1. Install dependencies
npm install

# 2. Configure the environment
cp .env.example.node .env
# Edit .env with your Microsoft Entra credentials, or use Dev Login

# 3. Start Vite and Express in parallel
npm run dev

• Frontend: http://localhost:5173
• API: http://localhost:3001

In development, Vite serves the frontend on port 5173 and forwards API calls to Express on port 3001. The backend restarts on its own when files in server/ or shared/ change.

The Node example file stores the database in ./frontdoor.db and the caches under ./data/. See Configuration reference for every variable.

Try it without Microsoft Entra (Dev Login)

To run Frontdoor without an Entra app registration, set this in .env (it is already on in .env.example.node):

DEV_LOGIN=true

When DEV_LOGIN=true and NODE_ENV is not production:

• Microsoft Entra credentials are not required: the server starts without them.
• A JWT_SECRET fallback is generated automatically if you do not set one.
• The sign-in page shows a Dev Login panel where you pick a role (owner, admin, admin_readonly or user) and enter immediately.
• A local dev user is created in the database on first use.

Dev Login is always off in production (NODE_ENV=production), whatever the value of DEV_LOGIN.

Local demo with Docker

To try Frontdoor in a container without installing Node.js or configuring Entra, use the demo profile:

docker compose -f docker-compose.demo.yml up --build

Open http://localhost:3001 and use the Dev Login panel. The demo needs no .env file, turns off Entra group sync, uses its own data volume and publishes the port on 127.0.0.1 only.

Dev Login lets anyone choose any role and signs tokens with a public fallback secret. Never expose the demo to a network or put it behind a reverse proxy. Remove it with:

docker compose -f docker-compose.demo.yml down -v

Demo apps

A new, empty database is seeded with example apps. You can restore them later from the admin panel or with:

npm run db:seed

Run the checks

Continuous integration runs these commands on every pull request. Run them before you open one:

npm run lint         # ESLint (no errors allowed)
npm test             # unit and HTTP tests, each test process gets its own temporary database
npm run check:i18n   # English and Italian dictionaries stay aligned
npm run build        # production frontend build

CI also builds the Docker image and smoke-tests it (/api/health and the app shell).