Deploy with Docker Compose

This tutorial gets a working Faxart stack running on one host with Docker Compose. By the end you will have the web app, the broker API, the database, and the media layer up, and you will know what each piece does.

This is a learning exercise on a single machine. For a production cutover, read the Configuration reference and the Architecture after you finish here.

Before you start

You need:

• Docker with the Compose plugin (docker compose, not docker-compose)
• A clone of the repository
• A few minutes; the first build pulls images and compiles the web UI

1. Create your environment file

Faxart reads everything from a .env file. Copy the example and open it:

cp .env.example .env

The defaults are wired for local development against *.l.supported.systems hostnames. You do not need real Active Directory, a GPU, or a SIP carrier to see the app come up. Those features stay inert until you provide their credentials, which is the whole posture of the system: every integration is off by default and lights up when configured.

2. Start the core stack

docker compose up -d --build

Then bring up the web UI in dev mode (hot reload):

COMPOSE_PROFILES=dev docker compose up -d --build faxart-web-dev

Check the logs, which is always worth doing right after a start:

docker compose logs -f --tail=50

3. Open the app

Visit the app hostname from your .env (the dev default is app-faxart.l.supported.systems). You should see the fax dashboard: an inbox, a sent view, and the settings surfaces.

What is actually running

A quick tour of the services you just started:

Service	Role
faxart-api	The broker. All routing, AD access, email, and filing logic.
faxart-postgres	The database, with a PHI-read audit floor.
faxart-freeswitch	Pure media: send and receive over SIP. No decisions.
faxart-worker-*	Background queues: send, classify, file, print, deliver.
faxart-web-dev	The web UI in hot-reload mode.

The layering principle matters: the media layer never makes routing decisions. See Architecture for the full picture.

Next steps

• Receive your first fax
• Send a fax from email
• Configuration reference to turn on real integrations