Docker Compose is a tool used to define and run multiple Docker containers as a single application stack. A RAG application may contain multiple components such as:

FastAPI application
FAISS vector index
Embedding model
Database
LLM service

Docker Compose manages these services using a single YAML configuration file.

docker compose up

This command can build and start the entire application stack.

1. Why Docker Compose?

A single Docker container can be started using:

docker run

However, applications often require multiple containers. Example:

FastAPI Application
        │
        ▼
Vector Store
        │
        ▼
Persistent Storage

Managing every container manually becomes difficult. Docker Compose simplifies this process.

docker compose up

Docker Compose can:

Build images
Create containers
Create networks
Create volumes
Manage dependencies
Start multiple services together

2. What is a Multi-Service Stack?

A multi-service stack is an application consisting of multiple services running independently. Example:

                 Docker Compose

        ┌──────────────────────────┐
        │                          │
        │    FastAPI Container     │
        │                          │
        └────────────┬─────────────┘
                     │
                     ▼
              Shared Volume
                     ▲
                     │
        ┌────────────┴─────────────┐
        │                          │
        │  FAISS Index Container   │
        │                          │
        └──────────────────────────┘

Each service has a specific responsibility.

Service	Responsibility
FastAPI	Handles API requests
Vector Store	Builds the FAISS index
Volume	Stores shared index data

3. What is Docker Compose?

Docker Compose uses a YAML configuration file. Common filenames:

docker-compose.yml

or:

compose.yaml

The file can define:

Services
Images
Build instructions
Ports
Volumes
Networks
Environment variables
Dependencies
Health checks

Basic structure:

services:

  service_name:
    build: .

4. Main Docker Compose Concepts

4.1 Services

A service represents an application component. Example:

services:

  api:
    build: ./api

  vector_store:
    build: ./vector_store

This creates two services:

services
│
├── api
│
└── vector_store

Each service can have its own:

Dockerfile
Dependencies
Ports
Environment variables
Volumes

4.2 Build

The build instruction tells Docker Compose how to build an image.

build:
  context: ./api

The context points to the directory containing the application files. Example:

api/
├── Dockerfile
├── requirements.txt
└── llm_api.py

Flow:

Source Code
    ↓
Dockerfile
    ↓
Docker Image
    ↓
Docker Container

4.3 Port Mapping

Ports expose a container application to the host machine. Example:

ports:
  - "8000:8000"

Format:

HOST_PORT:CONTAINER_PORT

Architecture:

Browser
   │
   ▼
localhost:8000
   │
   ▼
Host Port 8000
   │
   ▼
Container Port 8000
   │
   ▼
FastAPI Application

5. Docker Volumes

Containers are temporary. Data stored inside a container can be lost when the container is removed. Docker volumes provide persistent storage. Example:

volumes:
  vector_data:

This creates a named volume:

vector_data

5.1 Shared Volumes

A shared volume allows multiple containers to access the same data. Example:

services:

  api:
    volumes:
      - vector_data:/vector_data

  vector_store:
    volumes:
      - vector_data:/vector_data


volumes:
  vector_data:

Architecture:

FAISS Container
      │
      │ Write
      ▼
Shared Docker Volume
/vector_data
      │
      │ Read
      ▼
FastAPI Container

The FAISS index can be stored as:

/vector_data/faiss.index

6. `depends_on`

The depends_on instruction defines service dependencies. Example:

api:
  depends_on:
    vector_store:
      condition: service_completed_successfully

This means:

Vector Store Starts
        ↓
Build FAISS Index
        ↓
Save Index
        ↓
Completes Successfully
        ↓
FastAPI Starts

This is useful when the API requires the FAISS index before starting.

7. Docker Compose Networking

Docker Compose automatically creates a network for services. Example:

Docker Compose Network
│
├── API Container
│
└── Database Container

Containers can communicate using service names. Example:

api
 │
 │ communicates with
 ▼
database

The service name acts as a hostname. Example:

http://database:5432

8. Environment Variables

Environment variables store configuration values. Example:

api:
  environment:
    APP_ENV: production
    VECTOR_PATH: /vector_data/faiss.index

Python can access them using:

import os

environment = os.getenv("APP_ENV")

vector_path = os.getenv("VECTOR_PATH")

Useful for:

API keys
Database URLs
Application configuration
Model names
File paths

