GoDoxy

https://docs.godoxy.dev/
Admin
GoDoxy is a smart reverse proxy for Docker that automatically manages routes, saves resources, and...
Tokens:57,913
Snippets:596
Trust Score:3.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run Automatic Setup Script

Source: https://docs.godoxy.dev/docs/godoxy/Setup

Executes the GoDoxy setup script directly from the repository.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/yusing/godoxy/main/scripts/setup.sh)"
```

--------------------------------

### POST /api/v1/proxmox/lxc/:node/:vmid/start

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Proxmox

Starts a specified container.

```APIDOC
## POST /api/v1/proxmox/lxc/:node/:vmid/start

### Description
Starts the specified container on the given node.

### Method
POST

### Endpoint
/api/v1/proxmox/lxc/:node/:vmid/start

### Parameters
#### Path Parameters
- **node** (string) - Required - The identifier of the Proxmox node.
- **vmid** (string) - Required - The container ID.
```

--------------------------------

### Modify HTML Configuration Examples

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/middlewares/content-modification/Modify-HTML

Examples demonstrating how to inject CSS into the head element and replace the content of a main element.

```yaml
# Inject CSS into head
proxy.myapp.middlewares.modify_html: |
  target: head
  html: '<style>body { background: red; }</style>'

# Replace main content
proxy.myapp.middlewares.modify_html: |
  target: main
  html: '<section><h2>New</h2></section>'
  replace: true
```

--------------------------------

### POST /docker/start

Source: https://docs.godoxy.dev/docs/openapi/start

Starts a container by its ID.

```APIDOC
## POST /docker/start

### Description
Starts a container by its container id.

### Method
POST

### Endpoint
https://docs.godoxy.dev/api/v1/docker/start

### Request Body
- **id** (string) - Required - The ID of the container to start.
- **checkpointDir** (string) - Optional - Directory for the checkpoint.
- **checkpointID** (string) - Optional - ID of the checkpoint.

### Request Example
{
  "id": "string"
}

### Response
#### Success Response (200)
- **details** (object) - Container details.
- **message** (string) - Success message.

#### Response Example
{
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
```

--------------------------------

### Log Action Example

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing/Actions

Standard inline configuration for the log action.

```text
log info /dev/stdout "$req_method $req_url $status_code"
```

--------------------------------

### Start container via cURL

Source: https://docs.godoxy.dev/docs/openapi/start

Use this cURL command to initiate a container start request to the GoDoxy API.

```bash
curl -X POST "https://docs.godoxy.dev/api/v1/docker/start" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "string"
  }'
```

--------------------------------

### Manual Configuration Setup

Source: https://docs.godoxy.dev/docs/godoxy/Setup

Commands to initialize the configuration directory and download required files for a manual deployment.

```bash
mkdir -p config && wget https://raw.githubusercontent.com/yusing/godoxy/main/config.example.yml -O config/config.yml
```

```bash
wget https://raw.githubusercontent.com/yusing/godoxy/main/.env.example -O .env
```

```bash
wget https://raw.githubusercontent.com/yusing/godoxy/main/compose.example.yml -O compose.yml
```

--------------------------------

### Common Benchmark Invocations

Source: https://docs.godoxy.dev/docs/godoxy/Benchmarks-and-Resource-Usage

Examples of configuring benchmark presets, protocol support, and connection modes.

```bash
# Presets: smoke (default), stable, stress
shadowtree benchmark preset=stable
shadowtree benchmark preset=smoke
shadowtree benchmark preset=stress

# Protocol toggles (defaults: h1/h2/h3 on, h1c off)
shadowtree benchmark h1=false
shadowtree benchmark h2=false
shadowtree benchmark h3=false
shadowtree benchmark h1c=true           # cleartext HTTP/1.1 on :8080-:8083
shadowtree benchmark h1c=false

# Connection mode (default: both)
shadowtree benchmark connection_mode=reused
shadowtree benchmark connection_mode=fresh
shadowtree benchmark connection_mode=both

# Combine typed args
shadowtree benchmark preset=stable h1=false h3=false
```

--------------------------------

### GET /system/info

Source: https://docs.godoxy.dev/docs/openapi/byProvider

Retrieves general system information.

```APIDOC
## GET /system/info

### Description
Retrieves general system information.

### Method
GET

### Endpoint
/system/info
```

--------------------------------

### Start LXC Container cURL Request

Source: https://docs.godoxy.dev/docs/openapi/lxcStart

Use this cURL command to initiate the start process for a specific LXC container.

```bash
curl -X POST "https://docs.godoxy.dev/api/v1/proxmox/lxc/:node/:vmid/start"
```

--------------------------------

### Response body examples

Source: https://docs.godoxy.dev/docs/openapi/check

Example response bodies returned by the authentication check endpoint.

```text
"string"
```

```text
"string"
```

--------------------------------

### Handle Action Example

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing/Actions

Usage of the handle action for internal HTTP handlers.

```text
path glob("/api/v1/*") {
  handle api
}
```

--------------------------------

### Define a basic GoDoxy configuration

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-GoDoxy

A minimal configuration example showing the required providers section.

```yaml
providers:
  docker:
    local: $DOCKER_HOST
