From ff07d06c2e5bc729dfb229db45b3a10478faa0b6 Mon Sep 17 00:00:00 2001
From: Geanderson <geandersonlemonte.gl@gmail.com>
Date: Tue, 13 Jan 2026 10:06:33 -0300
Subject: [PATCH 1/5] feat: add Docker examples and setup documentation

---
 README.md                             |  16 ++
 rest/docker/README.md                 | 319 ++++++++++++++++++++++++++
 rest/docker/docker-compose.nodejs.yml |  37 +++
 rest/docker/docker-compose.python.yml |  37 +++
 rest/docker/docker-compose.yml        |  64 ++++++
 rest/docker/nodejs/.dockerignore      |   8 +
 rest/docker/nodejs/Dockerfile         |  37 +++
 rest/docker/python/.dockerignore      |  18 ++
 rest/docker/python/Dockerfile         |  47 ++++
 rest/nodejs/README.md                 |  20 ++
 rest/python/server/README.md          |  21 ++
 11 files changed, 624 insertions(+)
 create mode 100644 rest/docker/README.md
 create mode 100644 rest/docker/docker-compose.nodejs.yml
 create mode 100644 rest/docker/docker-compose.python.yml
 create mode 100644 rest/docker/docker-compose.yml
 create mode 100644 rest/docker/nodejs/.dockerignore
 create mode 100644 rest/docker/nodejs/Dockerfile
 create mode 100644 rest/docker/python/.dockerignore
 create mode 100644 rest/docker/python/Dockerfile

diff --git a/README.md b/README.md
index 61eaa64..fd25bf0 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,23 @@ Zod.
     *   Demonstrates implementation of UCP specifications for shopping,
         checkout, and order management using a Node.js stack.
 
+### Docker
+
+Docker configurations for running UCP servers. Includes separate compose files
+for each server and a combined setup.
+
+*   **Docker Setup**: [Documentation](rest/docker/README.md)
+    *   Located in `rest/docker/`.
+    *   Includes `docker-compose.yml` to orchestrate both servers together.
+    *   Includes `docker-compose.nodejs.yml` for Node.js server only.
+    *   Includes `docker-compose.python.yml` for Python server only.
+    *   Quick start option that doesn't require local Node.js or Python
+        installation.
+
 ## Getting Started
 
 Please refer to the specific README files linked above for detailed instructions
 on how to set up, run, and test each sample.
