DeepFellow Server

To install and configure DeepFellow Server, start with:

deepfellow server install

You will proceed to configure built-in components:

• Docker network
• no-sql database (for example MongoDB)
• connection with DeepFellow Infra
• vector database and embedding model
• telemetry
• Nightshift background worker and RabbitMQ

Docker Network

The installer first asks which Docker network DeepFellow Server will join. Use the same network name you chose during Infra installation so Server and Infra can reach each other:

$ deepfellow server install
💡      Installing DeepFellow Server.
❓      Provide a docker network name (deepfellow-infra-net):

MongoDB

💡      DeepFellow Server requires a MongoDB to be installed.
❓      Install a local MongoDB for DeepFellow Server? [y/n] (y):
💡      A default MongoDB setup is created.

If you choose n instead, you will be asked about credentials and database name first:

❓      Provide username for MongoDB: deepfellow-usr
❓      Provide password for MongoDB:
❓      Provide database name for MongoDB: deepfellow

Then you will be asked to provide the Mongo URL (not mongo connection string!):

❓      Provide host:port for MongoDB e.g. 192.168.1.5:27017: mongo:27017

If you use a service name like mongo, Docker will resolve it to the MongoDB container. Be careful: localhost will not work as it refers to the container's own loopback interface.

Connection with Infra

Next, the installator will proceed to configure connection with Infra:

