Skip to main content

Docker Deployment

Ragpi's Docker-based deployment method provides flexibility in where you can host the application. This guide walks through deploying Ragpi using Docker Compose, which can be used across various hosting environments including:

  • Local development environments
  • Virtual Private Servers (VPS) from providers like DigitalOcean, Linode, or Hetzner
  • Cloud compute instances from AWS EC2, Google Compute Engine, or Azure Virtual Machines
  • Dedicated servers or on-premises hardware

The deployment process remains consistent across these environments, making it easy to migrate between platforms as your needs evolve. The only requirements are Docker, Docker Compose, and Git access on your chosen platform.

For production deployments, the bare minimum server requirements are:

  • 1 CPU core
  • 2GB RAM
  • 10GB disk space

These specifications provide enough resources to run all core services comfortably while leaving room for document processing and API operations. Adjust these specifications based on your expected workload and the size of your document collection.

Docker Compose Deployment​

Prerequisites​

  • A server with at least 1 CPU core, 2GB RAM, and 10GB disk space
  • Docker and Docker Compose installed on the server
  • Git installed on the server

Core Deployment Steps​

  1. Clone the repository:
git clone https://github.com/ragpi/ragpi.git
cd ragpi
  1. Copy the example environment file and open it for editing:
cp .env.example .env
  1. Update the .env file with your desired configuration. Refer to the Configuration page to see all available environment variables. At a minimum, you should set the OPENAI_API_KEY variable to your OpenAI API key.
# Required unless using a different chat/embedding provider
OPENAI_API_KEY=your_api_key_here

# Optional: Required if using a GitHub connector
GITHUB_TOKEN=your_github_token

# Optional: Add API authentication
RAGPI_API_KEY=your_secret_api_key
  1. Start the services using Docker Compose:
docker compose -f docker-compose.prod.yml up -d

Core Services​

The following services will be started:

  • Redis (port 6379)
  • PostgreSQL (port 5432)
  • API (port 8000)
  • Task Worker (Celery worker, no exposed ports)
important

By default, all services are configured to only listen on localhost (127.0.0.1) for security. To expose the API service to external traffic, you can either:

  • Add the DOCKER_API_PORT_MAPPING environment variable to the .env file with the value 0.0.0.0:8000:8000 to expose the API service on port 8000. (Not recommended for production)
  • Use a reverse proxy like Nginx, a tunneling service like Cloudflare Tunnel, or a similar method to securely expose the API service. (Recommended for production)

Integrations​

Ragpi supports various integrations that can be deployed alongside the core services. Each integration requires additional configuration in your .env file and uses a specific Docker Compose profile.

Common Integration Requirements​

For all integrations:

  • RAGPI_BASE_URL - Already set to the API service URL by default in the Docker Compose configuration
  • RAGPI_API_KEY - If API authentication is enabled, this variable should already be set in the .env file and the integrations will use it for authentication

Integration-Specific Configuration​

Discord Integration​

Ensure you have created a Discord app and obtained the bot token. See the Discord Integration page for detailed instructions.

Required environment variables:

  • DISCORD_TOKEN - Discord bot token for authentication
  • DISCORD_CHANNEL_IDS - Comma-separated list of Discord channel IDs where the bot will listen

See Discord Configuration for additional options.

Slack Integration​

Ensure you have created a Slack app and obtained the app and bot tokens. See the Slack Integration page for detailed instructions.

Required environment variables:

  • SLACK_APP_TOKEN - Slack app token for authentication
  • SLACK_BOT_TOKEN - Slack bot token for authentication

See Slack Configuration for additional options.

Recaptcha Gateway (for Web Widget Integration)​

Ensure you have created a Google reCAPTCHA v3 key. See the Web Widget Integration page for detailed instructions.

Required environment variables:

  • RECAPTCHA_SECRET_KEY - Google reCAPTCHA v3 secret key

See Web Widget Configuration for additional options.

important

Similar to the API service, the Recaptcha Gateway service is configured to only listen on localhost (127.0.0.1) for security. To expose the Recaptcha Gateway service to external traffic, you can either:

  • Add the DOCKER_RECAPTCHA_GATEWAY_PORT_MAPPING environment variable to the .env file with the value 0.0.0.0:8000:8000 to expose the API service on port 8000. (Not recommended for production)
  • Use a reverse proxy like Nginx, a tunneling service like Cloudflare Tunnel, or a similar method to securely expose the API service. (Recommended for production)

Deploying Integrations​

Profiles are used to manage different integrations in the Docker Compose file. You can deploy Ragpi with specific integrations by using the --profile flag. Profile options include:

  • discord - Deploys the Discord integration
  • slack - Deploys the Slack integration
  • recaptcha-gateway - Deploys the Recaptcha Gateway (for Web Widget integration)

Deploy with a single integration, e.g., Discord:

docker compose -f docker-compose.prod.yml --profile discord up -d

To deploy with multiple integrations, you'll need to specify each profile with its own --profile flag:

docker compose -f docker-compose.prod.yml --profile slack --profile recaptcha-gateway up -d

Alternatively, you can use the COMPOSE_PROFILES environment variable with a comma-separated list:

COMPOSE_PROFILES=discord,recaptcha-gateway docker compose -f docker-compose.prod.yml up -d

Stopping Services​

To stop services, use the same profile configuration used to start them:

# Stop core services only
docker compose -f docker-compose.prod.yml down

# Stop with single profile
docker compose -f docker-compose.prod.yml --profile discord down

# Stop with multiple profiles
docker compose -f docker-compose.prod.yml --profile slack --profile recaptcha-gateway down

Custom Deployment​

For environments requiring custom orchestration or scaling solutions, Ragpi's Docker images can be deployed independently without Docker Compose. The official Docker images can be orchestrated using Kubernetes, AWS ECS, or other container management systems while maintaining the same environment variable configuration. Reference the Docker Compose file for service dependencies and configuration patterns.