chore (AI-Assistant): add embeddings to docker-compose.dev.yml; improve installation docs (baserow#4563)

* chore (AI-Assistant): add embeddings to docker-compose.dev.yml; improve installation docs

* Fix flaky test

* Address feedback

* Fix just dev down to stop all services

Author: silvestrid

backend/Dockerfile

@@ -182,6 +182,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     apt-get update && \
     apt-get upgrade -y && \
     apt-get install -y --no-install-recommends \
+    gettext \
     xmlsec1
 
 ENV DOCKER_USER=baserow_docker_user \
@@ -236,6 +237,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     python3.11-dev \
     ca-certificates \
     postgresql-client-15 \
+    gettext \
     xmlsec1 \
     curl \
     graphviz \
@@ -275,13 +277,14 @@ USER $UID:$GID
 WORKDIR /baserow/backend
 
 # Install all dependencies
+COPY --chown=$UID:$GID LICENSE /baserow/LICENSE
+COPY --chown=$UID:$GID premium/LICENSE /baserow/premium/LICENSE
+COPY --chown=$UID:$GID enterprise/LICENSE /baserow/enterprise/LICENSE
+
 RUN --mount=type=cache,target=$UV_CACHE_DIR,sharing=locked,uid=$UID,gid=$GID \
-    --mount=type=bind,source=LICENSE,target=/baserow/LICENSE \
     --mount=type=bind,source=backend/uv.lock,target=/baserow/backend/uv.lock \
     --mount=type=bind,source=backend/pyproject.toml,target=/baserow/backend/pyproject.toml \
-    --mount=type=bind,source=premium/LICENSE,target=/baserow/premium/LICENSE \
     --mount=type=bind,source=premium/backend/pyproject.toml,target=/baserow/premium/backend/pyproject.toml \
-    --mount=type=bind,source=enterprise/LICENSE,target=/baserow/enterprise/LICENSE \
     --mount=type=bind,source=enterprise/backend/pyproject.toml,target=/baserow/enterprise/backend/pyproject.toml \
     uv sync --frozen --no-install-workspace --no-install-project
 

backend/tests/baserow/contrib/database/rows/test_row_history.py

@@ -998,7 +998,7 @@ def test_create_rows_action_row_history_with_undo_redo(
 
     assert RowHistory.objects.count() == 1
 
-    history_entries = RowHistory.objects.order_by("row_id").values(
+    history_entries = RowHistory.objects.order_by("row_id", "action_timestamp").values(
         "user_id",
         "user_name",
         "table_id",
@@ -1040,7 +1040,7 @@ def test_create_rows_action_row_history_with_undo_redo(
         )
         assert undone
 
-    history_entries = RowHistory.objects.order_by("row_id").values(
+    history_entries = RowHistory.objects.order_by("row_id", "action_timestamp").values(
         "user_id",
         "user_name",
         "table_id",
@@ -1094,7 +1094,7 @@ def test_create_rows_action_row_history_with_undo_redo(
         )
         assert redone
 
-    history_entries = RowHistory.objects.order_by("row_id").values(
+    history_entries = RowHistory.objects.order_by("row_id", "action_timestamp").values(
         "user_id",
         "user_name",
         "table_id",

docker-compose.dev.yml

@@ -42,6 +42,7 @@ services:
       - "${HOST_PUBLISH_IP:-127.0.0.1}:8000:8000"
       - "${HOST_PUBLISH_IP:-127.0.0.1}:${BASEROW_BACKEND_DEBUGGER_PORT:-5678}:${BASEROW_BACKEND_DEBUGGER_PORT:-5678}"
     volumes:
+      - ./docs:/baserow/docs
       - ./backend:/baserow/backend
       - ./premium/backend/:/baserow/premium/backend
       - ./enterprise/backend/:/baserow/enterprise/backend
@@ -92,6 +93,7 @@ services:
       - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
       - BASEROW_DANGEROUS_SILKY_ANALYZE_QUERIES
     volumes:
+      - ./docs:/baserow/docs
       - ./backend:/baserow/backend
       - ./premium/backend/:/baserow/premium/backend
       - ./enterprise/backend/:/baserow/enterprise/backend
@@ -110,6 +112,7 @@ services:
       - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
       - BASEROW_DANGEROUS_SILKY_ANALYZE_QUERIES
     volumes:
+      - ./docs:/baserow/docs
       - ./backend:/baserow/backend
       - ./premium/backend/:/baserow/premium/backend
       - ./enterprise/backend/:/baserow/enterprise/backend
@@ -218,6 +221,28 @@ services:
       local:
     ports:
       - "4318:4318"
+  
+  embeddings:
+    profiles: ["ai"]
+    build:
+      context: ./embeddings
+      dockerfile: Dockerfile
+    ports:
+      - "${HOST_PUBLISH_IP:-127.0.0.1}:7999:80"
+    networks:
+      local:
+    restart: unless-stopped
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import requests; requests.get('http://localhost/health').raise_for_status()",
+        ]
+      interval: 1m30s
+      timeout: 10s
+      retries: 3
 
 volumes:
   pgdatadev:

docker-compose.yml

@@ -320,6 +320,7 @@ services:
       BASEROW_AUTOMATION_WORKFLOW_RATE_LIMIT_CACHE_EXPIRY_SECONDS:
       BASEROW_AUTOMATION_WORKFLOW_MAX_CONSECUTIVE_ERRORS:
       BASEROW_INTEGRATIONS_PERIODIC_MINUTE_MIN:
+      BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL:
     depends_on:
       - backend
     networks:
@@ -340,7 +341,8 @@ services:
           "/baserow/backend/docker/docker-entrypoint.sh celery-worker-healthcheck",
         ]
     depends_on:
-      - backend
+      - db
+      - redis
     volumes:
       - media:/baserow/media
     networks:
@@ -361,7 +363,8 @@ services:
           "/baserow/backend/docker/docker-entrypoint.sh celery-exportworker-healthcheck",
         ]
     depends_on:
-      - backend
+      - db
+      - redis
     volumes:
       - media:/baserow/media
     networks:
@@ -385,7 +388,8 @@ services:
     # See https://github.com/sibson/redbeat/issues/129#issuecomment-1057478237
     stop_signal: SIGQUIT
     depends_on:
-      - backend
+      - db
+      - redis
     volumes:
       - media:/baserow/media
     networks:

docs/development/embeddings-server.md

@@ -1,33 +1,78 @@
 # Setup embeddings server in dev environment
 
 If you would like to use the AI-assistant in combination with the search documentation
-tool, then you must add the embeddings server. This 
-
-## Docker compose
-
-Add the following to your `docker-compose.dev.yml` and then (re)start your dev server.
-The `BASEROW_EMBEDDINGS_API_URL=http://embeddings:80` variable is already configured by
-default for the backend container, so it should then work out of the box.
-
-```yaml
-  embeddings:
-    build:
-      context: ./embeddings
-      dockerfile: Dockerfile
-    ports:
-      - "${HOST_PUBLISH_IP:-127.0.0.1}:7999:80"
-    networks:
-      local:
-    restart: unless-stopped
-    healthcheck:
-      test:
-        [
-          "CMD",
-          "python",
-          "-c",
-          "import requests; requests.get('http://localhost/health').raise_for_status()",
-        ]
-      interval: 1m30s
-      timeout: 10s
-      retries: 3
+tool, then you must start the embeddings server.
+
+## Getting Started
+
+You can build and start the embedding service by adding `ai` to the `COMPOSE_PROFILES` environment variable:
+
+```bash
+COMPOSE_PROFILES=ai
 ```
+
+If you need both `ai` and `optional` profiles, combine them with a comma:
+
+```bash
+COMPOSE_PROFILES=ai,optional
+```
+
+After starting the services, make sure the correct environment variables are set. In particular, `BASEROW_EMBEDDINGS_API_URL` must be set correctly for the embedding server to work. See [ai-assistant.md](../installation/ai-assistant.md) for the full list of required variables.
+
+Then, run the management command to schedule the initial import:
+
+From the host:
+
+```bash
+just dcd run --rm backend manage sync_knowledge_base
+```
+
+From inside the container:
+```bash
+./baserow sync_knowledge_base
+```
+
+This will schedule a task to import `website_export.csv` containing all the docs and generate the embeddings using the local service. Once completed, asking the assistant to search for docs should show "Exploring the knowledge base..." in the UI when the assistant uses the `search_docs` tool, and the answers should show sources from the docs.
+
+
+## Troubleshooting
+
+### Kuma is not available in the sidebar
+
+Make sure `BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL` is set correctly both in the backend and in the frontend. See [ai-assistant.md](../installation/ai-assistant.md) for more information.
+
+### Kuma is visible but it doesn't search the docs
+
+Run the management command to synchronize the docs in the knowledge base:
+
+From the host:
+```bash
+just dcd run --rm backend manage sync_knowledge_base
+```
+
+From inside the container:
+```bash
+./baserow sync_knowledge_base
+```
+
+
+### The embedding service is not reachable
+
+Verify the server is up and running by executing one of the following commands:
+
+From the host:
+```bash
+curl -X POST "http://localhost:7999/embed" \
+  -H "Content-Type: application/json" \
+  -d '{"texts": "test"}'
+```
+
+From inside the container:
+
+```bash
+curl -X POST "$BASEROW_EMBEDDINGS_API_URL/embed" \
+  -H "Content-Type: application/json" \
+  -d '{"texts": "test"}'
+```
+
+This command should return a vector of more than 500 numbers. If it doesn't, check that the embeddings container is running and healthy.

docs/installation/ai-assistant.md

@@ -17,6 +17,8 @@ server.
 
 Set the model you want, restart Baserow, and let migrations run.
 
+**Important:** When running Baserow with Docker Compose or multiple services, `BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL` must be set in **all services** (both backend and frontend) for the assistant to work properly.
+
 ```dotenv
 # Required
 BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL=openai/gpt-4o
@@ -77,9 +79,11 @@ OpenAI-compatible client accordingly.
 
 ## 4) Knowledge-base lookup
 
-If your deployment method doesn’t auto-provision embeddings, run the Baserow embeddings
+If your deployment method doesn't auto-provision embeddings, run the Baserow embeddings
 service and point Baserow at it.
 
+**For developers using Docker Compose:** See [embeddings-server.md](../development/embeddings-server.md) for setup instructions.
+
 ### Run the embeddings container
 
 ```bash
@@ -95,3 +99,27 @@ BASEROW_EMBEDDINGS_API_URL=http://your-embedder-service
 ```
 
 After restart and migrations, knowledge-base lookup will be available.
+
+## 5) Troubleshooting
+
+### The assistant doesn't appear or doesn't work
+
+If the assistant is not visible in the sidebar or doesn't work, verify that:
+
+1. `BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL` is set correctly in **both** the backend and frontend services
+2. The required API key for your chosen provider is set (e.g., `OPENAI_API_KEY`, `GROQ_API_KEY`, etc.)
+
+### Verifying environment variables in development
+
+To check if the variables are set correctly in development, from the host run:
+
+```bash
+# Check backend
+just dcd run --rm backend bash -c env | grep LLM_MODEL
+just dcd run --rm backend bash -c env | grep API_KEY
+
+# Check frontend
+just dcd run --rm web-frontend bash -c env | grep LLM_MODEL
+```
+
+Both commands must return the same value for `BASEROW_ENTERPRISE_ASSISTANT_LLM_MODEL`. If either is missing or they differ, update your environment configuration and restart the services.

justfile

@@ -242,7 +242,7 @@ _dev-start:
 
     # Start docker services (redis, db, mailhog, otel-collector)
     echo "==> Starting Docker services (redis, db, mailhog, otel-collector)..."
-    just dc-dev up -d redis db mailhog otel-collector caddy
+    just dc-dev up -d --scale backend=0 --scale web-frontend=0 --scale celery=0 --scale celery-beat-worker=0 --scale celery-export-worker=0
 
     # Wait for services to be ready
     echo "==> Waiting for PostgreSQL to be ready..."
@@ -369,7 +369,7 @@ _dev-stop:
 
     # Stop docker services
     echo "Stopping Docker services..."
-    just dc-dev stop redis db mailhog otel-collector
+    just dc-dev down
 
     echo ""
     echo "Development environment stopped."