💡      DeepFellow Server is communicating with DeepFellow Infra.
❓      Provide DeepFellow Infra URL (http://infra:8086):
❓      Provide DeepFellow Infra API KEY:

Docker resolves a name like infra internally to a Compose service name. Be careful: localhost will not work as it refers to the container's own loopback interface.

Vector Database

Next, the installer configures the vector database and embedding model:

💡      DeepFellow Server might use a vector DB. If not provided some features will not work.
❓      Do you want to use a vector database with DeepFellow? [y/n] (y):
❓      Choose embedding type dense
❓      Choose the type of the vector database qdrant
❓      Install a local vector database for DeepFellow Server? [y/n] (y):
💡      DeepFellow will manage a Qdrant instance.
⚠️      Qdrant keeps its index in RAM and can stop responding once the data grows past ~5 GB. It is not suited for large data volumes - choose Milvus (--vectordb-type milvus) for those.
❓      Provide the model for embedding (mxbai-embed-large):
❓      Provide the embedding size (1024):

The available embedding types are dense and sparse. The available vector database backends are qdrant and milvus.

Answer n to "Install a local vector database?" if you want to connect to an existing instance. You will be asked for its URL:

❓      Install a local vector database for DeepFellow Server? [y/n] (y): n
❓      Provide Qdrant instance URL (http://qdrant:6333):

If you use a service name like qdrant, Docker will resolve it to the Qdrant service. Be careful: localhost will not work as it refers to the container's own loopback interface.

Telemetry

After that, OpenTelemetry configuration will start:

💡      DeepFellow Server might use an Open Telemetry.
❓      Do you have an Open Telemetry server ready? [y/n] (n): n
❓      Do you want to run Open Telemetry from this machine? [y/n] (n): y
💡      Let's configure Open Telemetry
❓      Do you want to export to Elasticsearch? [y/n] (n):

If you answer n to "Do you want to export to Elasticsearch?" (the default), DeepFellow generates a debug-only OTel collector configuration. No Elasticsearch instance is required.

Inspect telemetry via the container log once Server is running:

docker logs -f otel-collector-container

This mode suits local development, workshops, and demo environments.

To export to Elasticsearch, answer y. You will be prompted for your credentials:

❓      Do you want to export to Elasticsearch? [y/n] (n): y
❓      Provide your ElasticSearch endpoint: https://myelastic.com:9200
❓      Provide traces index: my-index
❓      Provide username: elastic_user
❓      Provide password:

In both cases, installation ends with:

⚠️       Open Telemetry configuration stored in file:
        /home/johndoe/.deepfellow/server/otel-collector-config.yaml
        Please review its content before starting the DeepFellow Server.

To use an existing OTel server instead of running one locally, answer y to "Do you have an Open Telemetry server ready?" You will be asked to provide the URL:

❓      Provide OTL url (http://otel-collector:4317):

If you use a service name like otel-collector, Docker will resolve it to the otel-collector service in compose. Be careful: localhost will not work as it refers to the container's own loopback interface.

By default, the server exports only traces to the collector. To also forward the server's Python log records, set DF_OTEL_LOGGING_ENABLED to true:

deepfellow server env set DF_OTEL_LOGGING_ENABLED true

The server ships logs to the endpoint defined by DF_OTEL_EXPORTER_OTLP_ENDPOINT (default http://localhost:4317). This endpoint must accept the OTLP log signal over insecure gRPC. The server exports logs under the service name llm-audit, which lets you correlate them with existing traces in your observability backend. Tracing and log export are independent. Enable each one with its own variable, DF_OTEL_TRACING_ENABLED and DF_OTEL_LOGGING_ENABLED.

Nightshift and RabbitMQ

The installer always sets up the Nightshift background worker and the RabbitMQ queue it reads from. Nightshift runs Metadata Expansion, Document Summarization, and Knowledge Graph jobs, with retries that survive a server restart. The worker runs in its own nightshift container, from the same image as the server.

First, choose the worker's operating mode:

❓      Choose Nightshift worker operating mode always

• always: the worker runs continuously. This is the default.
• shift: the worker runs only between a start hour and a stop hour. Tasks queued outside those hours wait in RabbitMQ until the next start.

shift mode requires a Linux host booted with systemd and a reachable systemd user session. On other hosts, the installer offers only always. If you run the installer from a shell without your user session, for example after su or sudo -u, log in as that user directly, for example over SSH or a console. If you choose shift, the installer asks for both hours, in HH:MM 24-hour format and the host timezone:

❓      Choose Nightshift worker operating mode shift
⚠️      In shift mode, tasks queued outside the worker's active hours wait in RabbitMQ until its next scheduled start - they are not processed by the server in the meantime.
❓      Provide the hour Nightshift worker should start (HH:MM, host timezone) (22:00):
❓      Provide the hour Nightshift worker should stop (HH:MM, host timezone) (06:00):

In shift mode, the installer creates two user-level systemd timers. Both run the same command, which starts or stops the worker to match the schedule. To keep the timers running without a login session, the installer also runs loginctl enable-linger for your user, and skips this step when lingering is already enabled. If the step needs root on your host, the installer asks to retry it with sudo, and sudo asks for your password. In non-interactive mode, the installer runs sudo -n instead, so the step fails if sudo needs a password.

The timer names are the same for every install, so only one install per user can use shift mode. See Nightshift Operating Modes.

In shift mode, if you start the server outside the scheduled hours, the worker stays stopped until the next start hour. See Start.

Next, choose where RabbitMQ runs:

❓      Install a local RabbitMQ for DeepFellow Server? [y/n] (y):
💡      A default RabbitMQ setup is created.

A local RabbitMQ runs in the rabbitmq container, with a generated username and password. The container has the fixed hostname rabbitmq and a 4-hour consumer timeout, so a long job is not redelivered while it runs. A reinstall keeps the existing credentials.

To connect to an existing RabbitMQ instance instead, answer n. You will be asked for its address, username, and password:

❓      Install a local RabbitMQ for DeepFellow Server? [y/n] (y): n
❓      Provide host:port for RabbitMQ e.g. 192.168.1.5:5672: rabbitmq.example.com:5672
❓      Provide RabbitMQ username:
❓      Provide RabbitMQ password:

The username and password cannot contain whitespace or any of the characters @ / : ? # [ ] %, because they are part of the connection URI.

If you run the installer again, the prompts default to the values in the rabbitmq section of config.json, when that section exists, instead of the possibly outdated DF_RABBITMQ_* values in .env. After the first start, change the broker connection with deepfellow server config set, not with deepfellow server env set. See deepfellow server env.

In non-interactive mode, pass the credentials with flags. Passing any --rabbitmq-url other than the default rabbitmq:5672 also selects an existing instance.

After configuring the components, successful installation will be confirmed:

💡      Generated /home/johndoe/.deepfellow/server/.env.
💡      A default Qdrant setup is created.
💡      Updated /home/johndoe/.deepfellow/config.
💡      Saved Docker Compose configuration to /home/johndoe/.deepfellow/server/compose.yaml
✅      DeepFellow Server Installed.
        Call `deepfellow server start`.

Check the worker's logs. Run docker compose logs nightshift in the server installation directory.

Check the RabbitMQ settings with deepfellow server config get. The server and the worker read the broker address from the rabbitmq section of config.json, not from .env.

Correct the settings with deepfellow server config set. Pass only the fields you change:

deepfellow server config set 'rabbitmq={"host": "RABBITMQ_HOST", "port": 5672, "username": "RABBITMQ_USER", "password": "RABBITMQ_PASSWORD"}'

The keys are the same as in the rabbitmq section of the deepfellow server config get output. For the RabbitMQ that the installer sets up, the host is rabbitmq. The server accepts the change only if it reaches the new broker. The worker reloads on its own, without a restart. See RabbitMQ Connection.