DEPLOYMENT.md•6.48 kB
# MCP cldkctl Server Deployment Guide
> **Security Note:** Never commit your real tokens or secrets to the repository. All authentication is handled via environment variables or user input. Example tokens in this documentation are placeholders only.
This guide covers deploying the MCP cldkctl server to PyPI and setting up automated builds.
## Prerequisites
- Python 3.8+ installed
- `uv` package manager installed
- PyPI account with API token
- GitHub repository access
## Local Development Setup
### 1. Install Dependencies
```bash
# Install uv if not already installed
pip install uv
# Sync dependencies
uv sync
# Install in development mode
uv pip install -e .
```
### 3. Code Quality Checks
```bash
# Format code
uv run black .
uv run isort .
# Lint code
uv run flake8 mcp_cldkctl/
# Type checking
uv run mypy mcp_cldkctl/
```
## Building and Publishing
### 1. Update Version
Edit `pyproject.toml` and increment the version:
```toml
[project]
name = "mcp-cldkctl"
version = "0.2.9" # Increment this
```
### 2. Build Package
```bash
# Clean previous builds
rm -rf dist/ build/ *.egg-info/
# Build package
uv run python -m build
# Verify build
uv run python -m twine check dist/*
```
### 3. Test Upload (Optional)
```bash
# Upload to TestPyPI first
uv run python -m twine upload --repository testpypi dist/*
# Test installation from TestPyPI
uvx mcp-cldkctl --version
```
### 4. Publish to PyPI
```bash
# Upload to PyPI
uv run python -m twine upload dist/*
# Verify installation
uvx mcp-cldkctl --version
```
## Automated Deployment
### GitHub Actions Workflow
Create `.github/workflows/deploy.yml`:
```yaml
name: Deploy to PyPI
on:
push:
tags:
- 'v*'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install uv
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Install dependencies
run: |
uv sync
- name: Run tests
run: |
uv run pytest
- name: Build package
run: |
uv run python -m build
- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
password: ${{ secrets.PYPI_API_TOKEN }}
```
### Environment Variables
Set these in your GitHub repository secrets:
- `PYPI_API_TOKEN`: Your PyPI API token
## Docker Deployment
### Dockerfile
```dockerfile
FROM python:3.11-slim
# Install uv
RUN pip install uv
# Set working directory
WORKDIR /app
# Copy project files
COPY pyproject.toml uv.lock ./
COPY mcp_cldkctl/ ./mcp_cldkctl/
# Install dependencies
RUN uv sync --frozen
# Expose port (if needed)
EXPOSE 8000
# Run the MCP server
CMD ["uv", "run", "mcp-cldkctl"]
```
### Docker Build and Run
```bash
# Build image
docker build -t mcp-cldkctl .
# Run container
docker run -e CLDKCTL_TOKEN=your_token mcp-cldkctl
```
## Kubernetes Deployment
### Deployment YAML
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-cldkctl
spec:
replicas: 1
selector:
matchLabels:
app: mcp-cldkctl
template:
metadata:
labels:
app: mcp-cldkctl
spec:
containers:
- name: mcp-cldkctl
image: your-registry/mcp-cldkctl:latest
env:
- name: CLDKCTL_TOKEN
valueFrom:
secretKeyRef:
name: cldkctl-secret
key: token
- name: CLDKCTL_BASE_URL
value: "https://ai.cloudeka.id"
ports:
- containerPort: 8000
```
### Secret for Token
```yaml
apiVersion: v1
kind: Secret
metadata:
name: cldkctl-secret
type: Opaque
data:
token: <base64-encoded-token>
```
## Environment Configuration
### Production Environment
```bash
# Environment variables
export CLDKCTL_TOKEN="cldkctl_your_production_token"
export CLDKCTL_BASE_URL="https://ai.cloudeka.id"
export CLDKCTL_DEFAULT_PROJECT_ID="your_project_id"
# Run server
uvx mcp-cldkctl
```
### Staging Environment
```bash
# Environment variables
export CLDKCTL_TOKEN="cldkctl_your_staging_token"
export CLDKCTL_BASE_URL="https://staging.ai.cloudeka.id"
export CLDKCTL_DEFAULT_PROJECT_ID="your_staging_project_id"
# Run server
uvx mcp-cldkctl
```
## Monitoring and Logging
### Health Check Endpoint
The MCP server provides a status endpoint:
```python
# Check server status
status()
```
### Logging Configuration
```python
import logging
# Configure logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```
## Troubleshooting
### Common Issues
1. **Build Failures**
- Check Python version compatibility
- Verify all dependencies are listed in `pyproject.toml`
- Run `uv sync` to update lock file
2. **Import Errors**
- Ensure package is installed correctly
- Check `__init__.py` files exist
- Verify import paths
3. **Authentication Issues**
- Verify `CLDKCTL_TOKEN` is set correctly
- Check token format (should start with `cldkctl_`)
- Test with staging environment
4. **Network Issues**
- Check firewall settings
- Verify DNS resolution
- Test connectivity to Cloudeka endpoints
### Debug Commands
```bash
# Check package installation
uvx mcp-cldkctl --version
# Run with debug output
uvx mcp-cldkctl 2>&1 | tee debug.log
```
## Version Management
### Semantic Versioning
Follow semantic versioning (MAJOR.MINOR.PATCH):
- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible
### Release Process
1. Update version in `pyproject.toml`
2. Update `CHANGELOG.md`
3. Create git tag: `git tag v0.1.18`
4. Push tag: `git push origin v0.1.18`
5. GitHub Actions will automatically deploy
## Support
For deployment issues:
- Check [GitHub Issues](https://github.com/cloudeka/mcp-cldkctl/issues)
- Review [MCP Documentation](https://modelcontextprotocol.io)
- Contact support@cloudeka.id
---
**Last Updated**: 2024-12-21
**Version**: 0.2.9