Web Hosting HTTPS

Web Hosting HTTPS

KOKOTO WebChat 5.0.0 · Minecraft 1.18–26.2 · Java 17 baseline

6. HTTP, HTTPS, and Public URLs

6.1 Direct HTTP

Recommended only for testing or a private network.

http:
  host: "0.0.0.0"
  port: 8899
  path-prefix: "/api"
  cors-origin: "*"

adapters:
  bluemap:
    api-base-url: ""

6.2 Same-Domain HTTPS Reverse Proxy

http:
  host: "127.0.0.1"
  port: 8899
  path-prefix: "/api"
  public-prefix: "/chat"
  cors-origin: "https://map.example.com"
  trusted-proxies:
    - "127.0.0.1"
    - "::1"

frontend:
  standalone:
    enabled: true
    path: "/"
    api-base-url: ""

adapters:
  bluemap:
    enabled: true
    api-base-url: ""

Public paths:

https://map.example.com/          BlueMap
https://map.example.com/chat/api  KOKOTO WebChat API
https://map.example.com/chat      Standalone chat

Normally leave frontend.standalone.api-base-url, upload.public-base-url, and emoji.public-base-url empty. They then follow the active public API base automatically.

6.2.1 BlueMap + squaremap + standalone together

The three frontends can be published on one HTTPS origin. Only one map should own /; put the other map and the standalone page under separate prefixes. Example with squaremap as the root site:

https://map.example.com/           squaremap
https://map.example.com/bluemap/   BlueMap
https://map.example.com/chat      Standalone chat
https://map.example.com/chat/api  KOKOTO WebChat API

Example Caddy routing:

map.example.com {
  encode zstd gzip

  @chat path /chat /chat/*
  handle @chat {
    uri strip_prefix /chat
    reverse_proxy 127.0.0.1:8899
  }

  @bluemap path /bluemap /bluemap/*
  handle @bluemap {
    uri strip_prefix /bluemap
    reverse_proxy 127.0.0.1:8100
  }

  handle {
    reverse_proxy 127.0.0.1:8080
  }
}

If BlueMap should own /, swap the BlueMap root handler and squaremap prefix instead. Adapter enablement is independent of which service owns /: enable both adapters.bluemap.enabled and adapters.squaremap.enabled when both embedded KWC frontends are wanted.

Alternative: standalone KWC at /, BlueMap at /chat/

To invert the normal layout, set http.public-prefix: "", keep frontend.standalone.path: "/", proxy /chat/ to BlueMap with the prefix stripped, and route the remaining site to KWC. The public endpoints then become:

/       KWC standalone
/api    KWC API
/chat/  BlueMap

For Caddy, handle_path /chat/* can proxy BlueMap :8100, followed by a catch-all handle for KWC :8899. See docs/CADDY_HTTPS_EN.md for the complete example.

6.3 Trusted Proxy Handling

X-Forwarded-For is accepted only from direct peers listed in http.trusted-proxies. Keep the list empty for direct HTTP.

Temporary diagnostic option:

http:
  log-client-ip-resolution: true

Disable it after confirming the proxy and resolved client IP.

Detailed references

See the bundled docs/CADDY_HTTPS_EN.md and docs/NGINX_HTTPS_EN.md for complete reverse-proxy examples.