Docker Setup

Docker Compose is the recommended way to run Fluent OSS. The bundled docker-compose.yml handles the build, volume persistence, and port mapping.

Default Start

docker compose --env-file .env.oss.example up --build

This starts Fluent OSS with:

• Port 8788 exposed
• A named volume for persistent data
• Default configuration from .env.oss.example

Custom Configuration

Copy the example environment file and modify it:

cp .env.oss.example .env.oss

Edit .env.oss to change ports, host binding, or the data root. Then start with your custom config:

docker compose --env-file .env.oss up --build

Token Management

Print the bearer token from inside the running container:

docker compose exec fluent-oss npm run oss:token:print

The token is persisted in the named volume, so it survives container restarts.

Persistent Volume

The named Docker volume stores:

• SQLite database -- all relational state (profiles, plans, recipes, items, etc.)
• Artifact storage -- uploaded photos and files
• Token state -- the bearer token for /mcp authentication

Data persists across docker compose down and docker compose up cycles as long as you do not explicitly remove the volume.

To remove the volume and start fresh:

docker compose down -v

WARNING

Removing the volume deletes all Fluent data. Export a snapshot first if you want to keep your data.

Port Mapping

The default port is 8788. To change it, set FLUENT_OSS_PORT in your .env.oss file or map a different host port in your compose override.

Rebuilding

After pulling new code from the repo:

git pull
docker compose --env-file .env.oss up --build

The --build flag ensures the container image is rebuilt with the latest code.

Health Checks

Verify the container is running:

curl http://127.0.0.1:8788/health
curl http://127.0.0.1:8788/codex-probe

Next Steps

• Configuration -- token management and environment variables
• Backup & Restore -- snapshot your data
• Postgres + S3 -- experimental backend