Skip to content

Home

Jump to bottom
Yuzerion edited this page Feb 23, 2025 · 43 revisions

Welcome to the GoDoxy v0.9 wiki

Docker Image

Stable

  • Proxy: ghcr.io/yusing/godoxy:latest
  • Frontend: ghcr.io/yusing/godoxy-frontend:latest

Nightly (experimental)

  • Proxy: ghcr.io/yusing/godoxy:nightly
  • Frontend: ghcr.io/yusing/godoxy-frontend:nightly

Known issues

  • Idlewatcher does not work with TCP / UDP routes (wip)

Environment variables

Core

Note: it also checks for environment variables with old prefix GOPROXY_, or without prefix like API_USER

Environment Variable Description Default Values
GODOXY_HTTP_ADDR http server listening address :80 [host]:port
GODOXY_HTTPS_ADDR https server listening address (if enabled) :443 [host]:port
GODOXY_API_ADDR api server listening address 127.0.0.1:8888 [host]:port
GODOXY_PROMETHEUS_ENABLED enable Prometheus metrics true boolean
GODOXY_DEBUG enable debug behaviors false boolean

Authentication

Authentication only works on HTTPs, please configure autocert, or disable authetication.

Default

  1. set random JWT secret
sed -i "s|API_JWT_SECRET=.*|API_JWT_SECRET=$(openssl rand -base64 32)|g" .env
  1. change username and password for WebUI authentication
USERNAME=admin
PASSWORD=some-password
sed -i "s|API_USERNAME=.*|API_USERNAME=${USERNAME}|g" .env
sed -i "s|API_PASSWORD=.*|API_PASSWORD=${PASSWORD}|g" .env
Environment Variable Description Default Values
GODOXY_API_JWT_SECRET base64 JWT secret for api server empty (disable WebUI auth) string
GODOXY_API_JWT_TOKEN_TTL JWT token TTL 1h duration
GODOXY_API_USER API/WebUI login username admin string
GODOXY_API_PASSWORD API/WebUI login password password string

OIDC

When OIDC is enabled GODOXY_API_* will be ignored.

Environment Variable Description
GODOXY_OIDC_ISSUER_URL OIDC issuer URL
GODOXY_OIDC_LOGOUT_URL OIDC logout URL (optional, set if your OIDC provider supports it, e.g. Authentik)
GODOXY_OIDC_CLIENT_ID OIDC client ID
GODOXY_OIDC_CLIENT_SECRET OIDC client secret
GODOXY_OIDC_REDIRECT_URL OIDC redirect URL
GODOXY_OIDC_ALLOWED_USERS OIDC allowed users (optional when ALLOWED_GROUPS is set)
GODOXY_OIDC_ALLOWED_GROUPS OIDC allowed groups (optional when ALLOWED_USERS is set)

You will have to add two "Allowed Callback URL"s in your OIDC provider, (replace domain.com with your actual domain):

  • https://godoxy.domain.com/api/auth/callback This one is for WebUI and API
  • https://*.domain.com/auth/callback This one is for other apps using middleware
    • On Authentik or those providers that support regex: https:\/\/([^\.]+)\.yourdomain\.com\/(api\/)?auth\/callback

Authentik specific:

  • Set Signing Key to "authentik Self-signed Certificate"
  • Set Encryption Key to None
  • Set Issuer mode to "Each provider has a different issuer, based on the application slug" if not already

Usage Example (Pocket ID):

Image

Image

Add these to .env:

  • GODOXY_OIDC_ISSUER_URL Authorization URL
  • GODOXY_OIDC_CLIENT_ID Client ID
  • GODOXY_OIDC_CLIENT_SECRET Client secret
  • GODOXY_OIDC_REDIRECT_URL the first callback url
  • GODOXY_OIDC_ALLOWED_USERS your pocket-id username

After setting these, to enable OIDC for specific app, it's just two lines in docker compose:

services:
  your_app:
    ...
    # here
    labels:
      proxy.#1.middlewares.oidc:

Checkout OIDC Middleware for customizing OIDC per app.

Behaviors

All docker containers are proxied by default, except any of the following is true:

  • label proxy.exclude is true
  • GoDoxy is NOT explicit enabled for container, but
    • it's from a provider in explicit mode (! at the end of provider name, means explicit only), OR
    • container is detected as a database (from mountpoints and exposed ports)
  • container name has prefix buildx_
  • alias has prefix x- or suffix -old
  • container don't have any exposed port / no port mapped to host

To explicitly enable GoDoxy for a container:

  • (GoDoxy < v0.9) set label proxy.aliases
  • (GoDoxy >= v0.9) set any label starting with proxy.

By default you can access your services at: <container_name>.yourdomain.com

Example Docker Compose for apps

HTTPs only apps

Some apps listen only HTTPs, so may have to set it manually, e.g.:

services:
  smtp:
    image: bytemark/smtp
    container_name: smtp # here is the alias/subdomain
    restart: always
    environment: ...
    labels:
      # set it to proxy to https
      proxy.smtp.scheme: https
      # disable TLS, assuming the app is using self signed cert
      # and maintains only local connection.
      proxy.smtp.no_tls_verify: true

Multiple-port apps

services:
  app:
    ...
    ports:
      - 8080
      - 8081
    labels:
      proxy.aliases: app, app-backend
      proxy.#1.port: 8080
      proxy.#2.port: 8081

GoDoxy Docker Compose Examples

Simple

services:
  frontend:
    image: ghcr.io/yusing/go-proxy-frontend:latest
    container_name: go-proxy-frontend
    restart: unless-stopped
    network_mode: host
    env_file: .env
    depends_on:
      - app
  app:
    image: ghcr.io/yusing/go-proxy:latest
    container_name: go-proxy
    restart: always
    network_mode: host
    env_file: .env
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config:/app/config
      - ./certs:/app/certs # to store obtained certs or load existing certs

Advanced

services:
  frontend:
    image: yusing/godoxy-frontend-nightly:latest
    container_name: go-proxy-frontend
    restart: unless-stopped
    network_mode: host
    env_file: .env
    environment:
      - PORT=3003 # you can change the default listening port
    labels:
      proxy.aliases: "home"
      proxy.home.port: "3003" # change here also
      proxy.home.middlewares.cidr_whitelist: |
        status_code: "403"
        message: "IP not allowed"
        allow:
          - 10.0.4.0/22
          - 10.0.14.0/22
    depends_on:
      - app
  app:
    image: yusing/godoxy-nightly:latest
    container_name: go-proxy
    restart: always
    network_mode: host
    env_file: .env
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /shared/godoxy/config:/app/config
      - /shared/godoxy/certs:/app/certs
      - /shared/godoxy/error_pages:/app/error_pages
      - /shared/godoxy/logs:/app/logs

Commands line arguments

Argument Description Example
empty start proxy server
validate validate config and exit
reload trigger a force reload of config
ls-config list config and exit godoxy ls-config | jq
ls-routes list proxy entries and exit godoxy ls-routes | jq
ls-icons list icons from selfh.st and walkxcode and exit godoxy ls-icons | grep adguard
debug-ls-mtrace list middleware trace (works only in debug mode) godoxy debug-ls-mtrace | jq

Create shell alias like alias godoxy="docker exec godoxy /app/godoxy" then run with godoxy <command>

Use JSON Schema in IDEs

If you are unsure about what it is, ignore this

Using JSON schema allows static checking in IDEs. For VSCode, copy .vscode/settings.example.json to .vscode/settings.json (under root directory of GoDoxy) and modify it to fit your needs

See also:

Clone this wiki locally