akanealw/Charon
1
0
Fork 0
Code Issues Pull Requests Actions 14 Packages Projects Releases Wiki Activity

chore: remove cached

Browse Source
This commit is contained in:
Wikid82
2025-11-24 18:21:11 +00:00
parent 5b041819bb
commit 9c842e7eab
394 changed files with 0 additions and 44139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

669
docs/api.md
View File

@@ -1,669 +0,0 @@
# API Documentation
CaddyProxyManager+ REST API documentation. All endpoints return JSON and use standard HTTP status codes.
## Base URL
```
http://localhost:8080/api/v1
```
## Authentication
🚧 Authentication is not yet implemented. All endpoints are currently public.
Future authentication will use JWT tokens:
```http
Authorization: Bearer <token>
```
## Response Format
### Success Response
```json
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example",
"created_at": "2025-01-18T10:00:00Z"
}
```
### Error Response
```json
{
"error": "Resource not found",
"code": 404
}
```
## Status Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created |
| 204 | No Content (successful deletion) |
| 400 | Bad Request (validation error) |
| 404 | Not Found |
| 500 | Internal Server Error |
## Endpoints
### Health Check
Check API health status.
```http
GET /health
```
**Response 200:**
```json
{
"status": "ok"
}
```
---
### Proxy Hosts
#### List All Proxy Hosts
```http
GET /proxy-hosts
```
**Response 200:**
```json
[
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"domain": "example.com, www.example.com",
"forward_scheme": "http",
"forward_host": "localhost",
"forward_port": 8080,
"ssl_forced": false,
"http2_support": true,
"hsts_enabled": false,
"hsts_subdomains": false,
"block_exploits": true,
"websocket_support": false,
"enabled": true,
"remote_server_id": null,
"created_at": "2025-01-18T10:00:00Z",
"updated_at": "2025-01-18T10:00:00Z"
}
]
```
#### Get Proxy Host
```http
GET /proxy-hosts/:uuid
```
**Parameters:**
- `uuid` (path) - Proxy host UUID
**Response 200:**
```json
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"domain": "example.com",
"forward_scheme": "https",
"forward_host": "backend.internal",
"forward_port": 9000,
"ssl_forced": true,
"websocket_support": false,
"enabled": true,
"created_at": "2025-01-18T10:00:00Z",
"updated_at": "2025-01-18T10:00:00Z"
}
```
**Response 404:**
```json
{
"error": "Proxy host not found"
}
```
#### Create Proxy Host
```http
POST /proxy-hosts
Content-Type: application/json
```
**Request Body:**
```json
{
"domain": "new.example.com",
"forward_scheme": "http",
"forward_host": "localhost",
"forward_port": 3000,
"ssl_forced": false,
"http2_support": true,
"hsts_enabled": false,
"hsts_subdomains": false,
"block_exploits": true,
"websocket_support": false,
"enabled": true,
"remote_server_id": null
}
```
**Required Fields:**
- `domain` - Domain name(s), comma-separated
- `forward_host` - Target hostname or IP
- `forward_port` - Target port number
**Optional Fields:**
- `forward_scheme` - Default: `"http"`
- `ssl_forced` - Default: `false`
- `http2_support` - Default: `true`
- `hsts_enabled` - Default: `false`
- `hsts_subdomains` - Default: `false`
- `block_exploits` - Default: `true`
- `websocket_support` - Default: `false`
- `enabled` - Default: `true`
- `remote_server_id` - Default: `null`
**Response 201:**
```json
{
"uuid": "550e8400-e29b-41d4-a716-446655440001",
"domain": "new.example.com",
"forward_scheme": "http",
"forward_host": "localhost",
"forward_port": 3000,
"created_at": "2025-01-18T10:05:00Z",
"updated_at": "2025-01-18T10:05:00Z"
}
```
**Response 400:**
```json
{
"error": "domain is required"
}
```
#### Update Proxy Host
```http
PUT /proxy-hosts/:uuid
Content-Type: application/json
```
**Parameters:**
- `uuid` (path) - Proxy host UUID
**Request Body:** (all fields optional)
```json
{
"domain": "updated.example.com",
"forward_port": 8081,
"ssl_forced": true
}
```
**Response 200:**
```json
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"domain": "updated.example.com",
"forward_port": 8081,
"ssl_forced": true,
"updated_at": "2025-01-18T10:10:00Z"
}
```
#### Delete Proxy Host
```http
DELETE /proxy-hosts/:uuid
```
**Parameters:**
- `uuid` (path) - Proxy host UUID
**Response 204:** No content
**Response 404:**
```json
{
"error": "Proxy host not found"
}
```
---
### Remote Servers
#### List All Remote Servers
```http
GET /remote-servers
```
**Query Parameters:**
- `enabled` (optional) - Filter by enabled status (`true` or `false`)
**Response 200:**
```json
[
{
"uuid": "660e8400-e29b-41d4-a716-446655440000",
"name": "Docker Registry",
"provider": "docker",
"host": "registry.local",
"port": 5000,
"reachable": true,
"last_checked": "2025-01-18T09:55:00Z",
"enabled": true,
"created_at": "2025-01-18T09:00:00Z",
"updated_at": "2025-01-18T09:55:00Z"
}
]
```
#### Get Remote Server
```http
GET /remote-servers/:uuid
```
**Parameters:**
- `uuid` (path) - Remote server UUID
**Response 200:**
```json
{
"uuid": "660e8400-e29b-41d4-a716-446655440000",
"name": "Docker Registry",
"provider": "docker",
"host": "registry.local",
"port": 5000,
"reachable": true,
"enabled": true
}
```
#### Create Remote Server
```http
POST /remote-servers
Content-Type: application/json
```
**Request Body:**
```json
{
"name": "Production API",
"provider": "generic",
"host": "api.prod.internal",
"port": 8080,
"enabled": true
}
```
**Required Fields:**
- `name` - Server name
- `host` - Hostname or IP
- `port` - Port number
**Optional Fields:**
- `provider` - One of: `generic`, `docker`, `kubernetes`, `aws`, `gcp`, `azure` (default: `generic`)
- `enabled` - Default: `true`
**Response 201:**
```json
{
"uuid": "660e8400-e29b-41d4-a716-446655440001",
"name": "Production API",
"provider": "generic",
"host": "api.prod.internal",
"port": 8080,
"reachable": false,
"enabled": true,
"created_at": "2025-01-18T10:15:00Z"
}
```
#### Update Remote Server
```http
PUT /remote-servers/:uuid
Content-Type: application/json
```
**Request Body:** (all fields optional)
```json
{
"name": "Updated Name",
"port": 8081,
"enabled": false
}
```
**Response 200:**
```json
{
"uuid": "660e8400-e29b-41d4-a716-446655440000",
"name": "Updated Name",
"port": 8081,
"enabled": false,
"updated_at": "2025-01-18T10:20:00Z"
}
```
#### Delete Remote Server
```http
DELETE /remote-servers/:uuid
```
**Response 204:** No content
#### Test Remote Server Connection
Test connectivity to a remote server.
```http
POST /remote-servers/:uuid/test
```
**Parameters:**
- `uuid` (path) - Remote server UUID
**Response 200:**
```json
{
"reachable": true,
"address": "registry.local:5000",
"timestamp": "2025-01-18T10:25:00Z"
}
```
**Response 200 (unreachable):**
```json
{
"reachable": false,
"address": "offline.server:8080",
"error": "connection timeout",
"timestamp": "2025-01-18T10:25:00Z"
}
```
**Note:** This endpoint updates the `reachable` and `last_checked` fields on the remote server.
---
### Import Workflow
#### Check Import Status
Check if there's an active import session.
```http
GET /import/status
```
**Response 200 (no session):**
```json
{
"has_pending": false
}
```
**Response 200 (active session):**
```json
{
"has_pending": true,
"session": {
"uuid": "770e8400-e29b-41d4-a716-446655440000",
"filename": "Caddyfile",
"state": "reviewing",
"created_at": "2025-01-18T10:30:00Z",
"updated_at": "2025-01-18T10:30:00Z"
}
}
```
#### Get Import Preview
Get preview of hosts to be imported (only available when session state is `reviewing`).
```http
GET /import/preview
```
**Response 200:**
```json
{
"hosts": [
{
"domain": "example.com",
"forward_host": "localhost",
"forward_port": 8080,
"forward_scheme": "http"
},
{
"domain": "api.example.com",
"forward_host": "backend",
"forward_port": 9000,
"forward_scheme": "https"
}
],
"conflicts": [
"example.com already exists"
],
"errors": []
}
```
**Response 404:**
```json
{
"error": "No active import session"
}
```
#### Upload Caddyfile
Upload a Caddyfile for import.
```http
POST /import/upload
Content-Type: application/json
```
**Request Body:**
```json
{
"content": "example.com {\n reverse_proxy localhost:8080\n}",
"filename": "Caddyfile"
}
```
**Required Fields:**
- `content` - Caddyfile content
**Optional Fields:**
- `filename` - Original filename (default: `"Caddyfile"`)
**Response 201:**
```json
{
"session": {
"uuid": "770e8400-e29b-41d4-a716-446655440000",
"filename": "Caddyfile",
"state": "parsing",
"created_at": "2025-01-18T10:35:00Z"
}
}
```
**Response 400:**
```json
{
"error": "content is required"
}
```
#### Commit Import
Commit the import after resolving conflicts.
```http
POST /import/commit
Content-Type: application/json
```
**Request Body:**
```json
{
"session_uuid": "770e8400-e29b-41d4-a716-446655440000",
"resolutions": {
"example.com": "overwrite",
"api.example.com": "keep"
}
}
```
**Required Fields:**
- `session_uuid` - Active import session UUID
- `resolutions` - Map of domain to resolution strategy
**Resolution Strategies:**
- `"keep"` - Keep existing configuration, skip import
- `"overwrite"` - Replace existing with imported configuration
- `"skip"` - Same as keep
**Response 200:**
```json
{
"imported": 2,
"skipped": 1,
"failed": 0
}
```
**Response 400:**
```json
{
"error": "Invalid session or unresolved conflicts"
}
```
#### Cancel Import
Cancel an active import session.
```http
DELETE /import/cancel?session_uuid=770e8400-e29b-41d4-a716-446655440000
```
**Query Parameters:**
- `session_uuid` - Active import session UUID
**Response 204:** No content
---
## Rate Limiting
🚧 Rate limiting is not yet implemented.
Future rate limits:
- 100 requests per minute per IP
- 1000 requests per hour per IP
## Pagination
🚧 Pagination is not yet implemented.
Future pagination:
```http
GET /proxy-hosts?page=1&per_page=20
```
## Filtering and Sorting
🚧 Advanced filtering is not yet implemented.
Future filtering:
```http
GET /proxy-hosts?enabled=true&sort=created_at&order=desc
```
## Webhooks
🚧 Webhooks are not yet implemented.
Future webhook events:
- `proxy_host.created`
- `proxy_host.updated`
- `proxy_host.deleted`
- `remote_server.unreachable`
- `import.completed`
## SDKs
No official SDKs yet. The API follows REST conventions and can be used with any HTTP client.
### JavaScript/TypeScript Example
```typescript
const API_BASE = 'http://localhost:8080/api/v1';
// List proxy hosts
const hosts = await fetch(`${API_BASE}/proxy-hosts`).then(r => r.json());
// Create proxy host
const newHost = await fetch(`${API_BASE}/proxy-hosts`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
domain: 'example.com',
forward_host: 'localhost',
forward_port: 8080
})
}).then(r => r.json());
// Test remote server
const testResult = await fetch(`${API_BASE}/remote-servers/${uuid}/test`, {
method: 'POST'
}).then(r => r.json());
```
### Python Example
```python
import requests
API_BASE = 'http://localhost:8080/api/v1'
# List proxy hosts
hosts = requests.get(f'{API_BASE}/proxy-hosts').json()
# Create proxy host
new_host = requests.post(f'{API_BASE}/proxy-hosts', json={
'domain': 'example.com',
'forward_host': 'localhost',
'forward_port': 8080
}).json()
# Test remote server
test_result = requests.post(f'{API_BASE}/remote-servers/{uuid}/test').json()
```
## Support
For API issues or questions:
- GitHub Issues: https://github.com/Wikid82/CaddyProxyManagerPlus/issues
- Discussions: https://github.com/Wikid82/CaddyProxyManagerPlus/discussions