Sensitive values should not be hardcoded in source code.

9. Restart Policies

Docker Compose can automatically restart containers. Example:

api:
  restart: unless-stopped

Common policies:

Policy	Description
`no`	No automatic restart
`always`	Always restart
`on-failure`	Restart when a failure occurs
`unless-stopped`	Restart unless manually stopped

10. Health Checks

Health checks monitor whether a container is functioning correctly. Example:

healthcheck:
  test:
    [
      "CMD",
      "python",
      "-c",
      "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
    ]
  interval: 30s
  timeout: 10s
  retries: 3

Possible states:

starting
   ↓
healthy

or:

starting
   ↓
unhealthy

11. FastAPI + FAISS Architecture

This example contains two services.

Service 1: FastAPI

Responsible for:

Receiving HTTP requests
Loading the FAISS index
Providing API endpoints

Service 2: Vector Store

Responsible for:

Loading documents
Creating embeddings
Creating a FAISS index
Saving the index

Shared Volume

Responsible for:

Storing the FAISS index
Sharing the index between containers

Architecture:

                 Docker Compose

       ┌───────────────────────────────┐
       │                               │
       │      Vector Store Service     │
       │                               │
       │   Documents → Embeddings      │
       │            ↓                  │
       │         FAISS Index           │
       │            ↓                  │
       │      Shared Docker Volume     │
       │            ↓                  │
       │       FastAPI Service         │
       │            ↓                  │
       │        Load FAISS Index       │
       │            ↓                  │
       │         API Endpoints         │
       │                               │
       └───────────────────────────────┘

12. Important Note About FAISS

FAISS is a vector similarity search library. It is not typically used as a standalone database server. For this Docker Compose example, the architecture is:

Vector Store Container
        ↓
Creates FAISS Index
        ↓
Writes Index File
        ↓
Shared Docker Volume
        ↓
FastAPI Container
        ↓
Reads FAISS Index

This architecture is useful for learning:

Docker Compose
Multi-container applications
Shared volumes
Service dependencies

13. Project Structure

FastAPI Deployment/
│
├── docker-compose.yml
│
├── api/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── llm_api.py
│
└── vector_store/
    ├── Dockerfile
    ├── requirements.txt
    └── build_index.py

14. Example: FastAPI Application

`api/llm_api.py`

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def home():
    return {
        "message": "LLM API is running"
    }


@app.get("/health")
def health():
    return {
        "status": "healthy"
    }

Explanation

from fastapi import FastAPI

Imports the FastAPI framework.

app = FastAPI()

Creates the FastAPI application.

@app.get("/")

Creates a GET endpoint for the root URL.

@app.get("/health")

Creates a health-check endpoint. Endpoints:

GET /
GET /health

15. API Requirements

`api/requirements.txt`

fastapi
uvicorn
faiss-cpu

Explanation

Package	Purpose
`fastapi`	Builds the API
`uvicorn`	Runs the FastAPI server
`faiss-cpu`	Loads and searches the FAISS index

16. API Dockerfile

`api/Dockerfile`

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "llm_api:app", "--host", "0.0.0.0", "--port", "8000"]

Step-by-Step Explanation

Base Image

FROM python:3.11-slim

Uses Python 3.11 as the base image.

Working Directory

WORKDIR /app

Sets /app as the working directory.

Copy Requirements

COPY requirements.txt .

Copies the dependency file.

Install Dependencies

RUN pip install --no-cache-dir -r requirements.txt

Installs required Python packages.

Copy Application

COPY . .

Copies the application files.

Expose Port

EXPOSE 8000

Documents that the application uses port 8000.

Start Application

CMD ["uvicorn", "llm_api:app", "--host", "0.0.0.0", "--port", "8000"]

Starts the FastAPI server.

17. Example: FAISS Index Builder

`vector_store/build_index.py`

import os

import faiss

from sentence_transformers import SentenceTransformer


documents = [
    "FAISS performs efficient similarity search.",
    "FastAPI is used to build Python APIs.",
    "Docker packages applications into containers.",
    "RAG retrieves relevant documents before generating answers.",
    "Embeddings convert text into numerical vectors.",
]


model = SentenceTransformer(
    "all-MiniLM-L6-v2"
)


embeddings = model.encode(
    documents,
    normalize_embeddings=True
)


dimension = embeddings.shape[1]