+
+For the quickest start, consider using the [Docker setup](rest/docker/README.md),
+which allows you to run both servers without installing dependencies locally.
diff --git a/rest/docker/README.md b/rest/docker/README.md
new file mode 100644
index 0000000..59f083d
--- /dev/null
+++ b/rest/docker/README.md
@@ -0,0 +1,319 @@
+<!--
+   Copyright 2026 UCP Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+# UCP Docker Examples
+
+This directory contains Docker configurations for running UCP reference
+implementations. Docker provides a quick and consistent way to run the UCP servers
+without needing to install Node.js, Python, or their dependencies locally.
+
+## Prerequisites
+
+*   [Docker](https://www.docker.com/get-started) (version 20.10 or higher)
+*   [Docker Compose](https://docs.docker.com/compose/install/) (version 2.0 or
+    higher)
+
+## Quick Start
+
+This directory provides three Docker Compose configurations:
+
+*   **`docker-compose.yml`** - Runs both Node.js and Python servers together
+*   **`docker-compose.nodejs.yml`** - Runs only the Node.js server
+*   **`docker-compose.python.yml`** - Runs only the Python server
+
+### Running Both Servers
+
+To start both the Node.js and Python servers:
+
+```bash
+cd samples/rest/docker
+docker-compose up
+```
+
+This will:
+
+1.  Build Docker images for both servers
+2.  Initialize the Python server's database with sample data
+3.  Start both servers:
+    *   Node.js server on `http://localhost:3000`
+    *   Python server on `http://localhost:8182`
+
+### Running Individual Services
+
+#### Node.js Server Only
+
+You can run the Node.js server using the dedicated compose file:
+
+```bash
+cd samples/rest/docker
+docker-compose -f docker-compose.nodejs.yml up
+```
+
+Or using the main compose file with service selection:
+
+```bash
+docker-compose up nodejs-server
+```
+
+The Node.js server will be available at `http://localhost:3000`.
+
+#### Python Server Only
+
+You can run the Python server using the dedicated compose file:
+
+```bash
+cd samples/rest/docker
+docker-compose -f docker-compose.python.yml up
+```
+
+Or using the main compose file with service selection:
+
+```bash
+docker-compose up python-server
+```
+
+The Python server will be available at `http://localhost:8182`.
+
+## Building Images
+
+To build the images without starting the containers:
+
+```bash
+# Build both services
+docker-compose build
+
+# Build only Node.js
+docker-compose -f docker-compose.nodejs.yml build
+
+# Build only Python
+docker-compose -f docker-compose.python.yml build
+```
+
+To rebuild images from scratch (no cache):
+
+```bash
+docker-compose build --no-cache
+```
+
+## Accessing the Services
+
+Once the services are running, you can access them:
+
+### Node.js Server
+
+*   Discovery endpoint:
+    ```bash
+    curl http://localhost:3000/.well-known/ucp
+    ```
+
+*   Create a checkout session:
+    ```bash
+    curl -X POST http://localhost:3000/checkout-sessions \
+      -H "Content-Type: application/json" \
+      -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
+      -d '{
+        "line_items": [{
+          "item": {"id": "product_1", "title": "Test Product"},
+          "quantity": 1
+        }],
+        "currency": "USD"
+      }'
+    ```
+
+### Python Server
+
+*   Discovery endpoint:
+    ```bash
+    curl http://localhost:8182/.well-known/ucp
+    ```
+
+*   Create a checkout session:
+    ```bash
+    curl -X POST http://localhost:8182/checkout-sessions \
+      -H "Content-Type: application/json" \
+      -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
+      -d '{
+        "line_items": [{
+          "item": {"id": "bouquet_roses", "title": "Red Rose"},
+          "quantity": 1
+        }],
+        "currency": "USD",
+        "buyer": {
+          "full_name": "John Doe",
+          "email": "john.doe@example.com"
+        }
+      }'
+    ```
+
+## Data Persistence
+
+Both servers use Docker volumes to persist data:
+
+*   **Node.js**: SQLite databases are stored in the `nodejs-databases` volume
+*   **Python**: SQLite databases are stored in the `python-data` volume
+
+Data persists across container restarts. To remove all data:
+
+```bash
+docker-compose down -v
+```
+
+## Stopping Services
+
+To stop the services:
+
+```bash
+# Stop both services (if using main compose file)
+docker-compose down
+
+# Stop Node.js only
+docker-compose -f docker-compose.nodejs.yml down
+
+# Stop Python only
+docker-compose -f docker-compose.python.yml down
+```
+
+To stop and remove volumes (this will delete all data):
+
+```bash
+docker-compose down -v
+```
+
+## Viewing Logs
+
+To view logs from all services:
+
+```bash
+docker-compose logs -f
+```
+
+To view logs from a specific service:
+
+```bash
+docker-compose logs -f nodejs-server
+docker-compose logs -f python-server
+```
+
+## Reinitializing Python Database
+
+The Python server automatically initializes its database on first start. To
+reinitialize it:
+
+```bash
+docker-compose exec python-server sh -c \
+  "uv run import_csv.py \
+    --products_db_path=/app/data/products.db \
+    --transactions_db_path=/app/data/transactions.db \
+    --data_dir=/app/test_data/flower_shop"
+```
+
+## Running in Detached Mode
+
+To run services in the background:
+
+```bash
+docker-compose up -d
+```
+
+To stop detached services:
+
+```bash
+docker-compose stop
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+If ports 3000 or 8182 are already in use, you can change them in the respective
+compose files:
+
+**For Node.js** (`docker-compose.nodejs.yml` or `docker-compose.yml`):
+
+```yaml
+services:
+  nodejs-server:
+    ports:
+      - "3001:3000"  # Change 3001 to your preferred port
+```
+
+**For Python** (`docker-compose.python.yml` or `docker-compose.yml`):
+
+```yaml
+services:
+  python-server:
+    ports:
+      - "8183:8182"  # Change 8183 to your preferred port
+```
+
+### Database Issues
+
+If the Python server fails to start due to database issues:
+
+1.  Stop the services: `docker-compose down -v`
+2.  Remove the volume: `docker volume rm docker_python-data`
+3.  Start again: `docker-compose up`
+
+### Build Failures
+
+If builds fail, try:
+
+1.  Clean build: `docker-compose build --no-cache`
+2.  Check Docker has enough resources (memory, disk space)
+3.  Ensure you're in the correct directory (`samples/rest/docker`)
+4.  If using a specific compose file, make sure to specify it: `docker-compose -f docker-compose.nodejs.yml build --no-cache`
+
+### Container Health Checks
+
+Both services include health checks. Check status:
+
+```bash
+docker-compose ps
+```
+
+## Development
+
+For development, you may want to mount source code as volumes for live
+reloading. Modify the respective compose file to add volume mounts:
+
+**For Node.js** (`docker-compose.nodejs.yml`):
+
+```yaml
+services:
+  nodejs-server:
+    volumes:
+      - nodejs-databases:/app/databases
+      - ../nodejs/src:/app/src  # Add for live reload
+```
+
+**For Python** (`docker-compose.python.yml`):
+
+```yaml
+services:
+  python-server:
+    volumes:
+      - python-data:/app/data
+      - ../python/server:/app/server  # Add for live reload
+```
+
+Note: Live reloading requires additional setup and is not included in the base
+configuration.
+
+## Additional Resources
+
+*   [Node.js Server Documentation](../nodejs/README.md)
+*   [Python Server Documentation](../python/server/README.md)
+*   [UCP Documentation](https://ucp.dev)
diff --git a/rest/docker/docker-compose.nodejs.yml b/rest/docker/docker-compose.nodejs.yml
new file mode 100644
index 0000000..9c70b8d
--- /dev/null
+++ b/rest/docker/docker-compose.nodejs.yml
@@ -0,0 +1,37 @@
+#   Copyright 2026 UCP Authors
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+version: '3.8'
+
+services:
+  nodejs-server:
+    build:
+      context: ../nodejs
+      dockerfile: ../docker/nodejs/Dockerfile
+    container_name: ucp-nodejs-server
+    ports:
+      - "3000:3000"
+    volumes:
+      - nodejs-databases:/app/databases
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/.well-known/ucp', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  nodejs-databases:
+    driver: local
diff --git a/rest/docker/docker-compose.python.yml b/rest/docker/docker-compose.python.yml
new file mode 100644
index 0000000..b56b6df
--- /dev/null
+++ b/rest/docker/docker-compose.python.yml
@@ -0,0 +1,37 @@
+#   Copyright 2026 UCP Authors
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+version: '3.8'
+
+services:
+  python-server:
+    build:
+      context: ../../..
+      dockerfile: samples/rest/docker/python/Dockerfile
+    container_name: ucp-python-server
+    ports:
+      - "8182:8182"
+    volumes:
+      - python-data:/app/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8182/.well-known/ucp'); exit(0)"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+volumes:
+  python-data:
+    driver: local
diff --git a/rest/docker/docker-compose.yml b/rest/docker/docker-compose.yml
new file mode 100644
index 0000000..34bd3c4
--- /dev/null
+++ b/rest/docker/docker-compose.yml
@@ -0,0 +1,64 @@
+#   Copyright 2026 UCP Authors
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+version: '3.8'
+
+services:
+  nodejs-server:
+    build:
+      context: ../nodejs
+      dockerfile: ../docker/nodejs/Dockerfile
+    container_name: ucp-nodejs-server
+    ports:
+      - "3000:3000"
+    volumes:
+      - nodejs-databases:/app/databases
+    networks:
+      - ucp-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/.well-known/ucp', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+  python-server:
+    build:
+      context: ../../..
+      dockerfile: samples/rest/docker/python/Dockerfile
+    container_name: ucp-python-server
+    ports:
+      - "8182:8182"
+    volumes:
+      - python-data:/app/data
+    networks:
+      - ucp-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8182/.well-known/ucp'); exit(0)"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+networks:
+  ucp-network:
+    driver: bridge
+
+volumes:
+  nodejs-databases:
+    driver: local
+  python-data:
+    driver: local
diff --git a/rest/docker/nodejs/.dockerignore b/rest/docker/nodejs/.dockerignore
new file mode 100644
index 0000000..73a632d
--- /dev/null
+++ b/rest/docker/nodejs/.dockerignore
@@ -0,0 +1,8 @@
+node_modules
+dist
+databases/*.db
+*.log
+.DS_Store
+.env
+.git
+.gitignore
diff --git a/rest/docker/nodejs/Dockerfile b/rest/docker/nodejs/Dockerfile
new file mode 100644
index 0000000..ce897fc
--- /dev/null
+++ b/rest/docker/nodejs/Dockerfile
@@ -0,0 +1,37 @@
+#   Copyright 2026 UCP Authors
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy source files
+COPY tsconfig.json ./
+COPY src ./src
+COPY scripts ./scripts
+
+# Create databases directory
+RUN mkdir -p databases
+
+# Expose port
+EXPOSE 3000
+
+# Start server using tsx (runs TypeScript directly, no build step needed)
+CMD ["npx", "tsx", "src/index.ts"]
diff --git a/rest/docker/python/.dockerignore b/rest/docker/python/.dockerignore
new file mode 100644
index 0000000..ed0f9be
--- /dev/null
+++ b/rest/docker/python/.dockerignore
@@ -0,0 +1,18 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info
+dist
+build
+.venv
+venv
+.env
+.git
+.gitignore
+.DS_Store
+*.db
+*.log
diff --git a/rest/docker/python/Dockerfile b/rest/docker/python/Dockerfile
new file mode 100644
index 0000000..7c4ce57
--- /dev/null
+++ b/rest/docker/python/Dockerfile
@@ -0,0 +1,47 @@
+#   Copyright 2026 UCP Authors
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+FROM python:3.11-slim
+
+# Install uv
+RUN pip install --no-cache-dir uv
+
+WORKDIR /app
+
+# Copy SDK first (needed by server)
+COPY sdk/python /app/sdk/python
+
+# Copy server files
+COPY samples/rest/python/server /app/server
+
+# Copy test data
+COPY samples/rest/python/test_data /app/test_data
+
+WORKDIR /app/server
+
+# Update pyproject.toml to use the copied SDK path
+RUN python3 -c "import re; content = open('pyproject.toml').read(); content = re.sub(r'path = \"\.\.\/\.\.\/\.\.\/\.\.\/sdk\/python\/\"', 'path = \"/app/sdk/python/\"', content); open('pyproject.toml', 'w').write(content)"
+
+# Install dependencies using uv
+RUN uv sync
+
+# Create data directory for databases
+RUN mkdir -p /app/data
+
+# Expose port
+EXPOSE 8182
+
+# Default command: initialize database and start server
+# Users can override this to run different commands
+CMD ["sh", "-c", "uv run import_csv.py --products_db_path=/app/data/products.db --transactions_db_path=/app/data/transactions.db --data_dir=/app/test_data/flower_shop && uv run server.py --products_db_path=/app/data/products.db --transactions_db_path=/app/data/transactions.db --port=8182"]
diff --git a/rest/nodejs/README.md b/rest/nodejs/README.md
index 7209b58..5697011 100644
--- a/rest/nodejs/README.md
+++ b/rest/nodejs/README.md
@@ -81,6 +81,26 @@ endpoint at:
 http://localhost:3000/.well-known/ucp
 ```
 
+## Running with Docker
+
+For a quick start without installing Node.js locally, you can use Docker:
+
+```bash
+cd ../docker
+docker-compose -f docker-compose.nodejs.yml up
+```
+
+Or using the main compose file:
+
+```bash
+docker-compose up nodejs-server
+```
+
+This will build and start the Node.js server in a Docker container. The server
+will be available at `http://localhost:3000`.
+
+For more details and options, see the [Docker documentation](../docker/README.md).
+
 ## Running Conformance Tests
 
 To verify that this server implementation complies with the UCP specifications,
diff --git a/rest/python/server/README.md b/rest/python/server/README.md
index f6e7c73..33a4d66 100644
--- a/rest/python/server/README.md
+++ b/rest/python/server/README.md
@@ -87,6 +87,27 @@ SERVER_PID=$!
 Note: Keep the server running for the duration of running the client and the
 following experiments.
 
+## Running with Docker
+
+For a quick start without installing Python or uv locally, you can use Docker:
+
+```bash
+cd ../../docker
+docker-compose -f docker-compose.python.yml up
+```
+
+Or using the main compose file:
+
+```bash
+docker-compose up python-server
+```
+
+This will build and start the Python server in a Docker container, automatically
+initializing the database with sample data. The server will be available at
+`http://localhost:8182`.
+
+For more details and options, see the [Docker documentation](../../docker/README.md).
+
 ## Run a Simple Client
 
 Exercise a simple checkout path: Once the server is running, execute the simple

From 5d0c5bf84418cfad473aa79b1158fa4b0686fc21 Mon Sep 17 00:00:00 2001
From: Geanderson <geandersonlemonte.gl@gmail.com>
Date: Wed, 14 Jan 2026 08:31:18 -0300
Subject: [PATCH 2/5] feat: add Docker configurations for Node.js and Python
 servers

- Introduced separate Docker Compose files for Node.js and Python servers.
- Updated README.md to reflect new Docker setup documentation.
- Removed the old combined Docker Compose file.
- Added .dockerignore files for both Node.js and Python to exclude unnecessary files.
- Created Dockerfiles for both servers to streamline the build process.
---
 README.md                                     |   9 +-
 {rest/docker => docker}/README.md             | 189 ++++++++----------
 .../docker-compose.nodejs.yml                 |   6 +-
 .../docker-compose.python.yml                 |   4 +-
 {rest/docker => docker}/nodejs/.dockerignore  |   1 +
 {rest/docker => docker}/nodejs/Dockerfile     |   0
 {rest/docker => docker}/python/.dockerignore  |   0
 {rest/docker => docker}/python/Dockerfile     |   0
 rest/docker/docker-compose.yml                |  64 ------
 9 files changed, 91 insertions(+), 182 deletions(-)
 rename {rest/docker => docker}/README.md (60%)
 rename {rest/docker => docker}/docker-compose.nodejs.yml (92%)
 rename {rest/docker => docker}/docker-compose.python.yml (93%)
 rename {rest/docker => docker}/nodejs/.dockerignore (93%)
 rename {rest/docker => docker}/nodejs/Dockerfile (100%)
 rename {rest/docker => docker}/python/.dockerignore (100%)
 rename {rest/docker => docker}/python/Dockerfile (100%)
 delete mode 100644 rest/docker/docker-compose.yml

diff --git a/README.md b/README.md
index fd25bf0..162cd0f 100644
--- a/README.md
+++ b/README.md
@@ -52,11 +52,10 @@ Zod.
 ### Docker
 
 Docker configurations for running UCP servers. Includes separate compose files
-for each server and a combined setup.
+for each server.
 
-*   **Docker Setup**: [Documentation](rest/docker/README.md)
-    *   Located in `rest/docker/`.
-    *   Includes `docker-compose.yml` to orchestrate both servers together.
+*   **Docker Setup**: [Documentation](docker/README.md)
+    *   Located in `docker/`.
     *   Includes `docker-compose.nodejs.yml` for Node.js server only.
     *   Includes `docker-compose.python.yml` for Python server only.
     *   Quick start option that doesn't require local Node.js or Python
@@ -67,5 +66,5 @@ for each server and a combined setup.
 Please refer to the specific README files linked above for detailed instructions
 on how to set up, run, and test each sample.
 
-For the quickest start, consider using the [Docker setup](rest/docker/README.md),
+For the quickest start, consider using the [Docker setup](docker/README.md),
 which allows you to run both servers without installing dependencies locally.
diff --git a/rest/docker/README.md b/docker/README.md
similarity index 60%
rename from rest/docker/README.md
rename to docker/README.md
index 59f083d..42e424e 100644
--- a/rest/docker/README.md
+++ b/docker/README.md
@@ -28,29 +28,11 @@ without needing to install Node.js, Python, or their dependencies locally.
 
 ## Quick Start
 
-This directory provides three Docker Compose configurations:
+This directory provides two Docker Compose configurations:
 
-*   **`docker-compose.yml`** - Runs both Node.js and Python servers together
 *   **`docker-compose.nodejs.yml`** - Runs only the Node.js server
 *   **`docker-compose.python.yml`** - Runs only the Python server
 
-### Running Both Servers
-
-To start both the Node.js and Python servers:
-
-```bash
-cd samples/rest/docker
-docker-compose up
-```
-
-This will:
-
-1.  Build Docker images for both servers
-2.  Initialize the Python server's database with sample data
-3.  Start both servers:
-    *   Node.js server on `http://localhost:3000`
-    *   Python server on `http://localhost:8182`
-
 ### Running Individual Services
 
 #### Node.js Server Only
@@ -58,16 +40,10 @@ This will:
 You can run the Node.js server using the dedicated compose file:
 
 ```bash
-cd samples/rest/docker
+cd samples/docker
 docker-compose -f docker-compose.nodejs.yml up
 ```
 
-Or using the main compose file with service selection:
-
-```bash
-docker-compose up nodejs-server
-```
-
 The Node.js server will be available at `http://localhost:3000`.
 
 #### Python Server Only
@@ -75,88 +51,71 @@ The Node.js server will be available at `http://localhost:3000`.
 You can run the Python server using the dedicated compose file:
 
 ```bash
-cd samples/rest/docker
+cd samples/docker
 docker-compose -f docker-compose.python.yml up
 ```
 
-Or using the main compose file with service selection:
+The Python server will be available at `http://localhost:8182`.
+
+### Running Both Servers
+
+To start both the Node.js and Python servers, you need to run them in separate terminals:
 
+**Terminal 1 - Node.js Server:**
 ```bash
-docker-compose up python-server
+cd samples/docker
+docker-compose -f docker-compose.nodejs.yml up
 ```
 
-The Python server will be available at `http://localhost:8182`.
+**Terminal 2 - Python Server:**
+```bash
+cd samples/docker
+docker-compose -f docker-compose.python.yml up
+```
+
+This will:
+
+1.  Build Docker images for both servers
+2.  Initialize the Python server's database with sample data
+3.  Start both servers:
+    *   Node.js server on `http://localhost:3000`
+    *   Python server on `http://localhost:8182`
 
 ## Building Images
 
 To build the images without starting the containers:
 
 ```bash
-# Build both services
-docker-compose build
-
-# Build only Node.js
+# Build Node.js server
 docker-compose -f docker-compose.nodejs.yml build
 
-# Build only Python
+# Build Python server
 docker-compose -f docker-compose.python.yml build
 ```
 
 To rebuild images from scratch (no cache):
 
 ```bash
-docker-compose build --no-cache
+# Rebuild Node.js server
+docker-compose -f docker-compose.nodejs.yml build --no-cache
+
+# Rebuild Python server
+docker-compose -f docker-compose.python.yml build --no-cache
 ```
 
 ## Accessing the Services
 
-Once the services are running, you can access them:
+Once the services are running, you can access them. For detailed information on how to test and interact with each server, please refer to their respective documentation:
 
 ### Node.js Server
 
-*   Discovery endpoint:
-    ```bash
-    curl http://localhost:3000/.well-known/ucp
-    ```
-
-*   Create a checkout session:
-    ```bash
-    curl -X POST http://localhost:3000/checkout-sessions \
-      -H "Content-Type: application/json" \
-      -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
-      -d '{
-        "line_items": [{
-          "item": {"id": "product_1", "title": "Test Product"},
-          "quantity": 1
-        }],
-        "currency": "USD"
-      }'
-    ```
+*   **Documentation**: [Node.js Server README](../rest/nodejs/README.md)
+*   Available at `http://localhost:3000`
 
 ### Python Server
 
-*   Discovery endpoint:
-    ```bash
-    curl http://localhost:8182/.well-known/ucp
-    ```
-
-*   Create a checkout session:
-    ```bash
-    curl -X POST http://localhost:8182/checkout-sessions \
-      -H "Content-Type: application/json" \
-      -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
-      -d '{
-        "line_items": [{
-          "item": {"id": "bouquet_roses", "title": "Red Rose"},
-          "quantity": 1
-        }],
-        "currency": "USD",
-        "buyer": {
-          "full_name": "John Doe",
-          "email": "john.doe@example.com"
-        }
-      }'
-    ```
+*   **Documentation**: [Python Server README](../rest/python/server/README.md)
+*   Available at `http://localhost:8182`
 
 ## Data Persistence
 
@@ -168,7 +127,11 @@ Both servers use Docker volumes to persist data:
 Data persists across container restarts. To remove all data:
 
 ```bash
-docker-compose down -v
+# Remove Node.js data
+docker-compose -f docker-compose.nodejs.yml down -v
+
+# Remove Python data
+docker-compose -f docker-compose.python.yml down -v
 ```
 
 ## Stopping Services
@@ -176,35 +139,33 @@ docker-compose down -v
 To stop the services:
 
 ```bash
-# Stop both services (if using main compose file)
-docker-compose down
-
-# Stop Node.js only
+# Stop Node.js
 docker-compose -f docker-compose.nodejs.yml down
 
-# Stop Python only
+# Stop Python
 docker-compose -f docker-compose.python.yml down
 ```
 
 To stop and remove volumes (this will delete all data):
 
 ```bash
-docker-compose down -v
+# Stop Node.js and remove volumes
+docker-compose -f docker-compose.nodejs.yml down -v
+
+# Stop Python and remove volumes
+docker-compose -f docker-compose.python.yml down -v
 ```
 
 ## Viewing Logs
 
-To view logs from all services:
-
-```bash
-docker-compose logs -f
-```
-
 To view logs from a specific service:
 
 ```bash
-docker-compose logs -f nodejs-server
-docker-compose logs -f python-server
+# Node.js server logs
+docker-compose -f docker-compose.nodejs.yml logs -f
+
+# Python server logs
+docker-compose -f docker-compose.python.yml logs -f
 ```
 
 ## Reinitializing Python Database
@@ -213,7 +174,7 @@ The Python server automatically initializes its database on first start. To
 reinitialize it:
 
 ```bash
-docker-compose exec python-server sh -c \
+docker-compose -f docker-compose.python.yml exec python-server sh -c \
   "uv run import_csv.py \
     --products_db_path=/app/data/products.db \
     --transactions_db_path=/app/data/transactions.db \
@@ -225,13 +186,21 @@ docker-compose exec python-server sh -c \
 To run services in the background:
 
 ```bash
-docker-compose up -d
+# Run Node.js server in background
+docker-compose -f docker-compose.nodejs.yml up -d
+
+# Run Python server in background
+docker-compose -f docker-compose.python.yml up -d
 ```
 
 To stop detached services:
 
 ```bash
-docker-compose stop
+# Stop Node.js server
+docker-compose -f docker-compose.nodejs.yml stop
+
+# Stop Python server
+docker-compose -f docker-compose.python.yml stop
 ```
 
 ## Troubleshooting
@@ -241,7 +210,7 @@ docker-compose stop
 If ports 3000 or 8182 are already in use, you can change them in the respective
 compose files:
 
-**For Node.js** (`docker-compose.nodejs.yml` or `docker-compose.yml`):
+**For Node.js** (`docker-compose.nodejs.yml`):
 
 ```yaml
 services:
@@ -250,7 +219,7 @@ services:
       - "3001:3000"  # Change 3001 to your preferred port
 ```
 
-**For Python** (`docker-compose.python.yml` or `docker-compose.yml`):
+**For Python** (`docker-compose.python.yml`):
 
 ```yaml
 services:
@@ -263,25 +232,29 @@ services:
 
 If the Python server fails to start due to database issues:
 
-1.  Stop the services: `docker-compose down -v`
-2.  Remove the volume: `docker volume rm docker_python-data`
-3.  Start again: `docker-compose up`
+1.  Stop the service: `docker-compose -f docker-compose.python.yml down -v`
+2.  Remove the volume: `docker volume rm samples_docker_python-data`
+3.  Start again: `docker-compose -f docker-compose.python.yml up`
 
 ### Build Failures
 
 If builds fail, try:
 
-1.  Clean build: `docker-compose build --no-cache`
+1.  Clean build: `docker-compose -f docker-compose.nodejs.yml build --no-cache` or `docker-compose -f docker-compose.python.yml build --no-cache`
 2.  Check Docker has enough resources (memory, disk space)
-3.  Ensure you're in the correct directory (`samples/rest/docker`)
-4.  If using a specific compose file, make sure to specify it: `docker-compose -f docker-compose.nodejs.yml build --no-cache`
+3.  Ensure you're in the correct directory (`samples/docker`)
+4.  Make sure to specify the compose file: `docker-compose -f docker-compose.nodejs.yml build --no-cache` or `docker-compose -f docker-compose.python.yml build --no-cache`
 
 ### Container Health Checks
 
 Both services include health checks. Check status:
 
 ```bash
-docker-compose ps
+# Check Node.js server status
+docker-compose -f docker-compose.nodejs.yml ps
+
+# Check Python server status
+docker-compose -f docker-compose.python.yml ps
 ```
 
 ## Development
@@ -296,7 +269,7 @@ services:
   nodejs-server:
     volumes:
       - nodejs-databases:/app/databases
-      - ../nodejs/src:/app/src  # Add for live reload
+      - ../rest/nodejs/src:/app/src  # Add for live reload
 ```
 
 **For Python** (`docker-compose.python.yml`):
@@ -306,7 +279,7 @@ services:
   python-server:
     volumes:
       - python-data:/app/data
-      - ../python/server:/app/server  # Add for live reload
+      - ../rest/python/server:/app/server  # Add for live reload
 ```
 
 Note: Live reloading requires additional setup and is not included in the base
@@ -314,6 +287,6 @@ configuration.
 
 ## Additional Resources
 
-*   [Node.js Server Documentation](../nodejs/README.md)
-*   [Python Server Documentation](../python/server/README.md)
+*   [Node.js Server Documentation](../rest/nodejs/README.md)
+*   [Python Server Documentation](../rest/python/server/README.md)
 *   [UCP Documentation](https://ucp.dev)
diff --git a/rest/docker/docker-compose.nodejs.yml b/docker/docker-compose.nodejs.yml
similarity index 92%
rename from rest/docker/docker-compose.nodejs.yml
rename to docker/docker-compose.nodejs.yml
index 9c70b8d..c21d305 100644
--- a/rest/docker/docker-compose.nodejs.yml
+++ b/docker/docker-compose.nodejs.yml
@@ -12,13 +12,13 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-version: '3.8'
+version: '5.0.1'
 
 services:
   nodejs-server:
     build:
-      context: ../nodejs
-      dockerfile: ../docker/nodejs/Dockerfile
+      context: ../rest/nodejs
+      dockerfile: nodejs/Dockerfile
     container_name: ucp-nodejs-server
     ports:
       - "3000:3000"
diff --git a/rest/docker/docker-compose.python.yml b/docker/docker-compose.python.yml
similarity index 93%
rename from rest/docker/docker-compose.python.yml
rename to docker/docker-compose.python.yml
index b56b6df..2e2fe9e 100644
--- a/rest/docker/docker-compose.python.yml
+++ b/docker/docker-compose.python.yml
@@ -12,13 +12,13 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-version: '3.8'
+version: '5.0.1'
 
 services:
   python-server:
     build:
       context: ../../..
-      dockerfile: samples/rest/docker/python/Dockerfile
+      dockerfile: samples/docker/python/Dockerfile
     container_name: ucp-python-server
     ports:
       - "8182:8182"
diff --git a/rest/docker/nodejs/.dockerignore b/docker/nodejs/.dockerignore
similarity index 93%
rename from rest/docker/nodejs/.dockerignore
rename to docker/nodejs/.dockerignore
index 73a632d..2fe86ff 100644
--- a/rest/docker/nodejs/.dockerignore
+++ b/docker/nodejs/.dockerignore
@@ -6,3 +6,4 @@ databases/*.db
 .env
 .git
 .gitignore
+*.md
diff --git a/rest/docker/nodejs/Dockerfile b/docker/nodejs/Dockerfile
similarity index 100%
rename from rest/docker/nodejs/Dockerfile
rename to docker/nodejs/Dockerfile
diff --git a/rest/docker/python/.dockerignore b/docker/python/.dockerignore
similarity index 100%
rename from rest/docker/python/.dockerignore
rename to docker/python/.dockerignore
diff --git a/rest/docker/python/Dockerfile b/docker/python/Dockerfile
similarity index 100%
rename from rest/docker/python/Dockerfile
rename to docker/python/Dockerfile
diff --git a/rest/docker/docker-compose.yml b/rest/docker/docker-compose.yml
deleted file mode 100644
index 34bd3c4..0000000
--- a/rest/docker/docker-compose.yml
+++ /dev/null
@@ -1,64 +0,0 @@
-#   Copyright 2026 UCP Authors
-#
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
-
-version: '3.8'
-
-services:
-  nodejs-server:
-    build:
-      context: ../nodejs
-      dockerfile: ../docker/nodejs/Dockerfile
-    container_name: ucp-nodejs-server
-    ports:
-      - "3000:3000"
-    volumes:
-      - nodejs-databases:/app/databases
-    networks:
-      - ucp-network
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/.well-known/ucp', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 10s
-
-  python-server:
-    build:
-      context: ../../..
-      dockerfile: samples/rest/docker/python/Dockerfile
-    container_name: ucp-python-server
-    ports:
-      - "8182:8182"
-    volumes:
-      - python-data:/app/data
-    networks:
-      - ucp-network
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8182/.well-known/ucp'); exit(0)"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 30s
-
-networks:
-  ucp-network:
-    driver: bridge
-
-volumes:
-  nodejs-databases:
-    driver: local
-  python-data:
-    driver: local

From 6d5731c61a3c9a97c0a622e1b768443c8cfbf681 Mon Sep 17 00:00:00 2001
From: Geanderson <geandersonlemonte.gl@gmail.com>
Date: Wed, 14 Jan 2026 08:44:15 -0300
Subject: [PATCH 3/5] chore: update .dockerignore to exclude markdown files

- Added '*.md' to the .dockerignore file for the Python Docker setup to prevent markdown files from being included in the Docker context.
---
 docker/python/.dockerignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docker/python/.dockerignore b/docker/python/.dockerignore
index ed0f9be..a7ff1fa 100644
--- a/docker/python/.dockerignore
+++ b/docker/python/.dockerignore
@@ -16,3 +16,4 @@ venv
 .DS_Store
 *.db
 *.log
+*.md

From 0bb19b8f2f330c6fa488b70a4821f063da42df6d Mon Sep 17 00:00:00 2001
From: Geanderson <geandersonlemonte.gl@gmail.com>
Date: Wed, 14 Jan 2026 09:39:15 -0300
Subject: [PATCH 4/5] fix: update Docker Compose configurations for Node.js and
 Python servers

- Corrected the Dockerfile paths in `docker-compose.nodejs.yml` and `docker-compose.python.yml`.
- Updated the README files for both Node.js and Python servers to improve clarity and organization of setup instructions.
- Removed outdated sections from the README files to streamline the documentation.
---
 docker/README.md                 | 259 +------------------------------
 docker/docker-compose.nodejs.yml |   2 +-
 docker/docker-compose.python.yml |   2 +-
 docker/nodejs/README.md          | 160 +++++++++++++++++++
 docker/python/README.md          | 171 ++++++++++++++++++++
 5 files changed, 339 insertions(+), 255 deletions(-)
 create mode 100644 docker/nodejs/README.md
 create mode 100644 docker/python/README.md

diff --git a/docker/README.md b/docker/README.md
index 42e424e..087e703 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -26,264 +26,17 @@ without needing to install Node.js, Python, or their dependencies locally.
 *   [Docker Compose](https://docs.docker.com/compose/install/) (version 2.0 or
     higher)
 
-## Quick Start
+## Available Services
 
 This directory provides two Docker Compose configurations:
 
-*   **`docker-compose.nodejs.yml`** - Runs only the Node.js server
-*   **`docker-compose.python.yml`** - Runs only the Python server
+*   **`docker-compose.nodejs.yml`** - Runs the Node.js server
+*   **`docker-compose.python.yml`** - Runs the Python server
 
-### Running Individual Services
+For detailed instructions on how to use each service, please refer to their respective documentation:
 
-#### Node.js Server Only
-
-You can run the Node.js server using the dedicated compose file:
-
-```bash
-cd samples/docker
-docker-compose -f docker-compose.nodejs.yml up
-```
-
-The Node.js server will be available at `http://localhost:3000`.
-
-#### Python Server Only
-
-You can run the Python server using the dedicated compose file:
-
-```bash
-cd samples/docker
-docker-compose -f docker-compose.python.yml up
-```
-
-The Python server will be available at `http://localhost:8182`.
-
-### Running Both Servers
-
-To start both the Node.js and Python servers, you need to run them in separate terminals:
-
-**Terminal 1 - Node.js Server:**
-```bash
-cd samples/docker
-docker-compose -f docker-compose.nodejs.yml up
-```
-
-**Terminal 2 - Python Server:**
-```bash
-cd samples/docker
-docker-compose -f docker-compose.python.yml up
-```
-
-This will:
-
-1.  Build Docker images for both servers
-2.  Initialize the Python server's database with sample data
-3.  Start both servers:
-    *   Node.js server on `http://localhost:3000`
-    *   Python server on `http://localhost:8182`
-
-## Building Images
-
-To build the images without starting the containers:
-
-```bash
-# Build Node.js server
-docker-compose -f docker-compose.nodejs.yml build
-
-# Build Python server
-docker-compose -f docker-compose.python.yml build
-```
-
-To rebuild images from scratch (no cache):
-
-```bash
-# Rebuild Node.js server
-docker-compose -f docker-compose.nodejs.yml build --no-cache
-
-# Rebuild Python server
-docker-compose -f docker-compose.python.yml build --no-cache
-```
-
-## Accessing the Services
-
-Once the services are running, you can access them. For detailed information on how to test and interact with each server, please refer to their respective documentation:
-
-### Node.js Server
-
-*   **Documentation**: [Node.js Server README](../rest/nodejs/README.md)
-*   Available at `http://localhost:3000`
-
-### Python Server
-
-*   **Documentation**: [Python Server README](../rest/python/server/README.md)
-*   Available at `http://localhost:8182`
-
-## Data Persistence
-
-Both servers use Docker volumes to persist data:
-
-*   **Node.js**: SQLite databases are stored in the `nodejs-databases` volume
-*   **Python**: SQLite databases are stored in the `python-data` volume
-
-Data persists across container restarts. To remove all data:
-
-```bash
-# Remove Node.js data
-docker-compose -f docker-compose.nodejs.yml down -v
-
-# Remove Python data
-docker-compose -f docker-compose.python.yml down -v
-```
-
-## Stopping Services
-
-To stop the services:
-
-```bash
-# Stop Node.js
-docker-compose -f docker-compose.nodejs.yml down
-
-# Stop Python
-docker-compose -f docker-compose.python.yml down
-```
-
-To stop and remove volumes (this will delete all data):
-
-```bash
-# Stop Node.js and remove volumes
-docker-compose -f docker-compose.nodejs.yml down -v
-
-# Stop Python and remove volumes
-docker-compose -f docker-compose.python.yml down -v
-```
-
-## Viewing Logs
-
-To view logs from a specific service:
-
-```bash
-# Node.js server logs
-docker-compose -f docker-compose.nodejs.yml logs -f
-
-# Python server logs
-docker-compose -f docker-compose.python.yml logs -f
-```
-
-## Reinitializing Python Database
-
-The Python server automatically initializes its database on first start. To
-reinitialize it:
-
-```bash
-docker-compose -f docker-compose.python.yml exec python-server sh -c \
-  "uv run import_csv.py \
-    --products_db_path=/app/data/products.db \
-    --transactions_db_path=/app/data/transactions.db \
-    --data_dir=/app/test_data/flower_shop"
-```
-
-## Running in Detached Mode
-
-To run services in the background:
-
-```bash
-# Run Node.js server in background
-docker-compose -f docker-compose.nodejs.yml up -d
-
-# Run Python server in background
-docker-compose -f docker-compose.python.yml up -d
-```
-
-To stop detached services:
-
-```bash
-# Stop Node.js server
-docker-compose -f docker-compose.nodejs.yml stop
-
-# Stop Python server
-docker-compose -f docker-compose.python.yml stop
-```
-
-## Troubleshooting
-
-### Port Already in Use
-
-If ports 3000 or 8182 are already in use, you can change them in the respective
-compose files:
-
-**For Node.js** (`docker-compose.nodejs.yml`):
-
-```yaml
-services:
-  nodejs-server:
-    ports:
-      - "3001:3000"  # Change 3001 to your preferred port
-```
-
-**For Python** (`docker-compose.python.yml`):
-
-```yaml
-services:
-  python-server:
-    ports:
-      - "8183:8182"  # Change 8183 to your preferred port
-```
-
-### Database Issues
-
-If the Python server fails to start due to database issues:
-
-1.  Stop the service: `docker-compose -f docker-compose.python.yml down -v`
-2.  Remove the volume: `docker volume rm samples_docker_python-data`
-3.  Start again: `docker-compose -f docker-compose.python.yml up`
-
-### Build Failures
-
-If builds fail, try:
-
-1.  Clean build: `docker-compose -f docker-compose.nodejs.yml build --no-cache` or `docker-compose -f docker-compose.python.yml build --no-cache`
-2.  Check Docker has enough resources (memory, disk space)
-3.  Ensure you're in the correct directory (`samples/docker`)
-4.  Make sure to specify the compose file: `docker-compose -f docker-compose.nodejs.yml build --no-cache` or `docker-compose -f docker-compose.python.yml build --no-cache`
-
-### Container Health Checks
-
-Both services include health checks. Check status:
-
-```bash
-# Check Node.js server status
-docker-compose -f docker-compose.nodejs.yml ps
-
-# Check Python server status
-docker-compose -f docker-compose.python.yml ps
-```
-
-## Development
-
-For development, you may want to mount source code as volumes for live
-reloading. Modify the respective compose file to add volume mounts:
-
-**For Node.js** (`docker-compose.nodejs.yml`):
-
-```yaml
-services:
-  nodejs-server:
-    volumes:
-      - nodejs-databases:/app/databases
-      - ../rest/nodejs/src:/app/src  # Add for live reload
-```
-
-**For Python** (`docker-compose.python.yml`):
-
-```yaml
-services:
-  python-server:
-    volumes:
-      - python-data:/app/data
-      - ../rest/python/server:/app/server  # Add for live reload
-```
-
-Note: Live reloading requires additional setup and is not included in the base
-configuration.
+*   [Node.js Docker Setup](./nodejs/README.md)
+*   [Python Docker Setup](./python/README.md)
 
 ## Additional Resources
 
diff --git a/docker/docker-compose.nodejs.yml b/docker/docker-compose.nodejs.yml
index c21d305..49b0510 100644
--- a/docker/docker-compose.nodejs.yml
+++ b/docker/docker-compose.nodejs.yml
@@ -18,7 +18,7 @@ services:
   nodejs-server:
     build:
       context: ../rest/nodejs
-      dockerfile: nodejs/Dockerfile
+      dockerfile: ../../docker/nodejs/Dockerfile
     container_name: ucp-nodejs-server
     ports:
       - "3000:3000"
diff --git a/docker/docker-compose.python.yml b/docker/docker-compose.python.yml
index 2e2fe9e..62f0989 100644
--- a/docker/docker-compose.python.yml
+++ b/docker/docker-compose.python.yml
@@ -17,7 +17,7 @@ version: '5.0.1'
 services:
   python-server:
     build:
-      context: ../../..
+      context: ../..
       dockerfile: samples/docker/python/Dockerfile
     container_name: ucp-python-server
     ports:
diff --git a/docker/nodejs/README.md b/docker/nodejs/README.md
new file mode 100644
index 0000000..badcdee
--- /dev/null
+++ b/docker/nodejs/README.md
@@ -0,0 +1,160 @@
+<!--
+   Copyright 2026 UCP Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+# Node.js Server Docker Setup
+
+This directory contains the Docker configuration for running the UCP Node.js server.
+
+## Quick Start
+
+To run the Node.js server:
+
+```bash
+cd samples/docker
+docker-compose -f docker-compose.nodejs.yml up
+```
+
+The Node.js server will be available at `http://localhost:3000`.
+
+## Building the Image
+
+To build the image without starting the container:
+
+```bash
+docker-compose -f docker-compose.nodejs.yml build
+```
+
+To rebuild from scratch (no cache):
+
+```bash
+docker-compose -f docker-compose.nodejs.yml build --no-cache
+```
+
+## Accessing the Service
+
+Once the service is running, you can access it at `http://localhost:3000`.
+
+For detailed information on how to test and interact with the server, please refer to the [Node.js Server README](../../rest/nodejs/README.md).
+
+## Data Persistence
+
+The Node.js server uses a Docker volume (`nodejs-databases`) to persist SQLite databases. Data persists across container restarts.
+
+To remove all data:
+
+```bash
+docker-compose -f docker-compose.nodejs.yml down -v
+```
+
+## Stopping the Service
+
+To stop the service:
+
+```bash
+docker-compose -f docker-compose.nodejs.yml down
+```
+
+To stop and remove volumes (this will delete all data):
+
+```bash
+docker-compose -f docker-compose.nodejs.yml down -v
+```
+
+## Viewing Logs
+
+To view logs from the service:
+
+```bash
+docker-compose -f docker-compose.nodejs.yml logs -f
+```
+
+## Running in Detached Mode
+
+To run the service in the background:
+
+```bash
+docker-compose -f docker-compose.nodejs.yml up -d
+```
+
+To stop the detached service:
+
+```bash
+docker-compose -f docker-compose.nodejs.yml stop
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+If port 3000 is already in use, you can change it in `docker-compose.nodejs.yml`:
+
+```yaml
+services:
+  nodejs-server:
+    ports:
+      - "3001:3000"  # Change 3001 to your preferred port
+```
+
+### Build Failures
+
+If builds fail, try:
+
+1.  Clean build: `docker-compose -f docker-compose.nodejs.yml build --no-cache`
+2.  Check Docker has enough resources (memory, disk space)
+3.  Ensure you're in the correct directory (`samples/docker`)
+4.  Make sure to specify the compose file: `docker-compose -f docker-compose.nodejs.yml build --no-cache`
+
+### Container Health Checks
+
+The service includes health checks. Check status:
+
+```bash
+docker-compose -f docker-compose.nodejs.yml ps
+```
+
+### Orphan Containers and Network Issues
+
+If you see warnings about orphan containers or network errors:
+
+1.  Stop all services and remove orphan containers:
+    ```bash
+    docker-compose -f docker-compose.nodejs.yml down --remove-orphans
+    ```
+
+2.  If the issue persists, remove the container manually:
+    ```bash
+    docker rm -f ucp-nodejs-server
+    docker-compose -f docker-compose.nodejs.yml up
+    ```
+
+3.  To clean up all Docker resources (containers, networks, volumes):
+    ```bash
+    docker-compose -f docker-compose.nodejs.yml down -v --remove-orphans
+    ```
+
+## Development
+
+For development, you may want to mount source code as volumes for live reloading. Modify `docker-compose.nodejs.yml` to add volume mounts:
+
+```yaml
+services:
+  nodejs-server:
+    volumes:
+      - nodejs-databases:/app/databases
+      - ../rest/nodejs/src:/app/src  # Add for live reload
+```
+
+Note: Live reloading requires additional setup and is not included in the base configuration.
diff --git a/docker/python/README.md b/docker/python/README.md
new file mode 100644
index 0000000..863cb6b
--- /dev/null
+++ b/docker/python/README.md
@@ -0,0 +1,171 @@
+<!--
+   Copyright 2026 UCP Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+
+# Python Server Docker Setup
+
+This directory contains the Docker configuration for running the UCP Python server.
+
+## Quick Start
+
+To run the Python server:
+
+```bash
+cd samples/docker
+docker-compose -f docker-compose.python.yml up
+```
+
+The Python server will be available at `http://localhost:8182`.
+
+## Building the Image
+
+To build the image without starting the container:
+
+```bash
+docker-compose -f docker-compose.python.yml build
+```
+
+To rebuild from scratch (no cache):
+
+```bash
+docker-compose -f docker-compose.python.yml build --no-cache
+```
+
+## Accessing the Service
+
+Once the service is running, you can access it at `http://localhost:8182`.
+
+For detailed information on how to test and interact with the server, please refer to the [Python Server README](../../rest/python/server/README.md).
+
+## Data Persistence
+
+The Python server uses a Docker volume (`python-data`) to persist SQLite databases. Data persists across container restarts.
+
+To remove all data:
+
+```bash
+docker-compose -f docker-compose.python.yml down -v
+```
+
+## Stopping the Service
+
+To stop the service:
+
+```bash
+docker-compose -f docker-compose.python.yml down
+```
+
+To stop and remove volumes (this will delete all data):
+
+```bash
+docker-compose -f docker-compose.python.yml down -v
+```
+
+## Viewing Logs
+
+To view logs from the service:
+
+```bash
+docker-compose -f docker-compose.python.yml logs -f
+```
+
+## Running in Detached Mode
+
+To run the service in the background:
+
+```bash
+docker-compose -f docker-compose.python.yml up -d
+```
+
+To stop the detached service:
+
+```bash
+docker-compose -f docker-compose.python.yml stop
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+If port 8182 is already in use, you can change it in `docker-compose.python.yml`:
+
+```yaml
+services:
+  python-server:
+    ports:
+      - "8183:8182"  # Change 8183 to your preferred port
+```
+
+### Database Issues
+
+If the Python server fails to start due to database issues:
+
+1.  Stop the service: `docker-compose -f docker-compose.python.yml down -v`
+2.  If the volume still exists, remove it manually:
+    ```bash
+    docker volume ls | grep python-data
+    docker volume rm <volume-name>
+    ```
+3.  Start again: `docker-compose -f docker-compose.python.yml up`
+
+### Build Failures
+
+If builds fail, try:
+
+1.  Clean build: `docker-compose -f docker-compose.python.yml build --no-cache`
+2.  Check Docker has enough resources (memory, disk space)
+3.  Ensure you're in the correct directory (`samples/docker`)
+
+### Container Health Checks
+
+The service includes health checks. Check status:
+
+```bash
+docker-compose -f docker-compose.python.yml ps
+```
+
+### Orphan Containers and Network Issues
+
+If you see warnings about orphan containers or network errors:
+
+1.  Stop all services and remove orphan containers:
+    ```bash
+    docker-compose -f docker-compose.python.yml down --remove-orphans
+    ```
+
+2.  If the issue persists, remove the container manually:
+    ```bash
+    docker rm -f ucp-python-server
+    docker-compose -f docker-compose.python.yml up
+    ```
+
+3.  To clean up all Docker resources (containers, networks, volumes):
+    ```bash
+    docker-compose -f docker-compose.python.yml down -v --remove-orphans
+    ```
+
+## Development
+
+For development, you may want to mount source code as volumes for live reloading. Modify `docker-compose.python.yml` to add volume mounts:
+
+```yaml
+services:
+  python-server:
+    volumes:
+      - python-data:/app/data
+      - ../rest/python/server:/app/server  # Add for live reload
+```
+
+Note: Live reloading requires additional setup and is not included in the base configuration.

From 70d651af9c1afaafad18db7fef5a98b741063e3d Mon Sep 17 00:00:00 2001
From: Geanderson <geandersonlemonte.gl@gmail.com>
Date: Wed, 14 Jan 2026 14:20:41 -0300
Subject: [PATCH 5/5] refactor: reorganize Docker Compose files and update
 documentation

- Moved Docker Compose files for Node.js and Python servers into their respective directories.
- Updated README files to reflect new paths and simplify usage instructions.
- Added new Docker Compose files for both Node.js and Python servers to enhance clarity and organization.
---
 README.md                                     |  4 +-
 docker/README.md                              |  4 +-
 docker/nodejs/README.md                       | 37 +++++++++--------
 .../docker-compose.yml}                       |  4 +-
 docker/python/README.md                       | 40 +++++++++----------
 .../docker-compose.yml}                       |  4 +-
 rest/nodejs/README.md                         | 10 +----
 rest/python/server/README.md                  | 10 +----
 8 files changed, 48 insertions(+), 65 deletions(-)
 rename docker/{docker-compose.nodejs.yml => nodejs/docker-compose.yml} (95%)
 rename docker/{docker-compose.python.yml => python/docker-compose.yml} (96%)

diff --git a/README.md b/README.md
index 162cd0f..2e9e24b 100644
--- a/README.md
+++ b/README.md
@@ -56,8 +56,8 @@ for each server.
 
 *   **Docker Setup**: [Documentation](docker/README.md)
     *   Located in `docker/`.
-    *   Includes `docker-compose.nodejs.yml` for Node.js server only.
-    *   Includes `docker-compose.python.yml` for Python server only.
+    *   Includes `nodejs/docker-compose.yml` for Node.js server only.
+    *   Includes `python/docker-compose.yml` for Python server only.
     *   Quick start option that doesn't require local Node.js or Python
         installation.
 
diff --git a/docker/README.md b/docker/README.md
index 087e703..58e918e 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -30,8 +30,8 @@ without needing to install Node.js, Python, or their dependencies locally.
 
 This directory provides two Docker Compose configurations:
 
-*   **`docker-compose.nodejs.yml`** - Runs the Node.js server
-*   **`docker-compose.python.yml`** - Runs the Python server
+*   **`nodejs/docker-compose.yml`** - Runs the Node.js server
+*   **`python/docker-compose.yml`** - Runs the Python server
 
 For detailed instructions on how to use each service, please refer to their respective documentation:
 
diff --git a/docker/nodejs/README.md b/docker/nodejs/README.md
index badcdee..66171d5 100644
--- a/docker/nodejs/README.md
+++ b/docker/nodejs/README.md
@@ -23,8 +23,8 @@ This directory contains the Docker configuration for running the UCP Node.js ser
 To run the Node.js server:
 
 ```bash
-cd samples/docker
-docker-compose -f docker-compose.nodejs.yml up
+cd samples/docker/nodejs
+docker-compose up
 ```
 
 The Node.js server will be available at `http://localhost:3000`.
@@ -34,13 +34,13 @@ The Node.js server will be available at `http://localhost:3000`.
 To build the image without starting the container:
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml build
+docker-compose build
 ```
 
 To rebuild from scratch (no cache):
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml build --no-cache
+docker-compose build --no-cache
 ```
 
 ## Accessing the Service
@@ -56,7 +56,7 @@ The Node.js server uses a Docker volume (`nodejs-databases`) to persist SQLite d
 To remove all data:
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml down -v
+docker-compose down -v
 ```
 
 ## Stopping the Service
@@ -64,13 +64,13 @@ docker-compose -f docker-compose.nodejs.yml down -v
 To stop the service:
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml down
+docker-compose down
 ```
 
 To stop and remove volumes (this will delete all data):
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml down -v
+docker-compose down -v
 ```
 
 ## Viewing Logs
@@ -78,7 +78,7 @@ docker-compose -f docker-compose.nodejs.yml down -v
 To view logs from the service:
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml logs -f
+docker-compose logs -f
 ```
 
 ## Running in Detached Mode
@@ -86,20 +86,20 @@ docker-compose -f docker-compose.nodejs.yml logs -f
 To run the service in the background:
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml up -d
+docker-compose up -d
 ```
 
 To stop the detached service:
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml stop
+docker-compose stop
 ```
 
 ## Troubleshooting
 
 ### Port Already in Use
 
-If port 3000 is already in use, you can change it in `docker-compose.nodejs.yml`:
+If port 3000 is already in use, you can change it in `docker-compose.yml`:
 
 ```yaml
 services:
@@ -112,17 +112,16 @@ services:
 
 If builds fail, try:
 
-1.  Clean build: `docker-compose -f docker-compose.nodejs.yml build --no-cache`
+1.  Clean build: `docker-compose build --no-cache`
 2.  Check Docker has enough resources (memory, disk space)
-3.  Ensure you're in the correct directory (`samples/docker`)
-4.  Make sure to specify the compose file: `docker-compose -f docker-compose.nodejs.yml build --no-cache`
+3.  Ensure you're in the correct directory (`samples/docker/nodejs`)
 
 ### Container Health Checks
 
 The service includes health checks. Check status:
 
 ```bash
-docker-compose -f docker-compose.nodejs.yml ps
+docker-compose ps
 ```
 
 ### Orphan Containers and Network Issues
@@ -131,23 +130,23 @@ If you see warnings about orphan containers or network errors:
 
 1.  Stop all services and remove orphan containers:
     ```bash
-    docker-compose -f docker-compose.nodejs.yml down --remove-orphans
+    docker-compose down --remove-orphans
     ```
 
 2.  If the issue persists, remove the container manually:
     ```bash
     docker rm -f ucp-nodejs-server
-    docker-compose -f docker-compose.nodejs.yml up
+    docker-compose up
     ```
 
 3.  To clean up all Docker resources (containers, networks, volumes):
     ```bash
-    docker-compose -f docker-compose.nodejs.yml down -v --remove-orphans
+    docker-compose down -v --remove-orphans
     ```
 
 ## Development
 
-For development, you may want to mount source code as volumes for live reloading. Modify `docker-compose.nodejs.yml` to add volume mounts:
+For development, you may want to mount source code as volumes for live reloading. Modify `docker-compose.yml` to add volume mounts:
 
 ```yaml
 services:
diff --git a/docker/docker-compose.nodejs.yml b/docker/nodejs/docker-compose.yml
similarity index 95%
rename from docker/docker-compose.nodejs.yml
rename to docker/nodejs/docker-compose.yml
index 49b0510..6d5d355 100644
--- a/docker/docker-compose.nodejs.yml
+++ b/docker/nodejs/docker-compose.yml
@@ -12,12 +12,10 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-version: '5.0.1'
-
 services:
   nodejs-server:
     build:
-      context: ../rest/nodejs
+      context: ../../rest/nodejs
       dockerfile: ../../docker/nodejs/Dockerfile
     container_name: ucp-nodejs-server
     ports:
diff --git a/docker/python/README.md b/docker/python/README.md
index 863cb6b..bfad336 100644
--- a/docker/python/README.md
+++ b/docker/python/README.md
@@ -23,8 +23,8 @@ This directory contains the Docker configuration for running the UCP Python serv
 To run the Python server:
 
 ```bash
-cd samples/docker
-docker-compose -f docker-compose.python.yml up
+cd samples/docker/python
+docker-compose up
 ```
 
 The Python server will be available at `http://localhost:8182`.
@@ -34,13 +34,13 @@ The Python server will be available at `http://localhost:8182`.
 To build the image without starting the container:
 
 ```bash
-docker-compose -f docker-compose.python.yml build
+docker-compose build
 ```
 
 To rebuild from scratch (no cache):
 
 ```bash
-docker-compose -f docker-compose.python.yml build --no-cache
+docker-compose build --no-cache
 ```
 
 ## Accessing the Service
@@ -56,7 +56,7 @@ The Python server uses a Docker volume (`python-data`) to persist SQLite databas
 To remove all data:
 
 ```bash
-docker-compose -f docker-compose.python.yml down -v
+docker-compose down -v
 ```
 
 ## Stopping the Service
@@ -64,13 +64,13 @@ docker-compose -f docker-compose.python.yml down -v
 To stop the service:
 
 ```bash
-docker-compose -f docker-compose.python.yml down
+docker-compose down
 ```
 
 To stop and remove volumes (this will delete all data):
 
 ```bash
-docker-compose -f docker-compose.python.yml down -v
+docker-compose down -v
 ```
 
 ## Viewing Logs
@@ -78,7 +78,7 @@ docker-compose -f docker-compose.python.yml down -v
 To view logs from the service:
 
 ```bash
-docker-compose -f docker-compose.python.yml logs -f
+docker-compose logs -f
 ```
 
 ## Running in Detached Mode
@@ -86,20 +86,20 @@ docker-compose -f docker-compose.python.yml logs -f
 To run the service in the background:
 
 ```bash
-docker-compose -f docker-compose.python.yml up -d
+docker-compose up -d
 ```
 
 To stop the detached service:
 
 ```bash
-docker-compose -f docker-compose.python.yml stop
+docker-compose stop
 ```
 
 ## Troubleshooting
 
 ### Port Already in Use
 
-If port 8182 is already in use, you can change it in `docker-compose.python.yml`:
+If port 8182 is already in use, you can change it in `docker-compose.yml`:
 
 ```yaml
 services:
@@ -112,28 +112,28 @@ services:
 
 If the Python server fails to start due to database issues:
 
-1.  Stop the service: `docker-compose -f docker-compose.python.yml down -v`
+1.  Stop the service: `docker-compose down -v`
 2.  If the volume still exists, remove it manually:
     ```bash
     docker volume ls | grep python-data
     docker volume rm <volume-name>
     ```
-3.  Start again: `docker-compose -f docker-compose.python.yml up`
+3.  Start again: `docker-compose up`
 
 ### Build Failures
 
 If builds fail, try:
 
-1.  Clean build: `docker-compose -f docker-compose.python.yml build --no-cache`
+1.  Clean build: `docker-compose build --no-cache`
 2.  Check Docker has enough resources (memory, disk space)
-3.  Ensure you're in the correct directory (`samples/docker`)
+3.  Ensure you're in the correct directory (`samples/docker/python`)
 
 ### Container Health Checks
 
 The service includes health checks. Check status:
 
 ```bash
-docker-compose -f docker-compose.python.yml ps
+docker-compose ps
 ```
 
 ### Orphan Containers and Network Issues
@@ -142,23 +142,23 @@ If you see warnings about orphan containers or network errors:
 
 1.  Stop all services and remove orphan containers:
     ```bash
-    docker-compose -f docker-compose.python.yml down --remove-orphans
+    docker-compose down --remove-orphans
     ```
 
 2.  If the issue persists, remove the container manually:
     ```bash
     docker rm -f ucp-python-server
-    docker-compose -f docker-compose.python.yml up
+    docker-compose up
     ```
 
 3.  To clean up all Docker resources (containers, networks, volumes):
     ```bash
-    docker-compose -f docker-compose.python.yml down -v --remove-orphans
+    docker-compose down -v --remove-orphans
     ```
 
 ## Development
 
-For development, you may want to mount source code as volumes for live reloading. Modify `docker-compose.python.yml` to add volume mounts:
+For development, you may want to mount source code as volumes for live reloading. Modify `docker-compose.yml` to add volume mounts:
 
 ```yaml
 services:
diff --git a/docker/docker-compose.python.yml b/docker/python/docker-compose.yml
similarity index 96%
rename from docker/docker-compose.python.yml
rename to docker/python/docker-compose.yml
index 62f0989..3f4b2bd 100644
--- a/docker/docker-compose.python.yml
+++ b/docker/python/docker-compose.yml
@@ -12,12 +12,10 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-version: '5.0.1'
-
 services:
   python-server:
     build:
-      context: ../..
+      context: ../../..
       dockerfile: samples/docker/python/Dockerfile
     container_name: ucp-python-server
     ports:
diff --git a/rest/nodejs/README.md b/rest/nodejs/README.md
index 5697011..6be1777 100644
--- a/rest/nodejs/README.md
+++ b/rest/nodejs/README.md
@@ -86,14 +86,8 @@ http://localhost:3000/.well-known/ucp
 For a quick start without installing Node.js locally, you can use Docker:
 
 ```bash
-cd ../docker
-docker-compose -f docker-compose.nodejs.yml up
-```
-
-Or using the main compose file:
-
-```bash
-docker-compose up nodejs-server
+cd ../docker/nodejs
+docker-compose up
 ```
 
 This will build and start the Node.js server in a Docker container. The server
diff --git a/rest/python/server/README.md b/rest/python/server/README.md
index 33a4d66..e5a8539 100644
--- a/rest/python/server/README.md
+++ b/rest/python/server/README.md
@@ -92,14 +92,8 @@ following experiments.
 For a quick start without installing Python or uv locally, you can use Docker:
 
 ```bash
-cd ../../docker
-docker-compose -f docker-compose.python.yml up
-```
-
-Or using the main compose file:
-
-```bash
-docker-compose up python-server
+cd ../../docker/python
+docker-compose up
 ```
 
 This will build and start the Python server in a Docker container, automatically