68
docs/beta_release_draft_pr.md
View File

@@ -1,68 +0,0 @@
# Beta Release Draft Pull Request
## Overview
This draft PR merges recent beta preparation changes from `feature/beta-release` into `feature/alpha-completion` to align the alpha integration branch with the latest CI, workflow, and release process improvements.
## Changes Included
1. Workflow Token Updates
- Replaced deprecated `CPMP_TOKEN` usage with `CPMP_TOKEN` per new GitHub token naming restrictions.
- Ensured consistent secret reference across `release.yml` and `renovate_prune.yml`.
2. Release Workflow Adjustments
- Fixed environment variable configuration for release publication.
- Maintained prerelease logic for alpha/beta/rc tags.
3. CI Stability Improvements
- Prior earlier commits (already merged previously) included action version pinning for reproducibility and security.
4. Docker Build Reliability
- (Previously merged) Improvements to locate and package the `dlv` binary reliably in multi-arch builds.
## Commits Ahead of `feature/alpha-completion`
- 6c8ba7b fix: replace CPMP_TOKEN with CPMP_TOKEN in workflows
- de1160a fix: revert to CPMP_TOKEN
- 7aee12b fix: use CPMP_TOKEN in release workflow
- 0449681 docs: add beta-release draft PR summary
- fc08514 docs: update beta-release draft PR summary with new commit
- 18c3621 docs: update beta-release draft PR summary with second update
- 178e7ed docs: update beta-release draft PR summary with third update
- 4843eca docs: update beta-release draft PR summary with fourth update
- 6b3b9e3 docs: update beta-release draft PR summary with fifth update
- dddfebb docs: update beta-release draft PR summary with sixth update
- a0c84c7 docs: update beta-release draft PR summary with seventh update
- 3a410b8 docs: update beta-release draft PR summary with eighth update
- 7483dd0 docs: update beta-release draft PR summary with ninth update
- e116e08 docs: update beta-release draft PR summary with tenth update
- 54f1585 docs: update beta-release draft PR summary with eleventh update (retry)
- 44c2fba docs: update beta-release draft PR summary with twelfth update
- 41edb5a docs: update beta-release draft PR summary with thirteenth update
- 49b13cc docs: update beta-release draft PR summary with fourteenth update
- 990161c docs: update beta-release draft PR summary with fifteenth update
- ed13d67 docs: update beta-release draft PR summary with sixteenth update
- 7e32857 docs: update beta-release draft PR summary with seventeenth update
- 5a6aec1 docs: update beta-release draft PR summary with eighteenth update
- 9169e61 docs: update beta-release draft PR summary with nineteenth update
- 119364f docs: update beta-release draft PR summary with twentieth update
- c960f18 docs: update beta-release draft PR summary with twenty-first update
- 5addf23 docs: update beta-release draft PR summary with twenty-second update
- 19aeb42 docs: update beta-release draft PR summary with twenty-third update
- ae918bf docs: update beta-release draft PR summary with twenty-fourth update
- 853f0f1 docs: update beta-release draft PR summary with twenty-fifth update
- 3adc860 docs: update beta-release draft PR summary with twenty-sixth update
- 28a793d docs: update beta-release draft PR summary with twenty-seventh update
- 3cd9875 docs: update beta-release draft PR summary with twenty-eighth update
- c99723d docs: update beta-release draft PR summary with twenty-ninth update
## Follow-ups (Not in This PR)
- Frontend test coverage enhancement for `ProxyHostForm` (in progress separately).
- Additional beta feature hardening tasks (observability, import validations) will come later.
## Verification Checklist
- [x] Workflows pass YAML lint locally (pre-commit success)
- [x] No removed secrets; only name substitutions
- [ ] CI run on draft PR (expected)
## Request
Marking this as a DRAFT to allow review of token changes before merge. Please:
- Confirm `CPMP_TOKEN` exists in repo secrets.
- Review for any missed workflow references.
---
Generated by automated assistant for alignment between branches.