index = faiss.IndexFlatIP(
    dimension
)


index.add(
    embeddings
)


os.makedirs(
    "/vector_data",
    exist_ok=True
)


faiss.write_index(
    index,
    "/vector_data/faiss.index"
)


print(
    "FAISS index created successfully"
)

print(
    "Number of vectors:",
    index.ntotal
)

Step 1: Import Libraries

import os

import faiss

from sentence_transformers import SentenceTransformer

os handles directories
faiss creates the vector index
SentenceTransformer creates embeddings

Step 2: Create Documents

documents = [
    "FAISS performs efficient similarity search.",
    "FastAPI is used to build Python APIs.",
    "Docker packages applications into containers.",
]

Documents represent the knowledge source.

Step 3: Load Embedding Model

model = SentenceTransformer(
    "all-MiniLM-L6-v2"
)

The model converts text into numerical vectors.

Text
 ↓
Embedding Model
 ↓
Vector

Step 4: Create Embeddings

embeddings = model.encode(
    documents,
    normalize_embeddings=True
)

Each document becomes a vector.

Document 1 → [0.12, -0.34, 0.56, ...]
Document 2 → [0.45, 0.21, -0.12, ...]
Document 3 → [0.67, -0.45, 0.32, ...]

Step 5: Get Vector Dimension

dimension = embeddings.shape[1]

Gets the number of values in each embedding.

Step 6: Create FAISS Index

index = faiss.IndexFlatIP(
    dimension
)

Creates a FAISS similarity index. IndexFlatIP performs inner-product similarity search. Because embeddings are normalized:

Inner Product ≈ Cosine Similarity

Step 7: Add Embeddings

index.add(
    embeddings
)

Stores embeddings inside the FAISS index.

Step 8: Create Directory

os.makedirs(
    "/vector_data",
    exist_ok=True
)

Creates the directory used for storing the FAISS index.

Step 9: Save FAISS Index

faiss.write_index(
    index,
    "/vector_data/faiss.index"
)

Saves the vector index. The resulting file:

/vector_data/faiss.index

This file will be stored inside the shared Docker volume.

18. Vector Store Requirements

`vector_store/requirements.txt`

faiss-cpu
sentence-transformers

Package	Purpose
`faiss-cpu`	Vector similarity search
`sentence-transformers`	Generates embeddings

19. Vector Store Dockerfile

`vector_store/Dockerfile`

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY build_index.py .

CMD ["python", "build_index.py"]

Flow:

Start Container
      ↓
Run build_index.py
      ↓
Create Embeddings
      ↓
Create FAISS Index
      ↓
Save to /vector_data
      ↓
Container Completes

20. Complete Docker Compose File

`docker-compose.yml`

services:

  api:
    build:
      context: ./api

    container_name: llm-api

    ports:
      - "8000:8000"

    volumes:
      - vector_data:/vector_data

    depends_on:
      vector_store:
        condition: service_completed_successfully


  vector_store:
    build:
      context: ./vector_store

    container_name: faiss-index

    volumes:
      - vector_data:/vector_data


volumes:

  vector_data:

21. Understanding the Docker Compose File

API Service

api:

Defines the FastAPI service.

Build Context

build:
  context: ./api

Builds the API image using:

api/
├── Dockerfile
├── requirements.txt
└── llm_api.py

Container Name

container_name: llm-api

Assigns a custom name to the API container.

Port Mapping

ports:
  - "8000:8000"

Maps:

Host Port 8000
       ↓
Container Port 8000
       ↓
FastAPI

Volume

volumes:
  - vector_data:/vector_data

Mounts the shared volume. Both services access:

/vector_data

Dependency

depends_on:
  vector_store:
    condition: service_completed_successfully

Ensures the FAISS index builder completes before the API starts.

Vector Store Service

vector_store:
  build:
    context: ./vector_store

Builds the vector store container. Its job is:

Documents
    ↓
Embeddings
    ↓
FAISS Index
    ↓
Save Index
    ↓
Exit

22. Load the FAISS Index in FastAPI

The FastAPI application should load the generated index.

Updated `api/llm_api.py`

import os

import faiss

from fastapi import FastAPI


app = FastAPI()


INDEX_PATH = "/vector_data/faiss.index"


@app.on_event("startup")
def load_vector_index():

    if os.path.exists(INDEX_PATH):

        index = faiss.read_index(
            INDEX_PATH
        )

        print(
            "FAISS index loaded"
        )

        print(
            "Vectors:",
            index.ntotal
        )

    else:

        print(
            "FAISS index not found"
        )


@app.get("/")
def home():

    return {
        "message": "LLM API is running"
    }


@app.get("/health")
def health():

    return {
        "status": "healthy"
    }

Flow:

FastAPI Starts
      ↓
Check Index File
      ↓
Load FAISS Index
      ↓
API Ready

23. Start the Application

Run from the project root:

docker compose up --build

Docker will:

1. Build vector_store image
        ↓
2. Start vector_store container
        ↓
3. Create FAISS index
        ↓
4. Save index to Docker volume
        ↓
5. Complete vector_store container
        ↓
6. Start API container
        ↓
7. Load FAISS index
        ↓
8. FastAPI available on port 8000

Run in Background

docker compose up -d --build

-d means detached mode.

24. Check Running Containers

docker compose ps

Expected:

NAME          STATUS
llm-api       running
faiss-index   exited

The faiss-index container exiting is expected. Its job is only:

Create Index
     ↓
Save Index
     ↓
Exit

25. View Logs

View all logs:

docker compose logs

Follow logs:

docker compose logs -f

View API logs:

docker compose logs api

View vector store logs:

docker compose logs vector_store

26. Test the API

Open:

http://localhost:8000

Expected:

{
    "message": "LLM API is running"
}

Health endpoint:

http://localhost:8000/health

Expected:

{
    "status": "healthy"
}

FastAPI documentation:

http://localhost:8000/docs

27. Docker Compose vs Dockerfile

Dockerfile	Docker Compose
Defines an image	Defines multiple services
Builds one application image	Manages multiple containers
Contains build instructions	Contains stack configuration
Uses Docker instructions	Uses YAML
Example: `FROM`	Example: `services`

Relationship:

Dockerfile
    ↓
Build Image
    ↓
Docker Compose
    ↓
Run Multiple Containers

28. Docker Compose vs `docker run`

Without Docker Compose:

docker build -t vector-store ./vector_store

docker build -t llm-api ./api

docker volume create vector_data

docker run --name faiss-index \
-v vector_data:/vector_data \
vector-store

docker run --name llm-api \
-p 8000:8000 \
-v vector_data:/vector_data \
llm-api

With Docker Compose:

docker compose up --build

Docker Compose stores the infrastructure configuration in one file.

29. Important Docker Compose Commands

Start Services

docker compose up

Build and Start

docker compose up --build

Run in Background

docker compose up -d

Stop Services

docker compose down

Check Services

docker compose ps

View Logs

docker compose logs

Follow Logs

docker compose logs -f

30. Important Concepts Summary

Docker Compose
│
├── Services
│   ├── api
│   └── vector_store
│
├── Build
│   └── Dockerfile
│
├── Ports
│   └── Host → Container
│
├── Volumes
│   ├── Persistent Storage
│   └── Shared Storage
│
├── Networks
│   └── Container Communication
│
├── Dependencies
│   └── depends_on
│
├── Environment Variables
│
├── Health Checks
│
└── Restart Policies

31. Complete Deployment Flow

Source Code
    │
    ├── FastAPI
    │
    └── FAISS Index Builder
             │
             ▼
        Dockerfiles
             │
             ▼
        Docker Images
             │
             ▼
        Docker Compose
             │
      ┌──────┴───────┐
      │              │
      ▼              ▼
FAISS Service    FastAPI Service
      │              │
      │              │
      └──────┬───────┘
             │
             ▼
       Docker Volume
             │
             ▼
        FAISS Index

32. Key Takeaways

Docker Compose manages multiple containers using one configuration file.
Services represent different components of an application.
The build option builds Docker images.
Ports expose applications outside containers.
Volumes provide persistent storage.
Shared volumes allow containers to access common data.
depends_on controls service dependencies.
Docker Compose automatically creates networks.
Environment variables provide configuration.
Health checks monitor container availability.
FastAPI can load a FAISS index stored in a shared Docker volume.
Docker Compose simplifies multi-service deployment.

Final Architecture

                    Docker Compose
                           │
              ┌────────────┴────────────┐
              │                         │
              ▼                         ▼
       Vector Store Service       FastAPI Service
              │                         │
              │ Creates                 │ Reads
              ▼                         ▲
                  Shared Volume
                  /vector_data
                        │
                        ▼
                   FAISS Index

