chore: clean .gitignore cache

2026-01-26 19:22:05 +00:00
parent e5f0fec5db
commit f64e3feef8
1448 changed files with 468101 additions and 0 deletions
--- a/docs/features/api.md
+++ b/docs/features/api.md
@@ -0,0 +1,161 @@
+---
+title: REST API
+description: Comprehensive REST API for automation and integrations
+---
+
+# REST API
+
+Automate everything. Charon's comprehensive REST API lets you manage hosts, certificates, security rules, and settings programmatically. Perfect for CI/CD pipelines, Infrastructure as Code, or custom integrations.
+
+## Overview
+
+The REST API provides full control over Charon's functionality through HTTP endpoints. All responses are JSON-formatted, and the API follows RESTful conventions for resource management.
+
+**Base URL**: `http://your-charon-instance:81/api`
+
+### Authentication
+
+All API requests require a Bearer token. Generate tokens in **Settings → API Tokens**.
+
+```bash
+# Include in all requests
+Authorization: Bearer your-api-token-here
+```
+
+Tokens support granular permissions:
+- **Read-only**: View configurations without modification
+- **Full access**: Complete CRUD operations
+- **Scoped**: Limit to specific resource types
+
+## Why Use the API?
+
+| Use Case | Benefit |
+|----------|---------|
+| **CI/CD Pipelines** | Automatically create proxy hosts for staging/preview deployments |
+| **Infrastructure as Code** | Version control your Charon configuration |
+| **Custom Dashboards** | Build monitoring integrations |
+| **Bulk Operations** | Manage hundreds of hosts programmatically |
+| **GitOps Workflows** | Sync configuration from Git repositories |
+
+## Key Endpoints
+
+### Proxy Hosts
+
+```bash
+# List all proxy hosts
+curl -X GET "http://charon:81/api/nginx/proxy-hosts" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Create a proxy host
+curl -X POST "http://charon:81/api/nginx/proxy-hosts" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "domain_names": ["app.example.com"],
+    "forward_host": "10.0.0.5",
+    "forward_port": 3000,
+    "ssl_forced": true,
+    "certificate_id": 1
+  }'
+
+# Update a proxy host
+curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"forward_port": 8080}'
+
+# Delete a proxy host
+curl -X DELETE "http://charon:81/api/nginx/proxy-hosts/1" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### SSL Certificates
+
+```bash
+# List certificates
+curl -X GET "http://charon:81/api/nginx/certificates" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Request new Let's Encrypt certificate
+curl -X POST "http://charon:81/api/nginx/certificates" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "provider": "letsencrypt",
+    "domain_names": ["secure.example.com"],
+    "meta": {"dns_challenge": true, "dns_provider": "cloudflare"}
+  }'
+```
+
+### DNS Providers
+
+```bash
+# List configured DNS providers
+curl -X GET "http://charon:81/api/nginx/dns-providers" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Add a DNS provider (for DNS-01 challenges)
+curl -X POST "http://charon:81/api/nginx/dns-providers" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Cloudflare Production",
+    "acme_dns_provider": "cloudflare",
+    "meta": {"CF_API_TOKEN": "your-cloudflare-token"}
+  }'
+```
+
+### Security Settings
+
+```bash
+# Get WAF status
+curl -X GET "http://charon:81/api/security/waf" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Enable WAF for a host
+curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"waf_enabled": true, "waf_mode": "block"}'
+
+# List CrowdSec decisions
+curl -X GET "http://charon:81/api/security/crowdsec/decisions" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## CI/CD Integration Example
+
+### GitHub Actions
+
+```yaml
+- name: Create Preview Environment
+  run: |
+    curl -X POST "${{ secrets.CHARON_URL }}/api/nginx/proxy-hosts" \
+      -H "Authorization: Bearer ${{ secrets.CHARON_TOKEN }}" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "domain_names": ["pr-${{ github.event.number }}.preview.example.com"],
+        "forward_host": "${{ steps.deploy.outputs.ip }}",
+        "forward_port": 3000
+      }'
+```
+
+## Error Handling
+
+The API returns standard HTTP status codes:
+
+| Code | Meaning |
+|------|---------|
+| `200` | Success |
+| `201` | Resource created |
+| `400` | Invalid request body |
+| `401` | Invalid or missing token |
+| `403` | Insufficient permissions |
+| `404` | Resource not found |
+| `500` | Server error |
+
+## Related
+
+- [Backup & Restore](backup-restore.md) - API-managed backups
+- [SSL Certificates](ssl-certificates.md) - Certificate automation
+- [Back to Features](../features.md)