38
docs/beta_release_draft_pr_body_snapshot.md
View File

@@ -1,38 +0,0 @@
# Beta Release Draft Pull Request
## Overview
This draft PR merges recent beta preparation changes from `feature/beta-release` into `feature/alpha-completion` to align the alpha integration branch with the latest CI, workflow, and release process improvements.
## Changes Included (Summary)
- Workflow token migration (`CPMP_TOKEN` → `CPMP_TOKEN`) across release and maintenance workflows.
- Stabilized release workflow prerelease detection and artifact publication.
- Prior (already merged earlier) CI enhancements: pinned action versions, Docker multi-arch debug tooling reliability, dynamic `dlv` binary resolution.
- Documentation updates enumerating each incremental workflow/token adjustment for auditability.
## Commits Ahead of `feature/alpha-completion`
(See `docs/beta_release_draft_pr.md` for full enumerated list.) Latest unique commit: `5727c586` (refreshed body snapshot).
## Rationale
Ensures alpha integration branch inherits hardened CI/release pipeline and updated secret naming policy before further alpha feature consolidation.
## Risk & Mitigation
- Secret Name Change: Requires `CPMP_TOKEN` to exist. Mitigation: Verify secret presence before merge.
- Workflow Fan-out: Reusable workflow path validated locally; CI run (draft) will confirm.
## Follow-ups (Out of Scope)
- Frontend test coverage improvements (ProxyHostForm).
- Additional beta observability and import validation tasks.
## Checklist
- [x] YAML lint (pre-commit passed)
- [x] Secret reference consistency
- [x] Release artifact list intact
- [ ] Draft PR CI run (pending after opening)
## Requested Review Focus
1. Confirm `CPMP_TOKEN` availability.
2. Sanity-check release artifact matrix remains correct.
3. Spot any residual `CPMP_TOKEN` references missed.
---
Generated draft to align branches; will convert to ready-for-review after validation.

37
docs/beta_release_pr_body.md
View File

@@ -1,37 +0,0 @@
# Beta Release Draft Pull Request
## Overview
Draft PR to merge hardened CI/release workflow changes from `feature/beta-release` into `feature/alpha-completion`.
## Highlights
- Secret token migration: all workflows now use `CPMP_TOKEN` (GitHub blocks new secrets containing `GITHUB`).
- Release workflow refinements: stable prerelease detection (alpha/beta/rc), artifact matrix intact.
- Prior infra hardening (already partially merged earlier): pinned GitHub Action SHAs/tags, resilient Delve (`dlv`) multi-arch build handling.
- Extensive incremental documentation trail in `docs/beta_release_draft_pr.md` plus concise snapshot in `docs/beta_release_draft_pr_body_snapshot.md` for reviewers.
## Ahead Commits (Representative)
Most recent snapshot commit: `308ae5dd` (final body content before PR). Full ordered list in `docs/beta_release_draft_pr.md`.
## Review Checklist
- Secret `CPMP_TOKEN` exists and has required scopes.
- No lingering `CPMP_TOKEN` references beyond allowed GitHub-provided contexts.
- Artifact list (frontend dist, backend binaries, caddy binaries) still correct for release.
## Risks & Mitigations
- Secret rename: Mitigate by verifying secret presence before merge.
- Workflow call path validity: `docker-publish.yml` referenced locally; CI on draft will validate end-to-end.
## Deferred Items (Out of Scope Here)
- Frontend test coverage improvements (ProxyHostForm).
- Additional beta observability and import validation tasks.
## Actions After Approval
1. Confirm CI draft run passes.
2. Convert PR from draft to ready-for-review.
3. Merge into `feature/alpha-completion`.
## Request
Please focus review on secret usage, workflow call integrity, and artifact correctness. Comment with any missed token references.
---
Generated programmatically to aid structured review.

337
docs/database-schema.md
View File