​1. Why Docker Compose?

​2. What is a Multi-Service Stack?

​3. What is Docker Compose?

​4. Main Docker Compose Concepts

​4.1 Services

​4.2 Build

​4.3 Port Mapping

​5. Docker Volumes

​5.1 Shared Volumes

​6. depends_on

​7. Docker Compose Networking

​8. Environment Variables

​9. Restart Policies

​10. Health Checks

​11. FastAPI + FAISS Architecture

​Service 1: FastAPI

​Service 2: Vector Store

​Shared Volume

​12. Important Note About FAISS

​13. Project Structure

​14. Example: FastAPI Application

​api/llm_api.py

​Explanation

​15. API Requirements

​api/requirements.txt

​Explanation

​16. API Dockerfile

​api/Dockerfile

​Step-by-Step Explanation

​Base Image

​Working Directory

​Copy Requirements

​Install Dependencies

​Copy Application

​Expose Port

​Start Application

​17. Example: FAISS Index Builder

​vector_store/build_index.py

​Step 1: Import Libraries

​Step 2: Create Documents

​Step 3: Load Embedding Model

​Step 4: Create Embeddings

​Step 5: Get Vector Dimension

​Step 6: Create FAISS Index

​Step 7: Add Embeddings

​Step 8: Create Directory

​Step 9: Save FAISS Index

​18. Vector Store Requirements

​vector_store/requirements.txt

​19. Vector Store Dockerfile

​vector_store/Dockerfile

​20. Complete Docker Compose File

​docker-compose.yml

​21. Understanding the Docker Compose File

​API Service

​Build Context

​Container Name

​Port Mapping

​Volume

​Dependency

​Vector Store Service

​22. Load the FAISS Index in FastAPI

​Updated api/llm_api.py

​23. Start the Application

​Run in Background

​24. Check Running Containers

​25. View Logs

​26. Test the API

​27. Docker Compose vs Dockerfile

​28. Docker Compose vs docker run

​29. Important Docker Compose Commands

​Start Services

​Build and Start

​Run in Background

​Stop Services

​Check Services

​View Logs

​Follow Logs

​30. Important Concepts Summary

​31. Complete Deployment Flow

1. Why Docker Compose?

2. What is a Multi-Service Stack?

3. What is Docker Compose?

4. Main Docker Compose Concepts

4.1 Services

4.2 Build

4.3 Port Mapping

5. Docker Volumes

5.1 Shared Volumes

6. `depends_on`

7. Docker Compose Networking

8. Environment Variables

9. Restart Policies

10. Health Checks

11. FastAPI + FAISS Architecture

Service 1: FastAPI

Service 2: Vector Store

Shared Volume

12. Important Note About FAISS

13. Project Structure

14. Example: FastAPI Application

`api/llm_api.py`

Explanation

15. API Requirements

`api/requirements.txt`

Explanation

16. API Dockerfile

`api/Dockerfile`

Step-by-Step Explanation

Base Image

Working Directory

Copy Requirements

Install Dependencies

Copy Application

Expose Port

Start Application

17. Example: FAISS Index Builder

`vector_store/build_index.py`

Step 1: Import Libraries

Step 2: Create Documents

Step 3: Load Embedding Model

Step 4: Create Embeddings

Step 5: Get Vector Dimension

Step 6: Create FAISS Index

Step 7: Add Embeddings

Step 8: Create Directory

Step 9: Save FAISS Index

18. Vector Store Requirements

`vector_store/requirements.txt`

19. Vector Store Dockerfile

`vector_store/Dockerfile`

20. Complete Docker Compose File

`docker-compose.yml`

21. Understanding the Docker Compose File

API Service

Build Context

Container Name

Port Mapping

Volume

Dependency

Vector Store Service

22. Load the FAISS Index in FastAPI

Updated `api/llm_api.py`

23. Start the Application

Run in Background

24. Check Running Containers

25. View Logs

26. Test the API

27. Docker Compose vs Dockerfile

28. Docker Compose vs `docker run`

29. Important Docker Compose Commands

Start Services

Build and Start

Run in Background

Stop Services

Check Services

View Logs

Follow Logs

30. Important Concepts Summary

31. Complete Deployment Flow