Skip to content

Commit 7e0389c

Browse files
IvanBirukIvanBiruk
committed
Add example Docker Compose template and documentation for HTTP-based MCP server deployment
- Introduced `docker-compose.example.yml` with detailed comments and configurations for both self-hosted and cloud deployments. - Updated `README.md` to include a new section on HTTP deployment, covering setup instructions and client integration examples.
1 parent ccb648c commit 7e0389c

File tree

2 files changed

+204
-0
lines changed

2 files changed

+204
-0
lines changed

‎README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ After setup, try these commands with your AI assistant:
4343
* [AI Client Integrations](#-ai-client-integrations)
4444
* [Advanced: Local Development](#-advanced-local-development)
4545
* [Community Plugins](#-community-plugins)
46+
* [HTTP Deployment (Self-Hosted & Cloud)](#-http-deployment-self-hosted--cloud)
4647
* [Available Tools](#-available-tools)
4748
* [Usage Examples](#-usage-examples)
4849
* [Troubleshooting](#-troubleshooting)
@@ -775,6 +776,77 @@ gemini
775776

776777
---
777778

779+
## 🚢 HTTP Deployment (Self-Hosted & Cloud)
780+
781+
**Deploy the MCP server as an HTTP service for team-wide access or integration with self-hosted CodeAlive instances.**
782+
783+
### Deployment Options
784+
785+
The CodeAlive MCP server can be deployed as an HTTP service using Docker. This allows multiple AI clients to connect to a single shared instance, and enables integration with self-hosted CodeAlive deployments.
786+
787+
### Docker Compose (Recommended)
788+
789+
Create a `docker-compose.yml` file based on our example:
790+
791+
```bash
792+
# Download the example
793+
curl -O https://raw.githubusercontent.com/CodeAlive-AI/codealive-mcp/main/docker-compose.example.yml
794+
mv docker-compose.example.yml docker-compose.yml
795+
796+
# Edit configuration (see below)
797+
nano docker-compose.yml
798+
799+
# Start the service
800+
docker compose up -d
801+
802+
# Check health
803+
curl http://localhost:8000/health
804+
```
805+
806+
**Configuration Options:**
807+
808+
1. **For CodeAlive Cloud (default):**
809+
- Remove `CODEALIVE_BASE_URL` environment variable (uses default `https://app.codealive.ai`)
810+
- Clients must provide their API key via `Authorization: Bearer YOUR_KEY` header
811+
812+
2. **For Self-Hosted CodeAlive:**
813+
- Set `CODEALIVE_BASE_URL` to your CodeAlive instance URL (e.g., `https://codealive.yourcompany.com`)
814+
- Clients must provide their API key via `Authorization: Bearer YOUR_KEY` header
815+
816+
See `docker-compose.example.yml` for the complete configuration template.
817+
818+
### Connecting AI Clients to Your Deployed Instance
819+
820+
Once deployed, configure your AI clients to use your HTTP endpoint:
821+
822+
**Claude Code:**
823+
```bash
824+
claude mcp add --transport http codealive http://your-server:8000/api --header "Authorization: Bearer YOUR_API_KEY_HERE"
825+
```
826+
827+
**VS Code:**
828+
```bash
829+
code --add-mcp "{\"name\":\"codealive\",\"type\":\"http\",\"url\":\"http://your-server:8000/api\",\"headers\":{\"Authorization\":\"Bearer YOUR_API_KEY_HERE\"}}"
830+
```
831+
832+
**Cursor / Other Clients:**
833+
```json
834+
{
835+
"mcpServers": {
836+
"codealive": {
837+
"url": "http://your-server:8000/api",
838+
"headers": {
839+
"Authorization": "Bearer YOUR_API_KEY_HERE"
840+
}
841+
}
842+
}
843+
}
844+
```
845+
846+
Replace `your-server:8000` with your actual deployment URL and port.
847+
848+
---
849+
778850
## 🐞 Troubleshooting
779851

780852
### Quick Diagnostics

‎docker-compose.example.yml‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
version: '3.8'
2+
3+
services:
4+
codealive-mcp:
5+
# Use the latest stable image from GitHub Container Registry
6+
image: ghcr.io/codealive-ai/codealive-mcp:main
7+
8+
# Container name for easy reference
9+
container_name: codealive-mcp-server
10+
11+
# Restart policy - automatically restart if container stops
12+
restart: unless-stopped
13+
14+
# Port mapping - expose MCP server on port 8000
15+
ports:
16+
- "8000:8000"
17+
18+
# Environment variables
19+
environment:
20+
# ==========================================
21+
# CONFIGURATION FOR SELF-HOSTED CODEALIVE
22+
# ==========================================
23+
# Uncomment and set this to your self-hosted CodeAlive instance URL
24+
# REQUIRED for self-hosted deployments
25+
# CODEALIVE_BASE_URL: "https://codealive.yourcompany.com"
26+
27+
# ==========================================
28+
# CONFIGURATION FOR CODEALIVE CLOUD
29+
# ==========================================
30+
# For CodeAlive Cloud, comment out or remove CODEALIVE_BASE_URL above
31+
# The server will use the default: https://app.codealive.ai
32+
33+
# ==========================================
34+
# API KEY CONFIGURATION (IMPORTANT!)
35+
# ==========================================
36+
# In HTTP mode, API keys should be provided by clients via
37+
# "Authorization: Bearer YOUR_KEY" headers, NOT environment variables.
38+
#
39+
# Do NOT set CODEALIVE_API_KEY here in production.
40+
# Each client connection should provide their own API key.
41+
42+
# ==========================================
43+
# OPTIONAL SETTINGS
44+
# ==========================================
45+
# Enable debug mode (verbose logging)
46+
# DEBUG_MODE: "false"
47+
48+
# Disable SSL verification (only for development/testing)
49+
# CODEALIVE_IGNORE_SSL: "false"
50+
51+
# Command to run the MCP server in HTTP mode
52+
command: >
53+
python src/codealive_mcp_server.py
54+
--transport http
55+
--host 0.0.0.0
56+
--port 8000
57+
58+
# Health check configuration
59+
healthcheck:
60+
test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
61+
interval: 30s
62+
timeout: 5s
63+
retries: 3
64+
start_period: 10s
65+
66+
# Resource limits (adjust based on your needs)
67+
deploy:
68+
resources:
69+
limits:
70+
cpus: '0.5'
71+
memory: 512M
72+
reservations:
73+
cpus: '0.25'
74+
memory: 256M
75+
76+
# ==========================================
77+
# USAGE INSTRUCTIONS
78+
# ==========================================
79+
#
80+
# 1. Copy this file to docker-compose.yml:
81+
# cp docker-compose.example.yml docker-compose.yml
82+
#
83+
# 2. Edit docker-compose.yml:
84+
# - For self-hosted: Uncomment and set CODEALIVE_BASE_URL
85+
# - For cloud: Leave CODEALIVE_BASE_URL commented out
86+
#
87+
# 3. Start the service:
88+
# docker compose up -d
89+
#
90+
# 4. Check health:
91+
# curl http://localhost:8000/health
92+
#
93+
# 5. Connect AI clients using:
94+
# - URL: http://your-server:8000/api
95+
# - Header: Authorization: Bearer YOUR_API_KEY
96+
#
97+
# ==========================================
98+
# EXAMPLES
99+
# ==========================================
100+
#
101+
# Claude Code:
102+
# claude mcp add --transport http codealive http://localhost:8000/api \
103+
# --header "Authorization: Bearer YOUR_API_KEY"
104+
#
105+
# Cursor/Other Clients (JSON config):
106+
# {
107+
# "mcpServers": {
108+
# "codealive": {
109+
# "url": "http://localhost:8000/api",
110+
# "headers": {
111+
# "Authorization": "Bearer YOUR_API_KEY"
112+
# }
113+
# }
114+
# }
115+
# }
116+
#
117+
# ==========================================
118+
# TROUBLESHOOTING
119+
# ==========================================
120+
#
121+
# View logs:
122+
# docker compose logs -f codealive-mcp
123+
#
124+
# Restart service:
125+
# docker compose restart codealive-mcp
126+
#
127+
# Stop service:
128+
# docker compose down
129+
#
130+
# Update to latest version:
131+
# docker compose pull
132+
# docker compose up -d

0 commit comments

Comments
 (0)