@@ -1,337 +0,0 @@
# Database Schema Documentation
CaddyProxyManager+ uses SQLite with GORM ORM for data persistence. This document describes the database schema and relationships.
## Overview
The database consists of 8 main tables:
- ProxyHost
- RemoteServer
- CaddyConfig
- SSLCertificate
- AccessList
- User
- Setting
- ImportSession
## Entity Relationship Diagram
```
┌─────────────────┐
│ ProxyHost │
├─────────────────┤
│ UUID │◄──┐
│ Domain │ │
│ ForwardScheme │ │
│ ForwardHost │ │
│ ForwardPort │ │
│ SSLForced │ │
│ WebSocketSupport│ │
│ Enabled │ │
│ RemoteServerID │───┘ (optional)
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
│
│ 1:1
▼
┌─────────────────┐
│ CaddyConfig │
├─────────────────┤
│ UUID │
│ ProxyHostID │
│ RawConfig │
│ GeneratedAt │
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
┌─────────────────┐
│ RemoteServer │
├─────────────────┤
│ UUID │
│ Name │
│ Provider │
│ Host │
│ Port │
│ Reachable │
│ LastChecked │
│ Enabled │
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
┌─────────────────┐
│ SSLCertificate │
├─────────────────┤
│ UUID │
│ Name │
│ DomainNames │
│ CertPEM │
│ KeyPEM │
│ ExpiresAt │
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
┌─────────────────┐
│ AccessList │
├─────────────────┤
│ UUID │
│ Name │
│ Addresses │
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
┌─────────────────┐
│ User │
├─────────────────┤
│ UUID │
│ Email │
│ PasswordHash │
│ IsActive │
│ IsAdmin │
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
┌─────────────────┐
│ Setting │
├─────────────────┤
│ UUID │
│ Key │ (unique)
│ Value │
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
┌─────────────────┐
│ ImportSession │
├─────────────────┤
│ UUID │
│ Filename │
│ State │
│ CreatedAt │
│ UpdatedAt │
└─────────────────┘
```
## Table Details
### ProxyHost
Stores reverse proxy host configurations.
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `domain` | TEXT | Domain names (comma-separated) |
| `forward_scheme` | TEXT | http or https |
| `forward_host` | TEXT | Target server hostname/IP |
| `forward_port` | INTEGER | Target server port |
| `ssl_forced` | BOOLEAN | Force HTTPS redirect |
| `http2_support` | BOOLEAN | Enable HTTP/2 |
| `hsts_enabled` | BOOLEAN | Enable HSTS header |
| `hsts_subdomains` | BOOLEAN | Include subdomains in HSTS |
| `block_exploits` | BOOLEAN | Block common exploits |
| `websocket_support` | BOOLEAN | Enable WebSocket proxying |
| `enabled` | BOOLEAN | Proxy is active |
| `remote_server_id` | UUID | Foreign key to RemoteServer (nullable) |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
**Indexes:**
- Primary key on `uuid`
- Foreign key index on `remote_server_id`
**Relationships:**
- `RemoteServer`: Many-to-One (optional) - Links to remote Caddy instance
- `CaddyConfig`: One-to-One - Generated Caddyfile configuration
### RemoteServer
Stores remote Caddy server connection information.
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `name` | TEXT | Friendly name |
| `provider` | TEXT | generic, docker, kubernetes, aws, gcp, azure |
| `host` | TEXT | Hostname or IP address |
| `port` | INTEGER | Port number (default 2019) |
| `reachable` | BOOLEAN | Connection test result |
| `last_checked` | TIMESTAMP | Last connection test time |
| `enabled` | BOOLEAN | Server is active |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
**Indexes:**
- Primary key on `uuid`
- Index on `enabled` for fast filtering
### CaddyConfig
Stores generated Caddyfile configurations for each proxy host.
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `proxy_host_id` | UUID | Foreign key to ProxyHost |
| `raw_config` | TEXT | Generated Caddyfile content |
| `generated_at` | TIMESTAMP | When config was generated |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
**Indexes:**
- Primary key on `uuid`
- Unique index on `proxy_host_id`
### SSLCertificate
Stores SSL/TLS certificates (future enhancement).
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `name` | TEXT | Certificate name |
| `domain_names` | TEXT | Domains covered (comma-separated) |
| `cert_pem` | TEXT | Certificate in PEM format |
| `key_pem` | TEXT | Private key in PEM format |
| `expires_at` | TIMESTAMP | Certificate expiration |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
### AccessList
Stores IP-based access control lists (future enhancement).
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `name` | TEXT | List name |
| `addresses` | TEXT | IP addresses (comma-separated) |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
### User
Stores user authentication information (future enhancement).
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `email` | TEXT | Email address (unique) |
| `password_hash` | TEXT | Bcrypt password hash |
| `is_active` | BOOLEAN | Account is active |
| `is_admin` | BOOLEAN | Admin privileges |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
**Indexes:**
- Primary key on `uuid`
- Unique index on `email`
### Setting
Stores application-wide settings as key-value pairs.
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `key` | TEXT | Setting key (unique) |
| `value` | TEXT | Setting value (JSON string) |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
**Indexes:**
- Primary key on `uuid`
- Unique index on `key`
**Default Settings:**
- `app_name`: "CaddyProxyManager+"
- `default_scheme`: "http"
- `enable_ssl_by_default`: "false"
### ImportSession
Tracks Caddyfile import sessions.
| Column | Type | Description |
|--------|------|-------------|
| `uuid` | UUID | Primary key |
| `filename` | TEXT | Uploaded filename (optional) |
| `state` | TEXT | parsing, reviewing, completed, failed |
| `created_at` | TIMESTAMP | Creation timestamp |
| `updated_at` | TIMESTAMP | Last update timestamp |
**States:**
- `parsing`: Caddyfile is being parsed
- `reviewing`: Waiting for user to review/resolve conflicts
- `completed`: Import successfully committed
- `failed`: Import failed with errors
## Database Initialization
The database is automatically created and migrated when the application starts. Use the seed script to populate with sample data:
```bash
cd backend
go run ./cmd/seed/main.go
```
### Sample Seed Data
The seed script creates:
- 4 remote servers (Docker registry, API server, web app, database admin)
- 3 proxy hosts (app.local.dev, api.local.dev, docker.local.dev)
- 3 settings (app configuration)
- 1 admin user
## Migration Strategy
GORM AutoMigrate is used for schema migrations:
```go
db.AutoMigrate(
&models.ProxyHost{},
&models.RemoteServer{},
&models.CaddyConfig{},
&models.SSLCertificate{},
&models.AccessList{},
&models.User{},
&models.Setting{},
&models.ImportSession{},
)
```
This ensures the database schema stays in sync with model definitions.
## Backup and Restore
### Backup
```bash
cp backend/data/cpm.db backend/data/cpm.db.backup
```
### Restore
```bash
cp backend/data/cpm.db.backup backend/data/cpm.db
```
## Performance Considerations
- **Indexes**: All foreign keys and frequently queried columns are indexed
- **Connection Pooling**: GORM manages connection pooling automatically
- **SQLite Pragmas**: `PRAGMA journal_mode=WAL` for better concurrency
- **Query Optimization**: Use `.Preload()` for eager loading relationships
## Future Enhancements
- Multi-tenancy support with organization model
- Audit log table for tracking changes
- Certificate auto-renewal tracking
- Integration with Let's Encrypt
- Metrics and monitoring data storage

24
docs/debugging-local-container.md
View File

@@ -1,24 +0,0 @@
# Debugging the Local Docker Image
Use the `cpmp:local` image as the source of truth and attach VS Code debuggers directly to the running container.
## 1. Enable the debugger
The image now ships with the Delve debugger. When you start the container, set `CPMP_DEBUG=1` (and optionally `CPMP_DEBUG_PORT`) so CPM+ runs under Delve.
```bash
docker run --rm -it \
--name cpmp-debug \
-p 8080:8080 \
-p 2345:2345 \
-e CPM_ENV=development \
-e CPM_DEBUG=1 \
cpmp:local
```
Delve will listen on `localhost:2345`, while the UI remains available at `http://localhost:8080`.
## 2. Attach VS Code
- Use the **Attach to CPMP backend** configuration in `.vscode/launch.json` to connect the Go debugger to Delve.
- Use the **Open CPMP frontend** configuration to launch Chrome against the management UI.
These launch configurations assume the ports above are exposed. If you need a different port, set `CPMP_DEBUG_PORT` when running the container and update the Go configuration's `port` field accordingly.