```

--------------------------------

### API Response Examples

Source: https://docs.godoxy.dev/docs/openapi/get

Examples of successful and error response bodies returned by the API.

```json
"string"
```

```json
{
  "error": "string",
  "message": "string"
}
```

--------------------------------

### GET /system/info

Source: https://docs.godoxy.dev/docs/openapi

Retrieves general system information for the GoDoxy instance.

```APIDOC
## GET /system/info

### Description
Retrieves general system information for the GoDoxy instance.

### Method
GET

### Endpoint
/system/info
```

--------------------------------

### Route File Configuration

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/Load-Balancing

Example of defining multiple backend hosts in a YAML configuration file.

```yaml
# config/loadbalancer.yml
whoami-1:
  host: 10.0.2.1
  port: 80
  load_balance:
    link: whoami
    mode: round_robin

whoami-2:
  host: 10.0.2.2
  port: 80
  load_balance:
    link: whoami
    mode: round_robin

whoami-3:
  host: 10.0.2.3
  port: 80
  load_balance:
    link: whoami
    mode: round_robin
```

--------------------------------

### Pattern Matching Examples

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing

Illustrates the use of string, glob, and regex patterns for matching request headers and paths.

```text
# String matching (default)
header X-API-Key "secret-key"

# Glob pattern matching
header User-Agent glob(Mozilla*)
path glob(/api/v[0-9]/*)

# Regular expression matching
header X-API-Key regex("^sk-[a-zA-Z0-9]{32}$")
path regex("^/api/v[0-9]+/users/[a-f0-9-]{36}$")
```

--------------------------------

### Expected Behavior Configuration

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/middlewares/ip-resolution/Real-IP

Example configuration and header input for testing recursive IP resolution logic.

```yaml
from: 192.168.0.0/16, 10.0.0.1
header: X-Forwarded-For
```

```text
X-Forwarded-For: 1.2.3.4, 192.168.0.123, 10.0.0.123
```

--------------------------------

### Successful response example

Source: https://docs.godoxy.dev/docs/openapi/journalctl

The expected response format for a successful request.

```json
"string"
```

--------------------------------

### Docker Compose with Multiple Replicas

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/Load-Balancing

Example configuration for deploying multiple replicas with load balancing labels.

```yaml
services:
  whoami:
    image: traefik/whoami
    deploy:
      replicas: 10
    labels:
      proxy.*.load_balance: |
        link: whoami
        mode: round_robin
    ports:
      - "80"
    restart: unless-stopped
```

--------------------------------

### Auth Callback Response Examples

Source: https://docs.godoxy.dev/docs/openapi/callback

Standard string response returned by the authentication callback endpoint.

```text
"string"
```

```text
"string"
```

```text
"string"
```

```text
"string"
```

--------------------------------

### Configure Basic Authentication Rule

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing/Conditions

Example of enforcing basic authentication and allowing specific users.

```text
default {
  require_basic_auth "Restricted Area"
}

basic_auth user1 "$2y$10$..." | basic_auth user2 "$2y$10$..." {
  pass
}
```

--------------------------------

### Development Environment Configuration

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/Idle-Sleep

Example configuration for a development API and database service using custom idle and stop settings.

```yaml
services:
  dev-api:
    image: myapp/api:latest
    labels:
      proxy.idle_timeout: 30m
      proxy.wake_timeout: 60s
      proxy.stop_method: kill
      proxy.stop_timeout: 5s
    depends_on:
      dev-db:
        condition: service_healthy
  dev-db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
```

--------------------------------

### Route File Directory Structure

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-Routes

Example directory layout for organizing route files within the config folder.

```text
config/
├── pve.yml        # Proxmox VE hosts
├── lxc.yml        # LXC containers
├── vps.yml        # Remote VPS instances
└── custom.yml     # Custom applications
```

--------------------------------

### POST /proxmox/lxc/:node/:vmid/start

Source: https://docs.godoxy.dev/docs/openapi/lxcStart

Starts an LXC container on the specified Proxmox node using the provided VM ID.

```APIDOC
## POST /proxmox/lxc/:node/:vmid/start

### Description
Starts an LXC container by node and vmid.

### Method
POST

### Endpoint
https://docs.godoxy.dev/api/v1/proxmox/lxc/:node/:vmid/start

### Parameters
#### Path Parameters
- **node** (string) - Required - The name of the Proxmox node.
- **vmid** (integer) - Required - The ID of the LXC container.

### Request Example
```bash
curl -X POST "https://docs.godoxy.dev/api/v1/proxmox/lxc/:node/:vmid/start"
```

### Response
#### Success Response (200)
- **details** (object) - Container details
- **message** (string) - Success message

#### Response Example
{
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
```

--------------------------------

### GET /metrics/all_system_info

Source: https://docs.godoxy.dev/docs/openapi/all_system_info

Retrieves aggregated system metrics based on specified parameters.

```APIDOC
## GET /metrics/all_system_info

### Description
Retrieves system information metrics such as CPU usage, memory, disk, and network statistics.

### Method
GET

### Endpoint
/metrics/all_system_info

### Parameters
#### Query Parameters
- **aggregate** (string) - Optional - One of: "cpu_average", "memory_usage", "memory_usage_percent", "disks_read_speed", "disks_write_speed", "disks_iops", "disk_usage", "network_speed", "network_transfer", "sensor_temperature"
- **interval** (string) - Optional - Duration format
- **period** (string) - Optional - One of: "5m", "15m", "1h", "1d", "1mo"

### Response
#### Success Response (200)
- **property1** (object) - System metric data
- **property2** (object) - System metric data

#### Response Example
{
  "property1": {
    "data": [
      {
        "property1": null,
        "property2": null
      }
    ],
    "total": 0
  },
  "property2": {
    "data": [
      {
        "property1": null,
        "property2": null
      }
    ],
    "total": 0
  }
}
```

--------------------------------

### Configure Autocert with Custom Internal CA

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/Certificates

Setup for using a custom ACME CA like step-ca. Requires fetching root certificates and providing the directory URL.

```bash
export ACME_URL=https://acme.internal
# get root certs and save to `certs/roots.pem`
# assume that `certs/` is mounted to `/app/certs` (by default)
curl -k https://${ACME_URL}/roots.pem > certs/roots.pem
```

```yaml
autocert:
  provider: custom
  email: your-email@example.com
  domains:
    - "*.yourdomain.com"
  ca_dir_url: https://acme.internal/acme/acme/directory
  ca_certs:
    - certs/roots.pem
```

--------------------------------

### GET /webui/config

Source: https://docs.godoxy.dev/docs/openapi/config

Retrieves the current WebUI configuration settings from the GoDoxy server.

```APIDOC
## GET /webui/config

### Description
Retrieves the WebUI configuration including access log settings, aliases, display name, mTLS profiles, and middleware configurations.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/webui/config

### Response
#### Success Response (200)
- **access_log** (object) - Configuration for access logging including fields, filters, format, path, retention, and rotation.
- **aliases** (array) - List of aliases.
- **display_name** (string) - The display name of the configuration.
- **inbound_mtls_profile** (string) - The inbound mTLS profile identifier.
- **middlewares** (object) - Middleware configurations.
- **rules** (array) - List of defined rules.

#### Response Example
{
  "access_log": {
    "fields": {
      "cookies": {
        "config": {
          "property1": "keep",
          "property2": "keep"
        },
        "default": "keep"
      },
      "headers": {
        "config": {
          "property1": "keep",
          "property2": "keep"
        },
        "default": "keep"
      },
      "query": {
        "config": {
          "property1": "keep",
          "property2": "keep"
        },
        "default": "keep"
      }
    },
    "filters": {
      "cidr": {
        "negative": true,
        "values": [
          {
            "ip": [0],
            "mask": [0]
          }
        ]
      },
      "headers": {
        "negative": true,
        "values": [
          {
            "key": "string",
            "value": "string"
          }
        ]
      },
      "host": {
        "negative": true,
        "values": ["string"]
      },
      "method": {
        "negative": true,
        "values": ["string"]
      },
      "status_codes": {
        "negative": true,
        "values": [
          {
            "end": 0,
            "start": 0
          }
        ]
      }
    },
    "format": "common",
    "path": "string",
    "retention": {
      "days": 0,
      "keep_size": 0,
      "last": 0
    },
    "rotate_interval": 0,
    "stdout": true
  },
  "aliases": ["string"],
  "display_name": "string",
  "inbound_mtls_profile": "string",
  "middlewares": {
    "property1": {
      "property1": null,
      "property2": null
    },
    "property2": {
      "property1": null,
      "property2": null
    }
  },
  "rules": [
    {
      "do": "string",
      "name": "string",
      "on": "string"
    }
  ]
}
```

--------------------------------

### List route cURL request

Source: https://docs.godoxy.dev/docs/openapi/route

Example cURL command to fetch route details.

```bash
curl -X GET "https://docs.godoxy.dev/api/v1/route/string"
```

--------------------------------

### Staging Environment with Wake Endpoint

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/Idle-Sleep

Example configuration for a staging application specifying a custom wake endpoint and idle timeout.

```yaml
services:
  staging-app:
    image: myapp/staging:latest
    labels:
      proxy.idle_timeout: 2h
      proxy.start_endpoint: /api/wake
      proxy.no_loading_page: false
```

--------------------------------

### GoDoxy Action Variable Usage Examples

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing/Actions

Demonstrates various ways to reference request and response metadata in logging, notifications, and header/body modifications.

```text
# Logging with request and response information
log info /dev/stdout "Method=$req_method Path=$req_path Status=$status_code"

# Logging with headers (redacting sensitive values)
log info /dev/stdout "User-Agent=$header(User-Agent) Auth=$redacted($header(Authorization))"

# Logging with response headers
log info /dev/stdout "Content-Type=$resp_header(Content-Type) Content-Length=$resp_content_length"

# Notifications with request context
notify info ntfy "New request" "From $remote_host to $req_host at $req_path"

# Setting headers with upstream information
set header X-Upstream-URL $upstream_url
set header X-Request-Path $req_path

# Body modifications with request info
set body "Status: $status_code for $req_method $req_path"

# Response body with request and response info
set resp_body "Request: $req_method $req_url\nResponse: $status_code"
```

--------------------------------

### Configure Docker provider with TLS

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-GoDoxy

Example of a structured Docker provider configuration requiring TLS certificates.

```yaml
providers:
  docker:
    local: ${DOCKER_HOST}
    remote_secured:
      scheme: https
      host: 10.0.2.1
      port: 2375
      tls:
        ca_file: /path/to/ca.pem
        cert_file: /path/to/cert.pem
        key_file: /path/to/key.pem
```

--------------------------------

### Retrieve uptime metrics via cURL

Source: https://docs.godoxy.dev/docs/openapi/uptime

Example request to fetch uptime data with specified interval, limit, and offset parameters.

```bash
curl -X GET "https://docs.godoxy.dev/api/v1/metrics/uptime?interval=1m&keyword=&limit=10&offset=10"
```

--------------------------------

### Update Docker Compose configuration for v0.29.0

Source: https://docs.godoxy.dev/docs/godoxy/migration/v0.29.0

Example configuration showing the removal of the frontend service and the use of LISTEN_ADDR for socket-proxy and app services.

```yaml
services:
  socket-proxy:
    image: ghcr.io/yusing/socket-proxy:latest
    ports:
      - ${LISTEN_ADDR:-127.0.0.1:2375}:2375
    volumes:
      - ${DOCKER_SOCKET:-/var/run/docker.sock}:/var/run/docker.sock
    # … full env and options in compose.example.yml

  app:
    image: ghcr.io/yusing/godoxy:${TAG:-latest}
    network_mode: host # do not change this
    env_file: .env
    environment:
      - DOCKER_HOST=tcp://${LISTEN_ADDR:-127.0.0.1:2375}
    # WebUI: set webui.aliases in config/config.yml (embedded assets in this image)
    volumes:
      - ./config:/app/config
      # … logs, error_pages, data, certs: see compose.example.yml

  # no more frontend service
```

--------------------------------

### Configure basic global and per-service middlewares

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/middlewares

Demonstrates setting global middlewares in the entrypoint and per-service middlewares using Docker labels.

```yaml
# Global middleware (entrypoint)
entrypoint:
  middlewares:
    - use: real_ip
      header: X-Real-IP
      from: [127.0.0.1, 192.168.0.0/16]

# Per-service (Docker labels)
services:
  app:
    labels:
      proxy.myapp.middlewares.redirect_http.priority: 1
      proxy.myapp.middlewares.cidr_whitelist.priority: 2
      proxy.myapp.middlewares.cidr_whitelist.allow: 127.0.0.1, 192.168.0.0/16
```

--------------------------------

### Reuse middleware compositions

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/middlewares

Examples of referencing a composed middleware set across Docker labels, route files, and entrypoint configurations.

```yaml
# Docker labels
proxy.#1.middlewares.myWhitelist@file:

# Route file
myapp:
  middlewares:
    myWhitelist@file:

# Entrypoint
entrypoint:
  middlewares:
    - use: myWhitelist@file
```

--------------------------------

### Configure infrastructure providers

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-GoDoxy

Sets up various providers including Docker, agents, notifications, Proxmox, and MaxMind.

```yaml
providers:
  include:
    - file1.yml
    - file2.yml

  docker:
    local: ${DOCKER_HOST}
    remote-1: tcp://10.0.2.1:2375
    remote-2: ssh://root:1234@10.0.2.2

  agents:
    - 10.0.0.1:8899
    - 10.0.0.2:8899

  notification:
    - name: gotify
      provider: gotify
      url: https://gotify.example.com
      token: your-token

  proxmox:
    - url: https://pve.domain.com:8006/api2/json
      token_id: root@pam!abcdef
      secret: aaaa-bbbb-cccc-dddd
      no_tls_verify: true

  maxmind:
    account_id: 123456
    license_key: your-license-key
    database: geolite # or geoip2 if you have subscription
```

--------------------------------

### Get file content via cURL

Source: https://docs.godoxy.dev/docs/openapi/get

Use this cURL command to perform a GET request to retrieve file content.

```bash
curl -X GET "https://docs.godoxy.dev/api/v1/file/content?filename=string&type=config"
```

--------------------------------

### Define entrypoint and composed middlewares

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/middlewares

Shows how to define middlewares directly in the entrypoint configuration and how to create reusable middleware compositions in separate files.

```yaml
# Entrypoint (config.yml)
entrypoint:
  middlewares:
    - use: CloudflareRealIP
    - use: CIDRWhitelist
      allow:
        - 127.0.0.1
        - 223.0.0.0/8

# Middleware Compose (config/middlewares/whitelist.yml)
myWhitelist:
  - use: CloudflareRealIP
  - use: CIDRWhitelist
    allow:
      - 127.0.0.1
      - 223.0.0.0/8
```

--------------------------------

### Configure Request Whitelist and Access Logging

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/Access-Control

Example configuration for CIDR whitelisting and access log filtering using YAML for config files and Docker labels.

```yaml
# config.yml
entrypoint:
  middlewares: # allow only local (private) ips
    - use: CIDRWhiteList
      allow:
        - 127.0.0.1/32
        - 172.16.0.0/12
        - 192.168.0.0/16
        - 10.0.0.0/8
      status_code: 403
      message: Forbidden
  access_log:
    format: json
    path: /app/logs/access.json.log
    filters: # skip logging requests from local (private) ips
      cidr:
        negative: true
        values:
          - 127.0.0.1/32
          - 172.16.0.0/12
          - 192.168.0.0/16
          - 10.0.0.0/8
    fields:
      headers:
        default: drop # drop app headers in log
        config: # keep only these
          X-Real-Ip: keep
          CF-Connecting-Ip: keep
          X-Forwarded-For: keep

# docker labels
proxy.#1.middlewares.cidr_whitelist: |
  allow:
    - 10.0.0.0/8
    - 192.168.0.0/16
  status_code: 403
  message: "IP not allowed"
```

--------------------------------

### Run Benchmark Modes

Source: https://docs.godoxy.dev/docs/godoxy/Benchmarks-and-Resource-Usage

Execute the default benchmark suite.

```bash
shadowtree benchmark
```

--------------------------------

### GET /cert/renew

Source: https://docs.godoxy.dev/docs/openapi/renew

Triggers the renewal process for a certificate.

```APIDOC
## GET /cert/renew

### Description
Triggers the renewal process for a certificate.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/cert/renew

### Response
#### Success Response (200)
- **details** (object) - Contains property1 and property2
- **message** (string) - Success message

#### Response Example
{
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
```

--------------------------------

### GET /events

Source: https://docs.godoxy.dev/docs/openapi/events

Retrieves the history of events from the system.

```APIDOC
## GET /events

### Description
Retrieves the event history from the GoDoxy API.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/events

### Response
#### Success Response (200)
- **action** (string) - The action performed.
- **category** (string) - The category of the event.
- **data** (null) - Additional event data.
- **level** (string) - The log level (e.g., debug).
- **timestamp** (string) - The time the event occurred.
- **uuid** (string) - The unique identifier for the event.

#### Response Example
[
  {
    "action": "string",
    "category": "string",
    "data": null,
    "level": "debug",
    "timestamp": "string",
    "uuid": "string"
  }
]
```

--------------------------------

### Block-Syntax Routing Sequences

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing

Examples of complex routing logic including multiline OR/AND conditions, request mutation chains, and handler dispatching.

```text
# Multiline OR in header (line continuation)
method GET |
method POST |
method PUT {
  pass
}

# Multiline AND in header
header Connection Upgrade &
header Upgrade websocket {
  bypass
}

# Non-terminating then terminating
method GET {
  rewrite / /index.html
  serve /static
}

# Request mutation chain
method POST {
  set header X-Custom value
  add query debug true
  remove header X-Secret
}

# Post-phase log via status variable
path glob("/api/*") {
  proxy http://backend:8080
  log info /dev/stdout "$req_method $status_code"
}

# Dispatch to a built-in GoDoxy handler
path glob("/api/v1/*") {
  handle api
}

# Pass-through alias
header X-Bypass true {
  bypass
}
```

--------------------------------

### GET /homepage/categories

Source: https://docs.godoxy.dev/docs/openapi/categories

Retrieves a list of homepage categories.

```APIDOC
## GET /homepage/categories

### Description
Retrieves a list of categories available on the homepage.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/homepage/categories

### Response
#### Success Response (200)
- **categories** (array of strings) - A list of category names.

#### Response Example
[
  "string"
]
```

--------------------------------

### Configure autocert and match_domains

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/Domain-Matching

Set up main domains for automatic certification and domain matching.

```yaml
autocert:
  domains:
    - my.app
match_domains:
  - my.app
```

--------------------------------

### GET /route/by_provider

Source: https://docs.godoxy.dev/docs/openapi/byProvider

Retrieves a list of routes organized by provider.

```APIDOC
## GET /route/by_provider

### Description
Retrieves a list of routes categorized by provider.

### Method
GET

### Endpoint
/route/by_provider

### Response
#### Success Response (200)
- **property1** (array) - A list of route objects grouped by provider.

#### Response Example
{
  "property1": [
    {
      "agent": "string",
      "alias": "string",
      "bind": "string",
      "container": {
        "container_id": "string",
        "container_name": "string",
        "running": true,
        "state": "created"
      }
    }
  ]
}
```

--------------------------------

### GET /route/providers

Source: https://docs.godoxy.dev/docs/openapi/providers

Retrieves a list of all available route providers.

```APIDOC
## GET /route/providers

### Description
Retrieves a list of all available route providers configured in the system.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/route/providers

### Response
#### Success Response (200)
- **full_name** (string) - The full name of the provider
- **short_name** (string) - The short name identifier of the provider

#### Response Example
[
  {
    "full_name": "string",
    "short_name": "string"
  }
]
```

--------------------------------

### GET /favicon

Source: https://docs.godoxy.dev/docs/openapi/favicon

Retrieves the favicon for a given URL or alias.

```APIDOC
## GET /favicon

### Description
Retrieves the favicon for a specified route URL or alias.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/favicon

### Parameters
#### Query Parameters
- **url** (string) - Optional - URL of the route
- **alias** (string) - Optional - Alias of the route

### Response
#### Success Response (200)
- **image/svg+xml** - The favicon image in SVG format

#### Error Response (400, 403, 404, 500)
- **error** (string) - Error type
- **message** (string) - Error description
```

--------------------------------

### GET /version

Source: https://docs.godoxy.dev/docs/openapi/version

Retrieves the current version string of the GoDoxy service.

```APIDOC
## GET /version

### Description
Get the version of the GoDoxy service.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/version

### Response
#### Success Response (200)
- **version** (string) - The version string of the service.

#### Response Example
"1.0.0"
```

--------------------------------

### GET /route/{which}

Source: https://docs.godoxy.dev/docs/openapi/route

Retrieves the configuration and status details for a specified route.

```APIDOC
## GET /route/{which}

### Description
Retrieves the configuration and status details for a specified route.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/route/{which}

### Parameters
#### Path Parameters
- **which** (string) - Required - Route name

### Response
#### Success Response (200)
- **access_log** (object) - Access log configuration
- **agent** (string) - Agent identifier
- **alias** (string) - Route alias
- **bind** (string) - Bind address
- **container** (object) - Container configuration and status
- **health** (object) - Health check status and configuration

#### Response Example
{
  "access_log": {
    "format": "common",
    "path": "string",
    "stdout": true
  },
  "agent": "string",
  "alias": "string",
  "bind": "string",
  "container": {
    "container_id": "string",
    "running": true,
    "state": "created"
  },
  "health": {
    "status": "unknown",
    "url": "string"
  }
}
```

--------------------------------

### Configure DNS for GoDoxy Short Links

Source: https://docs.godoxy.dev/docs/godoxy/customization/Short-Links

Set the 'go' hostname to point to the GoDoxy server IP address.

```text
go -> <godoxy-server-ip>
```

--------------------------------

### GET /file/content

Source: https://docs.godoxy.dev/docs/openapi/get

Retrieves the content of a specified file from the GoDoxy system.

```APIDOC
## GET /file/content

### Description
Retrieves the content of a file based on the provided filename and type.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/file/content

### Parameters
#### Query Parameters
- **filename** (string) - Required - The name of the file to retrieve.
- **type** (string) - Required - The type of the file, must be one of: "config", "provider", "middleware".

### Request Example
curl -X GET "https://docs.godoxy.dev/api/v1/file/content?filename=string&type=config"

### Response
#### Success Response (200)
- **content** (string) - The content of the requested file.

#### Response Example
"string"

#### Error Response (400, 403, 500)
- **error** (string) - Error code
- **message** (string) - Error description

#### Error Example
{
  "error": "string",
  "message": "string"
}
```

--------------------------------

### Implement API Gateway with Basic Auth

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing

Demonstrates path-based routing combined with basic authentication and header manipulation.

```text
path regex("^/api/v[0-9]+/public/.*") {
  proxy http://api-server:8080
}

path glob("/api/v[0-9]/admin/*") &
basic_auth admin "$2y$10$hashed_password" {
  set header X-Admin true
  proxy http://admin-server:8080
}

path glob("/api/v[0-9]/admin/*") {
  require_basic_auth "Admin Access"
}
```

--------------------------------

### GET /docker/containers

Source: https://docs.godoxy.dev/docs/openapi/containers

Retrieves a list of all Docker containers managed by the system.

```APIDOC
## GET /docker/containers

### Description
Retrieves a list of Docker containers.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/docker/containers

### Response
#### Success Response (200)
- **id** (string) - The container ID
- **image** (string) - The image name
- **name** (string) - The container name
- **server** (string) - The server identifier
- **state** (string) - The current state of the container (e.g., created)

#### Response Example
[
  {
    "id": "string",
    "image": "string",
    "name": "string",
    "server": "string",
    "state": "created"
  }
]
```

--------------------------------

### GET /metrics/system_info

Source: https://docs.godoxy.dev/docs/openapi/system_info

Retrieves system metrics based on specified query parameters.

```APIDOC
## GET /metrics/system_info

### Description
Retrieves system metrics such as CPU, memory, disk, and network usage.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/metrics/system_info

### Parameters
#### Query Parameters
- **agentAddr** (string) - Optional - The address of the agent.
- **agentName** (string) - Optional - The name of the agent.
- **aggregate** (string) - Optional - The metric type to aggregate. Values: "cpu_average", "memory_usage", "memory_usage_percent", "disks_read_speed", "disks_write_speed", "disks_iops", "disk_usage", "network_speed", "network_transfer", "sensor_temperature".
- **period** (string) - Optional - The time period for the metrics. Values: "5m", "15m", "1h", "1d", "1mo".

### Response
#### Success Response (200)
- **data** (array) - List of metric objects.
- **total** (integer) - Total count of records.

#### Response Example
{
  "data": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "total": 0
}
```

--------------------------------

### Environment Variable Substitution

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing

Shows how to inject environment variables into configuration strings and how to escape the dollar sign to prevent substitution.

```text
error 403 "Forbidden: ${CLOUDFLARE_API_KEY}"
proxy https://${DOMAIN}/api
set header X-Tenant "tenant-${DOMAIN}"
```

```text
error 404 "$${NON_EXISTENT}" # Results in literal "${NON_EXISTENT}"
```

--------------------------------

### GET /homepage/items

Source: https://docs.godoxy.dev/docs/openapi/items

Retrieves a list of homepage items with optional filtering and sorting.

```APIDOC
## GET /homepage/items

### Description
Retrieves a list of homepage items based on optional category, provider, search query, and sorting method.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/homepage/items

### Parameters
#### Query Parameters
- **category** (string) - Optional - Category filter
- **provider** (string) - Optional - Provider filter
- **search** (string) - Optional - Search query
- **sort_method** (string) - Optional - Sort method (Default: "alphabetical", Options: "clicks", "alphabetical", "custom")

### Response
#### Success Response (200)
- **items** (array) - List of homepage items
- **name** (string) - Name of the item group

#### Response Example
[
  {
    "items": [
      {
        "alias": "string",
        "all_sort_order": 0,
        "category": "string",
        "clicks": 0,
        "container_id": "string",
        "description": "string",
        "fav_sort_order": 0,
        "favorite": true,
        "icon": "string",
        "name": "string",
        "origin_url": "string",
        "provider": "string",
        "proxmox": {
          "node": "string",
          "vmid": 0
        },
        "show": true,
        "sort_order": 0,
        "url": "string",
        "widget_config": {
          "config": null,
          "provider": "string"
        },
        "widgets": [
          {
            "label": "string",
            "value": "string"
          }
        ]
      }
    ],
    "name": "string"
  }
]
```

--------------------------------

### Use environment variables in configuration

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-GoDoxy

Demonstrates how to inject environment variables into YAML strings using the ${VAR_NAME} syntax.

```yaml
autocert:
  ...
  options:
    auth_token: ${AUTH_TOKEN}
```

--------------------------------

### Initiate Login via cURL

Source: https://docs.godoxy.dev/docs/openapi/login

Use this command to initiate the login process by sending a POST request to the authentication endpoint.

```bash
curl -X POST "https://docs.godoxy.dev/api/v1/auth/login"
```

--------------------------------

### Response Body Examples

Source: https://docs.godoxy.dev/docs/openapi/validate

Various JSON response structures returned by the validation endpoint.

```json
{
  "details": {
    "property1": null,
    "property2": null
  },
  "message": "string"
}
```

```json
{
  "error": "string",
  "message": "string"
}
```

```json
null
```

--------------------------------

### GET /api/v1/proxmox/journalctl/:node

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Proxmox

Streams system logs from a PVE node via WebSocket.

```APIDOC
## GET /api/v1/proxmox/journalctl/:node

### Description
Streams system journal logs from a PVE node using WebSockets. Requires username/password authentication.

### Method
GET

### Endpoint
/api/v1/proxmox/journalctl/:node

### Parameters
#### Path Parameters
- **node** (string) - Required - The identifier of the Proxmox node.

#### Query Parameters
- **limit** (integer) - Optional - Number of historical lines to retrieve. Default: 0.
```

--------------------------------

### Configure entrypoint and proxy protocol

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-GoDoxy

Defines trusted proxies, middleware access control, and access log settings for incoming requests.

```yaml
entrypoint:
  proxy_protocol:
    # required accepts only these proxies; mixed also permits direct clients.
    mode: required
    trusted_proxies:
      - "172.18.0.10"
      - "10.0.0.0/8"

  middlewares:
    - use: CIDRWhitelist
      allow:
        - "127.0.0.1"
        - "10.0.0.0/8"
        - "192.168.0.0/16"
      status: 403
      message: "Forbidden"

  access_log:
    format: combined
    path: /app/logs/access.log
    filters: ...
    fields: ...
```

--------------------------------

### Quoting and Escaping Values

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing

Demonstrates how to handle spaces and quotes in configuration values using double quotes, single quotes, and backslash escaping.

```text
header Some-Header "foo bar"     # Double quotes
header Some-Header 'foo bar'     # Single quotes
header Some-Header foo\ bar      # Escaped space
header Some-Header 'foo \"bar\"' # Escaped quotes inside single quotes
```

--------------------------------

### GET /api/v1/proxmox/stats/:node/:vmid

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Proxmox

Retrieves statistics for a specific container on a Proxmox node.

```APIDOC
## GET /api/v1/proxmox/stats/:node/:vmid

### Description
Retrieves current statistics for a specific container (LXC) on a given node.

### Method
GET

### Endpoint
/api/v1/proxmox/stats/:node/:vmid

### Parameters
#### Path Parameters
- **node** (string) - Required - The identifier of the Proxmox node.
- **vmid** (string) - Required - The container ID.
```

--------------------------------

### HTML Error Page Content

Source: https://docs.godoxy.dev/docs/godoxy/customization/Custom-Error-Pages

Example structure for an error page providing user-friendly feedback.

```html
<div class="error-content">
  <h1>Something went wrong</h1>
  <p>We're working on fixing this issue.</p>
  <p>Try again in a few minutes or <a href="/contact">contact support</a>.</p>
</div>
```

--------------------------------

### Configure Entrypoint Overlay Promotion

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/middlewares

Promote route-specific bypass rules into an entrypoint middleware to avoid redundant evaluation.

```yaml
entrypoint:
  middlewares:
    - use: oidc
```

```yaml
# Entrypoint has OIDC enabled
# This route adds bypass rules for the entrypoint OIDC middleware
proxy.myapp.middlewares.oidc.bypass: |
  - path glob(/public/*)
  - path /health
```

```yaml
myapp:
  middlewares:
    oidc:
      bypass:
        - path glob(/public/*)
        - path /health
```

--------------------------------

### GET /metrics/uptime

Source: https://docs.godoxy.dev/docs/openapi/uptime

Retrieves uptime metrics for services, supporting filtering by interval, keyword, and pagination.

```APIDOC
## GET /metrics/uptime

### Description
Retrieves uptime metrics for services. Supports filtering by time interval, keyword search, and pagination.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/metrics/uptime

### Parameters
#### Query Parameters
- **interval** (string) - Optional - Value in "5m" | "15m" | "1h" | "1d" | "1mo"
- **keyword** (string) - Optional - Search keyword
- **limit** (integer) - Optional - Default 0
- **offset** (integer) - Optional - Default 0

### Response
#### Success Response (200)
- **data** (array) - List of uptime metrics
- **total** (integer) - Total count of records

#### Response Example
{
  "data": [
    {
      "alias": "string",
      "avg_latency": 0,
      "current_status": "healthy",
      "downtime": 0,
      "idle": 0,
      "statuses": [
        {
          "latency": 0,
          "status": "healthy",
          "timestamp": 0
        }
      ],
      "uptime": 0
    }
  ],
  "total": 0
}
```

--------------------------------

### Run HTTP/1.1 cleartext benchmark

Source: https://docs.godoxy.dev/docs/godoxy/Benchmarks-and-Resource-Usage

Command to execute a benchmark run for HTTP/1.1 cleartext when it is not enabled by default.

```bash
shadowtree benchmark h1c=true
```

--------------------------------

### Configure File Server Route

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-Routes

Serve static files from a local directory with SPA support.

```yaml
blog:
  scheme: fileserver
  root: /app/blog/public
  spa: true
  index: index.html
```

--------------------------------

### GET /route/list

Source: https://docs.godoxy.dev/docs/openapi/list

Retrieves a list of all routes configured in the GoDoxy system. Optionally filter by provider.

```APIDOC
## GET /route/list

### Description
Retrieves a list of all routes configured in the GoDoxy system. This endpoint supports filtering by provider.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/route/list

### Parameters
#### Query Parameters
- **provider** (string) - Optional - The provider to filter the routes by.

### Response
#### Success Response (200)
- **Array** (object) - A list of route objects containing configuration, agent, container, and health details.
```

--------------------------------

### GET /icons

Source: https://docs.godoxy.dev/docs/openapi/icons

Retrieves a list of icons. Supports filtering by keyword and limiting the number of results.

```APIDOC
## GET /icons

### Description
Retrieves a list of available icons from the system.

### Method
GET

### Endpoint
https://docs.godoxy.dev/api/v1/icons

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Limit the number of icons returned.
- **keyword** (string) - Optional - Filter icons by a keyword.

### Request Example
curl -X GET "https://docs.godoxy.dev/api/v1/icons"

### Response
#### Success Response (200)
- **Dark** (boolean) - Indicates if a dark version is available.
- **Light** (boolean) - Indicates if a light version is available.
- **PNG** (boolean) - Indicates if a PNG version is available.
- **Ref** (string) - Reference identifier for the icon.
- **SVG** (boolean) - Indicates if an SVG version is available.
- **Source** (string) - URL source of the icon.
- **WebP** (boolean) - Indicates if a WebP version is available.

#### Response Example
[
  {
    "Dark": true,
    "Light": true,
    "PNG": true,
    "Ref": "string",
    "SVG": true,
    "Source": "https://",
    "WebP": true
  }
]
```

--------------------------------

### Configure Redirect HTTP in Entrypoint

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/middlewares/traffic-control/Redirect-HTTP

Apply the redirect_http middleware globally within the entrypoint configuration.

```yaml
entrypoint:
  middlewares:
    - use: redirect_http
```

--------------------------------

### Retrieve favicon via cURL

Source: https://docs.godoxy.dev/docs/openapi/favicon

Use this command to perform a GET request to the favicon endpoint.

```bash
curl -X GET "https://docs.godoxy.dev/api/v1/favicon"
```

--------------------------------

### Define Basic Route File

Source: https://docs.godoxy.dev/docs/godoxy/getting-started/Configuring-Routes

Standard route definition including host, port, and optional homepage metadata.

```yaml
# config/app.yml
app:
  host: 10.0.9.98
  port: 80
  homepage:
    name: Application
    icon: "@selfhst/app.svg"
    description: My application
    category: app

app-backend:
  host: 10.0.9.98
  port: 8080
  homepage:
    show: false
```

--------------------------------

### Configure Basic Block Syntax

Source: https://docs.godoxy.dev/docs/godoxy/advanced-topics/rule-based-routing

Standard block syntax for defining default and path-based routing rules.

```text
default {
  remove resp_header X-Internal
}

path glob("/api/*") {
  proxy http://api:8080
}
```
Tokens:
Raw