From 8ab908d2298d80c79b3dc2813d40a68cc8441d26 Mon Sep 17 00:00:00 2001
From: Pier-Jean Malandrino <pierjean.malandrino@scub.net>
Date: Fri, 10 Apr 2026 19:26:37 +0200
Subject: [PATCH] feat(infra): add Docker Compose dev stack with OpenSearch

Closes #148
---
 .env.example           |  3 ++
 CHANGELOG.md           | 10 +++++
 CONTRIBUTING.md        | 29 ++++++++++++++
 docker-compose.dev.yml | 88 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 130 insertions(+)
 create mode 100644 docker-compose.dev.yml

diff --git a/.env.example b/.env.example
index 832eb86..0f23b23 100644
--- a/.env.example
+++ b/.env.example
@@ -36,3 +36,6 @@
 
 # Database path (inside container)
 # DB_PATH=./data/docling_studio.db
+
+# OpenSearch URL (used by docker-compose.dev.yml, auto-set to service name)
+# OPENSEARCH_URL=http://opensearch:9200
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dcdb5a7..23277a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,16 @@ All notable changes to Docling Studio will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - Unreleased
+
+### Added
+
+- Docker Compose dev stack (`docker-compose.dev.yml`) with OpenSearch, Dashboards, hot-reload backend and Vite frontend
+
+### Fixed
+
+### Changed
+
 ## [0.3.1] - 2026-04-09
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index baef553..fc91d31 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,6 +17,35 @@ Thank you for your interest in contributing to Docling Studio! This guide will h
 
 ## Development Setup
 
+### Docker Dev Stack (recommended)
+
+The fastest way to get the full stack running (backend + frontend + OpenSearch):
+
+```bash
+docker compose -f docker-compose.dev.yml up
+```
+
+This starts:
+
+| Service | URL | Notes |
+|---------|-----|-------|
+| Frontend (Vite) | http://localhost:3000 | HMR enabled |
+| Backend (FastAPI) | http://localhost:8000 | Auto-reload on file changes |
+| OpenSearch | http://localhost:9200 | Single-node, security disabled |
+| OpenSearch Dashboards | http://localhost:5601 | Index inspection UI |
+
+Source code is bind-mounted — edits on your host are reflected immediately.
+
+To use remote conversion mode instead of local:
+
+```bash
+CONVERSION_MODE=remote docker compose -f docker-compose.dev.yml up
+```
+
+### Manual Setup
+
+If you prefer running services directly on your machine:
+
 ### Backend (Python 3.12+)
 
 ```bash
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 0000000..4f7cee6
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,88 @@
+# =============================================================================
+# Docling Studio — Development stack
+#
+# Usage:
+#   docker compose -f docker-compose.dev.yml up
+#
+# Includes OpenSearch single-node + Dashboards for search/sync features.
+# Frontend runs Vite dev server with HMR, backend runs with --reload.
+# =============================================================================
+
+services:
+  # --- OpenSearch (single-node, security disabled for local dev) ---
+  opensearch:
+    image: opensearchproject/opensearch:2
+    environment:
+      discovery.type: single-node
+      DISABLE_SECURITY_PLUGIN: "true"
+      OPENSEARCH_JAVA_OPTS: "-Xms512m -Xmx512m"
+    ports:
+      - "9200:9200"
+    volumes:
+      - opensearch_data:/usr/share/opensearch/data
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:9200/_cluster/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  # --- OpenSearch Dashboards (index inspection UI) ---
+  opensearch-dashboards:
+    image: opensearchproject/opensearch-dashboards:2
+    environment:
+      OPENSEARCH_HOSTS: '["http://opensearch:9200"]'
+      DISABLE_SECURITY_DASHBOARDS_PLUGIN: "true"
+    ports:
+      - "5601:5601"
+    depends_on:
+      opensearch:
+        condition: service_healthy
+
+  # --- Backend (FastAPI with hot-reload) ---
+  document-parser:
+    build:
+      context: ./document-parser
+      target: ${CONVERSION_MODE:-local}
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./document-parser:/app
+      - uploads_data:/app/uploads
+      - db_data:/app/data
+    environment:
+      CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:3000,http://localhost:5173}
+      DOCLING_SERVE_URL: ${DOCLING_SERVE_URL:-}
+      DOCLING_SERVE_API_KEY: ${DOCLING_SERVE_API_KEY:-}
+      RATE_LIMIT_RPM: ${RATE_LIMIT_RPM:-100}
+      MAX_FILE_SIZE_MB: ${MAX_FILE_SIZE_MB:-50}
+      BATCH_PAGE_SIZE: ${BATCH_PAGE_SIZE:-0}
+      OPENSEARCH_URL: http://opensearch:9200
+    command: ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+    depends_on:
+      opensearch:
+        condition: service_healthy
+    deploy:
+      resources:
+        limits:
+          memory: 4g
+
+  # --- Frontend (Vite dev server with HMR) ---
+  frontend:
+    image: node:20-alpine
+    working_dir: /app
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./frontend:/app
+      - frontend_node_modules:/app/node_modules
+    environment:
+      VITE_APP_VERSION: dev
+    command: ["sh", "-c", "npm install && npm run dev -- --host"]
+    depends_on:
+      - document-parser
+
+volumes:
+  opensearch_data:
+  uploads_data:
+  db_data:
+  frontend_node_modules: