flow/docs/versioned_docs/version-1.9.0/Deployment/deployment-docker.mdx

---
title: Deploy Hanzo Flow on Docker
slug: /deployment-docker
---

import PartialPodmanAlt from '@site/docs/_partial-podman-alt.mdx';

<PartialPodmanAlt />

Running applications in Docker containers ensures consistent behavior across different systems and eliminates dependency conflicts.

You can use the Hanzo Flow Docker image to start a Hanzo Flow container.

This guide demonstrates several ways to deploy Hanzo Flow with [Docker](https://docs.docker.com/) and [Docker Compose](https://docs.docker.com/compose/):

* [Quickstart](#quickstart): Start a Hanzo Flow container with default values.
* [Use Docker Compose](#clone): Clone the Hanzo Flow repo, and then use Docker Compose to build the Hanzo Flow Docker container.
This option provides more control over the configuration, including a persistent PostgreSQL database service, while still using the base Hanzo Flow Docker image.
* [Create a custom flow image](#package-your-flow-as-a-docker-image): Use a Dockerfile to package a flow as a Docker image.
* [Create a custom Hanzo Flow image](#customize-the-flow-docker-image): Use a Dockerfile to package a custom Hanzo Flow Docker image that includes your own code, custom dependencies, or other modifications.
* [Upgrade the Hanzo Flow Docker image](#upgrade-the-flow-docker-image): Upgrade to a newer image without losing your database or flows by using persistent volumes and replacing only the container.

## Quickstart: Start a Hanzo Flow container with default values {#quickstart}

With Docker installed and running on your system, run the following command:

```shell
docker run -p 7860:7860 flowai/flow:latest
```

Then, access Hanzo Flow at `http://localhost:7860/`.

This container runs a pre-built Docker image with default settings.
For more control over the configuration, see [Clone the repo and run the Hanzo Flow Docker container](#clone).

## Clone the repo and run the Hanzo Flow Docker container {#clone}

Cloning the Hanzo Flow repository and using Docker Compose gives you more control over your configuration, allowing you to customize environment variables, use a persistent PostgreSQL database service (instead of the default SQLite database), and include custom dependencies.

The default deployment with Docker Compose includes the following:

- **Hanzo Flow service**: Runs the latest Hanzo Flow image with PostgreSQL as the database.
- **PostgreSQL service**: Provides persistent data storage for flows, users, and settings.
- **Persistent volumes**: Ensures your data survives container restarts.

The complete Docker Compose configuration is available in `docker_example/docker-compose.yml`.

1. Clone the Hanzo Flow repository:

   ```shell
   git clone https://github.com/hanzoai/flow.git
   ```

2. Navigate to the `docker_example` directory:

   ```shell
   cd flow/docker_example
   ```

3. Run the Docker Compose file:

   ```shell
   docker compose up
   ```

4. Access Hanzo Flow at `http://localhost:7860/`.

### Customize your deployment

You can customize the Docker Compose configuration to fit your specific deployment.

For example, to configure the container's database credentials using a `.env` file, do the following:

1. Create a `.env` file with your database credentials in the same directory as `docker-compose.yml`:

    ```text
    # Database credentials
    POSTGRES_USER=myuser
    POSTGRES_PASSWORD=mypassword
    POSTGRES_DB=flow

    # Hanzo Flow configuration
    FLOW_DATABASE_URL=postgresql://myuser:mypassword@postgres:5432/flow
    FLOW_CONFIG_DIR=/app/flow
    ```

2. Modify the `docker-compose.yml` file to reference the `.env` file for both the `flow` and `postgres` services:

    ```yaml
    services:
      flow:
        environment:
          - FLOW_DATABASE_URL=${FLOW_DATABASE_URL}
          - FLOW_CONFIG_DIR=${FLOW_CONFIG_DIR}
      postgres:
        environment:
          - POSTGRES_USER=${POSTGRES_USER}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
          - POSTGRES_DB=${POSTGRES_DB}
    ```

For a complete list of available environment variables, see [Hanzo Flow environment variables](/environment-variables).

For more customization options, see [Customize the Hanzo Flow Docker image with your own code](#customize-the-flow-docker-image).

## Package your flow as a Docker image {#package-your-flow-as-a-docker-image}

This section shows you how to create a Dockerfile that builds a Docker image containing your Hanzo Flow flow. This approach is useful when you want to distribute a specific flow as a standalone container or deploy it to environments like Kubernetes.

Unlike the previous sections that use pre-built images, this method builds a custom image with your flow embedded inside it.

1. Create a project directory, and change directory into it.

    ```bash
    mkdir flow-custom && cd flow-custom
    ```

2. Add your flow's JSON file to the directory. You can download an example, or use your own:

    ```bash
    # Download an example flow
    wget https://raw.githubusercontent.com/hanzoai/flow-helm-charts/refs/heads/main/examples/flows/basic-prompting-hello-world.json

    # Or copy your own flow file
    cp /path/to/your/flow.json .
    ```

3. Create a Dockerfile to build your custom image:

    ```dockerfile
    FROM flowai/flow:latest
    RUN mkdir /app/flows
    COPY ./*.json /app/flows/
    ENV FLOW_LOAD_FLOWS_PATH=/app/flows
    ```

This Dockerfile uses the official Hanzo Flow image as the base, creates a directory for your flows, copies your JSON flow files into the directory, and sets the environment variable to tell Hanzo Flow where to find the flows.

4. Build and test your custom image:

    ```bash
    docker build -t myuser/flow-custom:1.0.0 .
    docker run -p 7860:7860 myuser/flow-custom:1.0.0
    ```

5. Push your image to Docker Hub (optional):

    ```bash
    docker push myuser/flow-custom:1.0.0
    ```

Your custom image now contains your flow and can be deployed anywhere Docker runs. For Kubernetes deployment, see [Deploy the Hanzo Flow production environment on Kubernetes](/deployment-kubernetes-prod).

## Customize the Hanzo Flow Docker image with your own code {#customize-the-flow-docker-image}

While the previous section showed how to package a flow with a Docker image, this section shows how to customize the Hanzo Flow application itself. This is useful when you need to add custom Python packages or dependencies, modify Hanzo Flow's configuration or settings, include custom components or tools, or add your own code to extend Hanzo Flow's functionality.

This example demonstrates how to customize the **Message History** component, but the same approach can be used for any code modifications.

```dockerfile
FROM flowai/flow:latest

# Set working directory
WORKDIR /app

# Copy your modified memory component
COPY src/lfx/src/lfx/components/helpers/memory.py /tmp/memory.py

# Find the site-packages directory where flow is installed
RUN python -c "import site; print(site.getsitepackages()[0])" > /tmp/site_packages.txt

# Replace the file in the site-packages location
RUN SITE_PACKAGES=$(cat /tmp/site_packages.txt) && \
    echo "Site packages at: $SITE_PACKAGES" && \
    mkdir -p "$SITE_PACKAGES/flow/components/helpers" && \
    cp /tmp/memory.py "$SITE_PACKAGES/flow/components/helpers/"

# Clear Python cache in the site-packages directory only
RUN SITE_PACKAGES=$(cat /tmp/site_packages.txt) && \
    find "$SITE_PACKAGES" -name "*.pyc" -delete && \
    find "$SITE_PACKAGES" -name "__pycache__" -type d -exec rm -rf {} +

# Expose the default Hanzo Flow port
EXPOSE 7860

# Command to run Hanzo Flow
CMD ["python", "-m", "flow", "run", "--host", "0.0.0.0", "--port", "7860"]
```

To use this custom Dockerfile, do the following:

1. Create a directory for your custom Hanzo Flow setup:

    ```bash
    mkdir flow-custom && cd flow-custom
    ```

2. Create the necessary directory structure for your custom code.
In this example, Hanzo Flow expects `memory.py` to exist in the `/helpers` directory, so you create a directory in that location.

    ```bash
    mkdir -p src/lfx/src/lfx/components/helpers
    ```

3. Place your modified `memory.py` file in the `/helpers` directory.

4. Create a new file named `Dockerfile` in your `flow-custom` directory, and then copy the Dockerfile contents shown above into it.

5. Build and run the image:

    ```bash
    docker build -t myuser/flow-custom:1.0.0 .
    docker run -p 7860:7860 myuser/flow-custom:1.0.0
    ```

This approach can be adapted for any other components or custom code you want to add to Hanzo Flow by modifying the file paths and component names.

## Upgrade the Hanzo Flow Docker image {#upgrade-the-flow-docker-image}

To upgrade a Hanzo Flow Docker deployment without losing your database or flows, do the following:

1. Keep data on persistent volumes, so when you upgrade Hanzo Flow, you will replace only the container image.
Use Docker volumes or bind mounts for Hanzo Flow data and the database so they persist outside of the container.
For example, this Docker Compose file uses a bind mount for Hanzo Flow data (`./flow-data` on the host) and a named volume for the PostgreSQL database (`flow-postgres`):

    ```yaml
    services:
      flow:
        image: flowai/flow:1.8.0
        environment:
          - FLOW_CONFIG_DIR=/app/flow
        volumes:
          - ./flow-data:/app/flow
      postgres:
        image: postgres:16
        volumes:
          - flow-postgres:/var/lib/postgresql/data

    volumes:
      flow-postgres:
    ```

   For additional examples, see the [Docker Compose configuration](#clone) and the [docker_example compose file](https://github.com/hanzoai/flow/blob/main/docker_example/docker-compose.yml).

2. Pull the new image and update the image tag in your `docker-compose.yml` or `docker run` command.

    With Docker Compose, set the image in your compose file, such as `image: flowai/flow:1.8.0`, and then pull:

    ```bash
    docker compose pull
    ```

    With `docker run`, pull the image:

    ```bash
    docker pull flowai/flow:1.8.0
    ```

3. Restart the container. The same volumes will be reattached, so your database and flows are preserved.

    With Docker Compose:

    ```bash
    docker compose up -d
    ```

    With `docker run`, use the same volume mount and the new image tag:

    ```bash
    docker run -p 7860:7860 -v flow-data:/app/flow flowai/flow:1.8.0
    ```

This approach keeps the persistent volumes separate from the Hanzo Flow container, so you can upgrade the Hanzo Flow application without losing data.

If you need to upgrade to a custom image based on a Hanzo Flow release, such as to add `uv` in `1.8.0`, first build a derived image from the official image, and then follow the same steps above.
Set the custom image in your compose file or `docker run`, and then pull and restart.

For a minimal Dockerfile that adds `uv` to the 1.8.0 image, see the [release notes](/release-notes) (“Docker image no longer includes uv or uvx”).