Deployment & Self-Hosting
Relevant source files
The following files were used as context for generating this wiki page:
The pho.chat application offers flexible deployment options, primarily supporting one-click deployment via Vercel and a more controlled, self-hosted environment using Docker. These methods allow users to deploy their own private chatbot application.
The primary deployment strategies are:
- Vercel: For a streamlined, serverless deployment experience, integrating with services like Neon (PostgreSQL), Clerk (Authentication), and Sentry (Monitoring).
- Docker: For local development and self-hosting, providing greater control over the infrastructure stack, including the database and object storage.
This document outlines the architecture and configuration for both Vercel and Docker-based deployments.
Sources: packages/const/src/guide.ts:28-32, PRODUCTION_DEPLOYMENT_GUIDE.md
Deployment Options Overview
The following diagram illustrates the two main paths for deploying the application.
This diagram shows the two primary deployment strategies: a managed Vercel deployment and a self-contained Docker deployment.
Sources: PRODUCTION_DEPLOYMENT_GUIDE.md, docker-compose/local/docker-compose.yml, packages/const/src/guide.ts:28-32
Vercel Deployment
Vercel is the recommended platform for production deployment, offering a serverless architecture that integrates with various managed services.
Sources: PRODUCTION_DEPLOYMENT_GUIDE.md
Build Configuration
The vercel.json file defines the build process and routing rules for the Vercel platform.
- Build Command: The application is built using the
pnpm buildcommand. - Routing: The configuration includes rewrite rules to handle API endpoints and image placeholders. For example, requests to
/api/placeholder/:path*are rewritten to a Vercel function.
{
"build": {
"env": {
"ENABLE_VERCEL_ANALYTICS": "1",
"ENABLE_VERCEL_TOOLBAR": "1"
}
},
"buildCommand": "pnpm build",
"rewrites": [
{
"source": "/api/placeholder/:path*",
"destination": "/api/placeholder?path=:path*"
}
]
}
Sources: vercel.json:3-13
Production Environment & Services
The production environment on Vercel is configured to use a suite of external services for database, authentication, and monitoring.
| Service | Provider | Purpose |
|---|---|---|
| Database | Neon | PostgreSQL database with pooled connections. |
| Authentication | Clerk | The sole authentication provider, replacing NextAuth. |
| Monitoring | Sentry | Error tracking and performance monitoring. |
| AI Models | OpenRouter | Routes requests to various AI models (OpenAI, Anthropic, Google). |
| File Storage | AWS S3 | Used for file uploads, requiring CORS configuration. |
Sources: PRODUCTION_DEPLOYMENT_GUIDE.md:12-39, 100-104, FILE_UPLOAD_EXECUTIVE_SUMMARY.md:18-20
Environment Variables
A set of environment variables is required for the production deployment to function correctly.
| Variable | Description | Example Value |
|---|---|---|
DATABASE_URL | Connection string for the Neon PostgreSQL database. | postgres://... |
DATABASE_DRIVER | Set to node for Vercel environment. | node |
KEY_VAULTS_SECRET | Secret for key vault encryption. | configured |
NEXT_PUBLIC_SERVICE_MODE | Application service mode. | server |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Public key for Clerk authentication. | pk_live_... |
CLERK_SECRET_KEY | Secret key for Clerk authentication. | sk_live_... |
CLERK_WEBHOOK_SECRET | Secret for verifying Clerk webhooks. | whsec_... |
NEXT_PUBLIC_ENABLE_NEXT_AUTH | Set to 0 to disable NextAuth. | 0 |
OPENROUTER_API_KEY | API key for the OpenRouter service. | sk-or-v1-... |
S3_BUCKET | Name of the S3 bucket for file uploads. | pho-chat |
S3_REGION | AWS region for the S3 bucket. | ap-southeast-2 |
Sources: PRODUCTION_DEPLOYMENT_GUIDE.md:15-24, 42-45, 69-72, FILE_UPLOAD_EXECUTIVE_SUMMARY.md:55-57
Docker Deployment
The project provides Docker Compose files for setting up both a local development environment and a more complete self-hosted environment.
Local Development Setup
The docker-compose.development.yml file is designed for local development. It spins up the application container and a PostgreSQL database.
This diagram shows the services defined in the development Docker Compose file.
| Service | Image | Ports | Description |
|---|---|---|---|
db | postgres:16-alpine | 5432:5432 | A PostgreSQL database for data persistence. |
app | lobe-chat-development | 3010:3010 | The main application, built from the local source code. It depends on the db service. |
Sources: docker-compose.development.yml
Full Self-Hosting Setup
The docker-compose/local/docker-compose.yml file provides a more comprehensive stack for self-hosting, including object storage.
This diagram illustrates the services in the local self-hosting stack.
| Service | Image | Ports | Description |
|---|---|---|---|
minio | minio/minio | 9000:9000, 9001:9001 | An S3-compatible object storage service for file uploads. |
postgres | postgres:16-alpine | 5433:5432 | A PostgreSQL database for data persistence, mapped to a different host port to avoid conflicts. |
app | lobehub/lobe-chat:latest | 3210:3210 | The main application, using the official pre-built Docker image. |
Sources: docker-compose/local/docker-compose.yml
Docker Setup Script
The docker-compose/setup.sh script automates the initial configuration for the Docker environment by creating the necessary .env file.
The sequence diagram below shows the script's execution flow.
This script simplifies the setup process by ensuring that a default environment file is available for customization before starting the Docker containers.
Sources: docker-compose/setup.sh
Summary
pho.chat offers two robust deployment paths. Vercel provides a managed, scalable, and easy-to-deploy solution ideal for production, leveraging a rich ecosystem of third-party services. The Docker-based approach offers greater control and is suitable for local development and users who wish to self-host the entire application stack on their own infrastructure. The provided Docker Compose files and setup scripts streamline the process of getting a local instance running.
Sources: packages/const/src/guide.ts:28-32, PRODUCTION_DEPLOYMENT_GUIDE.md, docker-compose/local/docker-compose.yml