Skip to content

Quick Start with Docker Compose

To quickly get started with Hayhooks, we provide a ready-to-use Docker Compose 🐳 setup with pre-configured integration with Open WebUI.

It's available in the Hayhooks + Open WebUI Docker Compose repository.

Setup Instructions

1. Clone the Repository

git clone https://github.com/deepset-ai/hayhooks-open-webui-docker-compose.git
cd hayhooks-open-webui-docker-compose

2. Start the Services

Set the model API key before starting the containers:

export OPENAI_API_KEY="your-openai-api-key"
docker compose up --build -d

This will start:

  • Hayhooks server on port 1416
  • Open WebUI on port 3000

3. Access the Services

The repository auto-deploys chat_with_website_streaming at startup. The Compose file starts only the HTTP server; MCP requires a separate server.

4. Deploy Example Pipelines

Install Hayhooks locally to use the CLI:

pip install hayhooks

Then deploy example pipelines:

# Deploy a sample pipeline
hayhooks pipeline deploy-files -n chat_with_website --overwrite pipelines/chat_with_website_streaming

Alternative: Deploy via API

You can also deploy pipelines using the HTTP API endpoints: POST /deploy_files (PipelineWrapper files) or POST /deploy-yaml (YAML pipeline definition). See the API Reference for details.

Configuration Options

Environment Variables

The following environment variables can be configured in .env:

Variable Description Default
OPEN_WEBUI_PORT Port for Open WebUI 3000
WEBUI_DOCKER_TAG Tag for Open WebUI image main

Volume Mounts

The Docker Compose setup includes the following volume mounts:

  • Pipeline Directory: /pipelines – Directory mounted inside the Hayhooks container where your pipeline wrappers or YAML files live. Hayhooks auto-deploys anything it finds here at startup.

Integrating with Open WebUI

The Docker Compose setup comes pre-configured to integrate Hayhooks with Open WebUI:

1. Configure Open WebUI

  1. Access Open WebUI at http://localhost:3000
  2. Go to Settings → Connections
  3. Add a new connection with:
  4. API Base URL: http://hayhooks:1416/v1
  5. API Key: any-value (not used by Hayhooks)

2. Deploy a Pipeline

Deploy a pipeline that supports chat completion:

hayhooks pipeline deploy-files -n chat_with_website --overwrite pipelines/chat_with_website_streaming

Alternatively, use the API endpoints (POST /deploy_files or POST /deploy-yaml).

3. Test the Integration

  1. In Open WebUI, select the Hayhooks backend
  2. Start a conversation with your deployed pipeline
  3. The pipeline will respond through the Open WebUI interface

Troubleshooting

Common Issues

  1. Port Conflicts: Ensure ports 1416 and 3000 are available
  2. Permission Issues: Make sure Docker has proper permissions
  3. Network Issues: Check that containers can communicate with each other

Logs

Check logs for troubleshooting:

# Hayhooks logs
docker compose logs -f hayhooks

# Open WebUI logs
docker compose logs -f open-webui

Cleanup

To stop and remove the containers while preserving Open WebUI data:

docker compose down

Next Steps