234
docs/getting-started.md
View File

@@ -1,234 +0,0 @@
# 🏠 Getting Started with Caddy Proxy Manager Plus
**Welcome!** This guide will walk you through setting up your first proxy. Don't worry if you're new to this - we'll explain everything step by step!
---
## 🤔 What Is This App?
Think of this app as a **traffic controller** for your websites and apps.
**Here's a simple analogy:**
Imagine you have several houses (websites/apps) on different streets (servers). Instead of giving people complicated directions to each house, you have one main address (your domain) where a helpful guide (the proxy) sends visitors to the right house automatically.
**What you can do:**
- ✅ Make multiple websites accessible through one domain
- ✅ Route traffic from example.com to different servers
- ✅ Manage SSL certificates (the lock icon in browsers)
- ✅ Control who can access what
---
## 📋 Before You Start
You'll need:
1. **A computer** (Windows, Mac, or Linux)
2. **Docker installed** (it's like a magic box that runs apps)
- Don't have it? [Get Docker here](https://docs.docker.com/get-docker/)
3. **5 minutes** of your time
That's it! No programming needed.
---
### Step 1: Get the App Running
### The Easy Way (Recommended)
Open your **terminal** (or Command Prompt on Windows) and paste this:
```bash
docker run -d \
-p 8080:8080 \
-v caddy_data:/app/data \
--name caddy-proxy-manager \
ghcr.io/wikid82/cpmp:latest
```
**What does this do?** It downloads and starts the app. You don't need to understand the details - just copy and paste!
### Check If It's Working
1. Open your web browser
2. Go to: `http://localhost:8080`
3. You should see the app! 🎉
> **Didn't work?** Check if Docker is running. On Windows/Mac, look for the Docker icon in your taskbar.
---
## 🎯 Step 2: Create Your First Proxy Host
Let's set up your first proxy! We'll create a simple example.
### What's a Proxy Host?
A **Proxy Host** is like a forwarding address. When someone visits `mysite.com`, it secretly sends them to `192.168.1.100:3000` without them knowing.
### Let's Create One!
1. **Click "Proxy Hosts"** in the left sidebar
2. **Click "+ Add Proxy Host"** button (top right)
3. **Fill in the form:**
📝 **Domain Name:** (What people type in their browser)
```
myapp.local
```
> This is like your house's street address
📍 **Forward To:** (Where the traffic goes)
```
192.168.1.100
```
> This is where your actual app is running
🔢 **Port:** (Which door to use)
```
3000
```
> Apps listen on specific "doors" (ports) - 3000 is common for web apps
🌐 **Scheme:** (How to talk to it)
```
http
```
> Choose `http` for most apps, `https` if your app already has SSL
4. **Click "Save"**
**Congratulations!** 🎉 You just created your first proxy! Now when you visit `http://myapp.local`, it will show your app from `192.168.1.100:3000`.
---
## 🌍 Step 3: Set Up a Remote Server (Optional)
Sometimes your apps are on different computers (servers). Let's add one!
### What's a Remote Server?
Think of it as **telling the app about other computers** you have. Once added, you can easily send traffic to them.
### Adding a Remote Server
1. **Click "Remote Servers"** in the left sidebar
2. **Click "+ Add Server"** button
3. **Fill in the details:**
🏷️ **Name:** (A friendly name)
```
My Home Server
```
🌐 **Hostname:** (The address of your server)
```
192.168.1.50
```
📝 **Description:** (Optional - helps you remember)
```
The server in my office running Docker
```
4. **Click "Test Connection"** - this checks if the app can reach your server
5. **Click "Save"**
Now when creating proxy hosts, you can pick this server from a dropdown instead of typing the address every time!
---
## 📥 Step 4: Import Existing Caddy Files (If You Have Them)
Already using Caddy and have configuration files? You can bring them in!
### What's a Caddyfile?
It's a **text file that tells Caddy how to route traffic**. If you're not sure if you have one, you probably don't need this step.
### How to Import
1. **Click "Import Caddy Config"** in the left sidebar
2. **Choose your method:**
- **Drag & Drop:** Just drag your `Caddyfile` into the box
- **Paste:** Copy the contents and paste them in the text area
3. **Click "Parse Config"** - the app reads your file
4. **Review the results:**
- ✅ Green items = imported successfully
- ⚠️ Yellow items = need your attention (conflicts)
- ❌ Red items = couldn't import (will show why)
5. **Resolve any conflicts** (the app will guide you)
6. **Click "Import Selected"**
Done! Your existing setup is now in the app.
> **Need more help?** Check the detailed [Import Guide](import-guide.md)
---
## 💡 Tips for New Users
### 1. Start Small
Don't try to import everything at once. Start with one proxy host, make sure it works, then add more.
### 2. Use Test Connection
When adding remote servers, always click "Test Connection" to make sure the app can reach them.
### 3. Check Your Ports
Make sure the ports you use aren't already taken by other apps. Common ports:
- `80` - Web traffic (HTTP)
- `443` - Secure web traffic (HTTPS)
- `3000-3999` - Apps often use these
- `8080-8090` - Alternative web ports
### 4. Local Testing First
Test everything with local addresses (like `localhost` or `192.168.x.x`) before using real domain names.
### 5. Save Backups
The app stores everything in a database. The Docker command above saves it in `caddy_data` - don't delete this!
---
## 🐛 Something Not Working?
### App Won't Start
- **Check if Docker is running** - look for the Docker icon
- **Check if port 8080 is free** - another app might be using it
- **Try:** `docker ps` to see if it's running
### Can't Access the Website
- **Check your spelling** - domain names are picky
- **Check the port** - make sure the app is actually running on that port
- **Check the firewall** - might be blocking connections
### Import Failed
- **Check your Caddyfile syntax** - paste it at [Caddy Validate](https://caddyserver.com/docs/caddyfile)
- **Look at the error message** - it usually tells you what's wrong
- **Start with a simple file** - test with just one site first
---
## 📚 What's Next?
You now know the basics! Here's what to explore:
- 🔐 **Add SSL Certificates** - get the green lock icon
- 🚦 **Set Up Access Lists** - control who can visit your sites
- ⚙️ **Configure Settings** - customize the app
- 🔌 **Try the API** - control everything with code
---
## 🆘 Still Need Help?
We're here for you!
- 💬 [Ask on GitHub Discussions](https://github.com/Wikid82/CaddyProxyManagerPlus/discussions)
- 🐛 [Report a Bug](https://github.com/Wikid82/CaddyProxyManagerPlus/issues)
- 📖 [Read the Full Documentation](index.md)
---
<p align="center">
<strong>You're doing great! 🌟</strong><br>
<em>Remember: Everyone was a beginner once. Take your time and have fun!</em>
</p>

259
docs/github-setup.md
View File

@@ -1,259 +0,0 @@
# 🔧 GitHub Setup Guide
This guide will help you set up GitHub Actions for automatic Docker builds and documentation deployment.
---
## 📦 Step 1: Docker Image Publishing (Automatic!)
The Docker build workflow uses GitHub Container Registry (GHCR) to store your images. **No setup required!** GitHub automatically provides authentication tokens for GHCR.
### How It Works:
GitHub Actions automatically uses the built-in `CPMP_TOKEN` which has permission to:
- ✅ Push images to `ghcr.io/wikid82/caddyproxymanagerplus`
- ✅ Link images to your repository
- ✅ Publish images for free (public repositories)
**Nothing to configure!** Just push code and images will be built automatically.
### Make Your Images Public (Optional):
By default, container images are private. To make them public:
1. **Go to your repository** → https://github.com/Wikid82/CaddyProxyManagerPlus
2. **Look for "Packages"** on the right sidebar (after first build)
3. **Click your package name**
4. **Click "Package settings"** (right side)
5. **Scroll down to "Danger Zone"**
6. **Click "Change visibility"** → Select **"Public"**
**Why make it public?** Anyone can pull your Docker images without authentication!
---
## 📚 Step 2: Enable GitHub Pages (For Documentation)
Your documentation will be published to GitHub Pages (not the wiki). Pages is better for auto-deployment and looks more professional!
### Enable Pages:
1. **Go to your repository** → https://github.com/Wikid82/CaddyProxyManagerPlus
2. **Click "Settings"** (top menu)
3. **Click "Pages"** (left sidebar under "Code and automation")
4. **Under "Build and deployment":**
- **Source**: Select **"GitHub Actions"** (not "Deploy from a branch")
5. That's it! No other settings needed.
Once enabled, your docs will be live at:
```
https://wikid82.github.io/CaddyProxyManagerPlus/
```
**Note:** The first deployment takes 2-3 minutes. Check the Actions tab to see progress!
---
## 🚀 How the Workflows Work
### Docker Build Workflow (`.github/workflows/docker-build.yml`)
**Triggers when:**
- ✅ You push to `main` branch → Creates `latest` tag
- ✅ You push to `development` branch → Creates `dev` tag
- ✅ You create a version tag like `v1.0.0` → Creates version tags
- ✅ You manually trigger it from GitHub UI
**What it does:**
1. Builds the frontend
2. Builds a Docker image for multiple platforms (AMD64, ARM64)
3. Pushes to Docker Hub with appropriate tags
4. Tests the image by starting it and checking the health endpoint
5. Shows you a summary of what was built
**Tags created:**
- `latest` - Always the newest stable version (from `main`)
- `dev` - The development version (from `development`)
- `1.0.0`, `1.0`, `1` - Version numbers (from git tags)
- `sha-abc1234` - Specific commit versions
**Where images are stored:**
- `ghcr.io/wikid82/caddyproxymanagerplus:latest`
- `ghcr.io/wikid82/caddyproxymanagerplus:dev`
- `ghcr.io/wikid82/caddyproxymanagerplus:1.0.0`
### Documentation Workflow (`.github/workflows/docs.yml`)
**Triggers when:**
- ✅ You push changes to `docs/` folder
- ✅ You update `README.md`
- ✅ You manually trigger it from GitHub UI
**What it does:**
1. Converts all markdown files to beautiful HTML pages
2. Creates a nice homepage with navigation
3. Adds dark theme styling (matches the app!)
4. Publishes to GitHub Pages
5. Shows you the published URL
---
## 🎯 Testing Your Setup
### Test Docker Build:
1. Make a small change to any file
2. Commit and push to `development`:
```bash
git add .
git commit -m "test: trigger docker build"
git push origin development
```
3. Go to **Actions** tab on GitHub
4. Watch the "Build and Push Docker Images" workflow run
5. Check **Packages** on your GitHub profile for the new `dev` tag!
### Test Docs Deployment:
1. Make a small change to `README.md` or any doc file
2. Commit and push to `main`:
```bash
git add .
git commit -m "docs: update readme"
git push origin main
```
3. Go to **Actions** tab on GitHub
4. Watch the "Deploy Documentation to GitHub Pages" workflow run
5. Visit your docs site (shown in the workflow summary)!
---
## 🏷️ Creating Version Releases
When you're ready to release a new version:
1. **Tag your release:**
```bash
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
```
2. **The workflow automatically:**
- Builds Docker image
- Tags it as `1.0.0`, `1.0`, and `1`
- Pushes to Docker Hub
- Tests it works
3. **Users can pull it:**
```bash
docker pull ghcr.io/wikid82/caddyproxymanagerplus:1.0.0
docker pull ghcr.io/wikid82/caddyproxymanagerplus:latest
```
---
## 🐛 Troubleshooting
### Docker Build Fails
**Problem**: "Error: denied: requested access to the resource is denied"
- **Fix**: This shouldn't happen with `CPMP_TOKEN` - check workflow permissions
- **Verify**: Settings → Actions → General → Workflow permissions → "Read and write permissions" enabled
**Problem**: Can't pull the image
- **Fix**: Make the package public (see Step 1 above)
- **Or**: Authenticate with GitHub: `echo $CPMP_TOKEN | docker login ghcr.io -u USERNAME --password-stdin`
### Docs Don't Deploy
**Problem**: "deployment not found"
- **Fix**: Make sure you selected "GitHub Actions" as the source in Pages settings
- **Not**: "Deploy from a branch"
**Problem**: Docs show 404 error
- **Fix**: Wait 2-3 minutes after deployment completes
- **Fix**: Check the workflow summary for the actual URL
### General Issues
**Check workflow logs:**
1. Go to **Actions** tab
2. Click the failed workflow
3. Click the failed job
4. Expand the step that failed
5. Read the error message
**Still stuck?**
- Open an issue: https://github.com/Wikid82/CaddyProxyManagerPlus/issues
- We're here to help!
---
## 📋 Quick Reference
### Docker Commands
```bash
# Pull latest development version
docker pull ghcr.io/wikid82/caddyproxymanagerplus:dev
# Pull stable version
docker pull ghcr.io/wikid82/cpmp:latest
# Pull specific version
docker pull ghcr.io/wikid82/cpmp:1.0.0
# Run the container
docker run -d -p 8080:8080 -v caddy_data:/app/data ghcr.io/wikid82/cpmp:latest
```
### Git Tag Commands
```bash
# Create a new version tag
git tag -a v1.2.3 -m "Release 1.2.3"
# Push the tag
git push origin v1.2.3
# List all tags
git tag -l
# Delete a tag (if you made a mistake)
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3
```
### Trigger Manual Workflow
1. Go to **Actions** tab
2. Click the workflow name (left sidebar)
3. Click "Run workflow" button (right side)
4. Select branch
5. Click "Run workflow"
---
## ✅ Checklist
Before pushing to production, make sure:
- [ ] GitHub Pages is enabled with "GitHub Actions" source
- [ ] You've tested the Docker build workflow (automatic on push)
- [ ] You've tested the docs deployment workflow
- [ ] Container package is set to "Public" visibility (optional, for easier pulls)
- [ ] Documentation looks good on the published site
- [ ] Docker image runs correctly
- [ ] You've created your first version tag
---
## 🎉 You're Done!
Your CI/CD pipeline is now fully automated! Every time you:
- Push to `main` → New `latest` Docker image + updated docs
- Push to `development` → New `dev` Docker image for testing
- Create a tag → New versioned Docker image
**No manual building needed!** 🚀
<p align="center">
<em>Questions? Check the <a href="https://docs.github.com/en/actions">GitHub Actions docs</a> or <a href="https://github.com/Wikid82/CaddyProxyManagerPlus/issues">open an issue</a>!</em>
</p>

429
docs/import-guide.md
View File

@@ -1,429 +0,0 @@
# Caddyfile Import Guide
This guide explains how to import existing Caddyfiles into CaddyProxyManager+, handle conflicts, and troubleshoot common issues.
## Table of Contents
- [Overview](#overview)
- [Import Methods](#import-methods)
- [Import Workflow](#import-workflow)
- [Conflict Resolution](#conflict-resolution)
- [Supported Caddyfile Syntax](#supported-caddyfile-syntax)
- [Limitations](#limitations)
- [Troubleshooting](#troubleshooting)
- [Examples](#examples)
## Overview
CaddyProxyManager+ can import existing Caddyfiles and convert them into managed proxy host configurations. This is useful when:
- Migrating from standalone Caddy to CaddyProxyManager+
- Importing configurations from other systems
- Bulk importing multiple proxy hosts
- Sharing configurations between environments
## Import Methods
### Method 1: File Upload
1. Navigate to **Import Caddyfile** page
2. Click **Choose File** button
3. Select your Caddyfile (any text file)
4. Click **Upload**
### Method 2: Paste Content
1. Navigate to **Import Caddyfile** page
2. Click **Paste Caddyfile** tab
3. Paste your Caddyfile content into the textarea
4. Click **Preview Import**
## Import Workflow
The import process follows these steps:
### 1. Upload/Paste
Upload your Caddyfile or paste the content directly.
```caddyfile
# Example Caddyfile
example.com {
reverse_proxy localhost:8080
}
api.example.com {
reverse_proxy https://backend:9000
}
```
### 2. Parsing
The system parses your Caddyfile and extracts:
- Domain names
- Reverse proxy directives
- TLS settings
- Headers and other directives
**Parsing States:**
- ✅ **Success** - All hosts parsed correctly
- ⚠️ **Partial** - Some hosts parsed, others failed
- ❌ **Failed** - Critical parsing error
### 3. Preview
Review the parsed configurations:
| Domain | Forward Host | Forward Port | SSL | Status |
|--------|--------------|--------------|-----|--------|
| example.com | localhost | 8080 | No | New |
| api.example.com | backend | 9000 | Yes | New |
### 4. Conflict Detection
The system checks if any imported domains already exist:
- **No Conflicts** - All domains are new, safe to import
- **Conflicts Found** - One or more domains already exist
### 5. Conflict Resolution
For each conflict, choose an action:
| Domain | Existing Config | New Config | Action |
|--------|-----------------|------------|--------|
| example.com | localhost:3000 | localhost:8080 | [Keep Existing ▼] |
**Resolution Options:**
- **Keep Existing** - Don't import this host, keep current configuration
- **Overwrite** - Replace existing configuration with imported one
- **Skip** - Don't import this host, keep existing unchanged
- **Create New** - Import as a new host with modified domain name
### 6. Commit
Once all conflicts are resolved, click **Commit Import** to finalize.
**Post-Import:**
- Imported hosts appear in Proxy Hosts list
- Configurations are saved to database
- Caddy configs are generated automatically
## Conflict Resolution
### Strategy: Keep Existing
Use when you want to preserve your current configuration and ignore the imported one.
```
Current: example.com → localhost:3000
Imported: example.com → localhost:8080
Result: example.com → localhost:3000 (unchanged)
```
### Strategy: Overwrite
Use when the imported configuration is newer or more correct.
```
Current: example.com → localhost:3000
Imported: example.com → localhost:8080
Result: example.com → localhost:8080 (replaced)
```
### Strategy: Skip
Same as "Keep Existing" - imports everything except conflicting hosts.
### Strategy: Create New (Future)
Renames the imported host to avoid conflicts (e.g., `example.com` → `example-2.com`).
## Supported Caddyfile Syntax
### Basic Reverse Proxy
```caddyfile
example.com {
reverse_proxy localhost:8080
}
```
**Parsed as:**
- Domain: `example.com`
- Forward Host: `localhost`
- Forward Port: `8080`
- Forward Scheme: `http`
### HTTPS Upstream
```caddyfile
secure.example.com {
reverse_proxy https://backend:9000
}
```
**Parsed as:**
- Domain: `secure.example.com`
- Forward Host: `backend`
- Forward Port: `9000`
- Forward Scheme: `https`
### Multiple Domains
```caddyfile
example.com, www.example.com {
reverse_proxy localhost:8080
}
```
**Parsed as:**
- Domain: `example.com, www.example.com`
- Forward Host: `localhost`
- Forward Port: `8080`
### TLS Configuration
```caddyfile
example.com {
tls internal
reverse_proxy localhost:8080
}
```
**Parsed as:**
- SSL Forced: `true`
- TLS provider: `internal` (self-signed)
### Headers and Directives
```caddyfile
example.com {
header {
X-Custom-Header "value"
}
reverse_proxy localhost:8080 {
header_up Host {host}
}
}
```
**Note:** Custom headers and advanced directives are stored in the raw CaddyConfig but may not be editable in the UI initially.
## Limitations
### Current Limitations
1. **Path-based routing** - Not yet supported
```caddyfile
example.com {
route /api/* {
reverse_proxy localhost:8080
}
route /static/* {
file_server
}
}
```
2. **File server blocks** - Only reverse_proxy supported
```caddyfile
static.example.com {
file_server
root * /var/www/html
}
```
3. **Advanced matchers** - Basic domain matching only
```caddyfile
@api {
path /api/*
header X-API-Key *
}
reverse_proxy @api localhost:8080
```
4. **Import statements** - Must be resolved before import
```caddyfile
import snippets/common.caddy
```
5. **Environment variables** - Must be hardcoded
```caddyfile
{$DOMAIN} {
reverse_proxy {$BACKEND_HOST}
}
```
### Workarounds
- **Path routing**: Create multiple proxy hosts per path
- **File server**: Use separate Caddy instance or static host tool
- **Matchers**: Manually configure in Caddy after import
- **Imports**: Flatten your Caddyfile before importing
- **Variables**: Replace with actual values before import
## Troubleshooting
### Error: "Failed to parse Caddyfile"
**Cause:** Invalid Caddyfile syntax
**Solution:**
1. Validate your Caddyfile with `caddy validate --config Caddyfile`
2. Check for missing braces `{}`
3. Ensure reverse_proxy directives are properly formatted
### Error: "No hosts found in Caddyfile"
**Cause:** Only contains directives without reverse_proxy blocks
**Solution:**
- Ensure you have at least one `reverse_proxy` directive
- Remove file_server-only blocks
- Add domain blocks with reverse_proxy
### Warning: "Some hosts could not be imported"
**Cause:** Partial import with unsupported features
**Solution:**
- Review the preview to see which hosts failed
- Simplify complex directives
- Import compatible hosts, add others manually
### Conflict Resolution Stuck
**Cause:** Not all conflicts have resolution selected
**Solution:**
- Ensure every conflicting host has a resolution dropdown selection
- The "Commit Import" button enables only when all conflicts are resolved
## Examples
### Example 1: Simple Migration
**Original Caddyfile:**
```caddyfile
app.example.com {
reverse_proxy localhost:3000
}
api.example.com {
reverse_proxy localhost:8080
}
```
**Import Result:**
- 2 hosts imported successfully
- No conflicts
- Ready to use immediately
### Example 2: HTTPS Upstream
**Original Caddyfile:**
```caddyfile
secure.example.com {
reverse_proxy https://internal.corp:9000 {
transport http {
tls_insecure_skip_verify
}
}
}
```
**Import Result:**
- Domain: `secure.example.com`
- Forward: `https://internal.corp:9000`
- Note: `tls_insecure_skip_verify` stored in raw config
### Example 3: Multi-domain with Conflict
**Original Caddyfile:**
```caddyfile
example.com, www.example.com {
reverse_proxy localhost:8080
}
```
**Existing Configuration:**
- `example.com` already points to `localhost:3000`
**Resolution:**
1. System detects conflict on `example.com`
2. Choose **Overwrite** to use new config
3. Commit import
4. Result: `example.com, www.example.com → localhost:8080`
### Example 4: Complex Setup (Partial Import)
**Original Caddyfile:**
```caddyfile
# Supported
app.example.com {
reverse_proxy localhost:3000
}
# Supported
api.example.com {
reverse_proxy https://backend:8080
}
# NOT supported (file server)
static.example.com {
file_server
root * /var/www
}
# NOT supported (path routing)
multi.example.com {
route /api/* {
reverse_proxy localhost:8080
}
route /web/* {
reverse_proxy localhost:3000
}
}
```
**Import Result:**
- ✅ `app.example.com` imported
- ✅ `api.example.com` imported
- ❌ `static.example.com` skipped (file_server not supported)
- ❌ `multi.example.com` skipped (path routing not supported)
- **Action:** Add unsupported hosts manually through UI or keep separate Caddyfile
## Best Practices
1. **Validate First** - Run `caddy validate` before importing
2. **Backup** - Keep a backup of your original Caddyfile
3. **Simplify** - Remove unsupported directives before import
4. **Test Small** - Import a few hosts first to verify
5. **Review Preview** - Always check the preview before committing
6. **Resolve Conflicts Carefully** - Understand impact before overwriting
7. **Document Custom Config** - Note any advanced directives that can't be edited in UI
## Getting Help
If you encounter issues:
1. Check this guide's [Troubleshooting](#troubleshooting) section
2. Review [Supported Syntax](#supported-caddyfile-syntax)
3. Open an issue on GitHub with:
- Your Caddyfile (sanitized)
- Error messages
- Expected vs actual behavior
## Future Enhancements
Planned improvements to import functionality:
- [ ] Path-based routing support
- [ ] Custom header import/export
- [ ] Environment variable resolution
- [ ] Import from URL
- [ ] Export to Caddyfile
- [ ] Diff view for conflicts
- [ ] Batch import from multiple files
- [ ] Import validation before upload

117
docs/index.md
View File

@@ -1,117 +0,0 @@
# 📚 Caddy Proxy Manager Plus - Documentation
Welcome! 👋 This page will help you find exactly what you need to use Caddy Proxy Manager Plus.
---
## 🚀 I'm New Here - Where Do I Start?
Start with the [**README**](../README.md) - it's like the front door of our project! It will show you:
- What this app does (in simple terms!)
- How to install it on your computer
- How to get it running in 5 minutes
**Next Step:** Once you have it running, check out the guides below!
---
## 📖 How-To Guides
### For Everyone
#### [🏠 Getting Started Guide](getting-started.md)
*Coming soon!* - A step-by-step walkthrough of your first proxy setup. We'll hold your hand through the whole process!
#### [📥 Import Your Caddy Files](import-guide.md)
Already have Caddy configuration files? This guide shows you how to bring them into the app so you don't have to start from scratch.
**What you'll learn:**
- How to upload your existing files (it's just drag-and-drop!)
- What to do if the app finds conflicts
- Tips to make importing super smooth
---
### For Developers & Advanced Users
#### [🔌 API Documentation](api.md)
Want to talk to the app using code? This guide shows all the ways you can send and receive information from the app.
**What you'll learn:**
- All the different commands you can send
- Examples in JavaScript and Python
- What responses to expect
#### [💾 Database Guide](database-schema.md)
Curious about how the app stores your information? This guide explains the database structure.
**What you'll learn:**
- What information we save
- How everything connects together
- Tips for backing up your data
---
## 🤝 Want to Help Make This Better?
#### [✨ Contributing Guide](../CONTRIBUTING.md)
We'd love your help! This guide shows you how to:
- Report bugs (things that don't work right)
- Suggest new features
- Submit code improvements
- Follow our project rules
---
## 🆘 Need Help?
### Quick Troubleshooting
**Can't get it to run?**
- Check the [Installation section in README](../README.md#-installation)
- Make sure Docker is installed and running
- Try the quick start commands exactly as written
**Having import problems?**
- See the [Import Guide troubleshooting section](import-guide.md#troubleshooting)
- Check your Caddy file is valid
- Look at the example files in the guide
**Found a bug?**
- [Open an issue on GitHub](https://github.com/Wikid82/CaddyProxyManagerPlus/issues)
- Tell us what you were trying to do
- Share any error messages you see
---
## 📚 All Documentation Files
### User Documentation
- [📖 README](../README.md) - Start here!
- [📥 Import Guide](import-guide.md) - Bring in existing configs
- [🏠 Getting Started](getting-started.md) - *Coming soon!*
### Developer Documentation
- [🔌 API Reference](api.md) - REST API endpoints
- [💾 Database Schema](database-schema.md) - How data is stored
- [✨ Contributing](../CONTRIBUTING.md) - Help make this better
- [🔧 GitHub Setup](github-setup.md) - Set up Docker builds & docs deployment
### Project Information
- [📄 LICENSE](../LICENSE) - Legal stuff (MIT License)
- [🔖 Changelog](../CHANGELOG.md) - *Coming soon!* - What's new in each version
---
## 💡 Quick Links
- [🏠 Project Home](https://github.com/Wikid82/CaddyProxyManagerPlus)
- [🐛 Report a Bug](https://github.com/Wikid82/CaddyProxyManagerPlus/issues/new)
- [💬 Ask a Question](https://github.com/Wikid82/CaddyProxyManagerPlus/discussions)
---
<p align="center">
<strong>Made with ❤️ for the community</strong><br>
<em>Questions? Open an issue - we're here to help!</em>
</p>