Nicolas Koehl
3aa1d90b89
- Document complete process for handling internal/corporate SSL certificates - Explain CA bundle extraction and configuration methods - Provide environment variable setup for multiple tools - Include best practices for SSL certificate management - Reusable guide for other projects with custom CAs 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# CLAUDE.md - Guide for AI Coding Agents
|
|
|
|
## Project Overview
|
|
Nomad MCP is a service that enables management of HashiCorp Nomad jobs via REST API, with Claude AI integration.
|
|
|
|
## Commands
|
|
- **Run server**: `uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`
|
|
- **Tests**: `pytest` (all) or `pytest tests/test_nomad_service.py::test_job_lifecycle` (single)
|
|
- **Build docker**: `docker build -t nomad-mcp .`
|
|
- **Run docker**: `docker-compose up -d`
|
|
|
|
## Code Style
|
|
- **Imports**: Standard library → Third-party → Local modules (alphabetically)
|
|
- **Type annotations**: Required for all function parameters and returns
|
|
- **Error handling**: Use try/except with proper logging and HTTP exceptions
|
|
- **Logging**: Use Python's logging module with appropriate levels
|
|
- **API responses**: Return consistent JSON structures with Pydantic models
|
|
- **Docstrings**: Required for all functions and classes
|
|
- **Variables**: snake_case for variables, CamelCase for classes
|
|
|
|
## Structure
|
|
- `/app`: Main code (/routers, /schemas, /services)
|
|
- `/configs`: Configuration files
|
|
- `/static`: Frontend assets
|
|
- `/tests`: Test files
|
|
|
|
Always maintain backward compatibility with existing API endpoints. Follow REST principles.
|
|
|
|
## SSL Certificate Management for Internal Services
|
|
|
|
When working with internal/corporate services that use custom Certificate Authorities (CAs):
|
|
|
|
### Problem
|
|
- Internal services use SSL certificates signed by custom/corporate CAs
|
|
- System trust stores don't recognize these CAs
|
|
- Results in `SSL: CERTIFICATE_VERIFY_FAILED` errors
|
|
|
|
### Solution: Extract and Configure CA Bundle
|
|
|
|
1. **Extract CA Certificate Chain**:
|
|
```bash
|
|
# Find the CA issuer from certificate details
|
|
openssl s_client -connect your-service.internal:443 -showcerts
|
|
|
|
# Download CA certificate (adjust URL for your PKI)
|
|
curl -k "https://vault.internal:8200/v1/pki/ca" -o certs/ca_bundle.pem
|
|
```
|
|
|
|
2. **Test CA Bundle**:
|
|
```bash
|
|
# Test with curl
|
|
curl --cacert certs/ca_bundle.pem https://your-service.internal
|
|
|
|
# Test with Python
|
|
python -c "import requests; print(requests.get('https://your-service.internal', verify='certs/ca_bundle.pem').status_code)"
|
|
```
|
|
|
|
3. **Create Environment Configuration**:
|
|
```bash
|
|
# .env.ssl
|
|
export SSL_CERT_FILE="$(pwd)/certs/ca_bundle.pem"
|
|
export REQUESTS_CA_BUNDLE="$(pwd)/certs/ca_bundle.pem"
|
|
export CURL_CA_BUNDLE="$(pwd)/certs/ca_bundle.pem"
|
|
export GIT_SSL_CAINFO="$(pwd)/certs/ca_bundle.pem"
|
|
```
|
|
|
|
4. **Usage**:
|
|
```bash
|
|
# Load SSL configuration
|
|
source .env.ssl
|
|
|
|
# Now all tools use the CA bundle automatically
|
|
curl https://your-service.internal
|
|
git clone https://git.internal/repo.git
|
|
pip install -i https://pypi.internal/simple/ package
|
|
```
|
|
|
|
### For Different Tools
|
|
|
|
- **Curl**: `curl --cacert path/to/ca_bundle.pem`
|
|
- **Python requests**: `requests.get(url, verify='path/to/ca_bundle.pem')`
|
|
- **Git**: `git config http.sslCAInfo path/to/ca_bundle.pem`
|
|
- **Node.js**: `NODE_EXTRA_CA_CERTS=path/to/ca_bundle.pem`
|
|
- **Docker**: Mount certs and set `SSL_CERT_FILE` environment variable
|
|
|
|
### Environment Variables Priority
|
|
1. `SSL_CERT_FILE` - Used by most SSL libraries
|
|
2. `REQUESTS_CA_BUNDLE` - Python requests library
|
|
3. `CURL_CA_BUNDLE` - curl command
|
|
4. Tool-specific variables (e.g., `GIT_SSL_CAINFO`)
|
|
|
|
### Best Practices
|
|
- **Keep CA bundle in version control** (it's public key material)
|
|
- **Test SSL connections** with a script to verify setup
|
|
- **Document certificate renewal process** in project README
|
|
- **Use environment variables** for consistent configuration across tools
|
|
- **Never disable SSL verification** in production code
|
|
|
|
This approach provides proper SSL security while working with internal services. |