Document api.public_host in the engine.yaml (#458)

* document api.public_host in the engine.yaml

* fix order and identation

* adjust wording explaining when to use api.public_host; fix wrong references to api.http.{prop}

* Update app/en/home/local-deployment/configure/configuration-templates/page.mdx

Co-authored-by: Nate Barbettini <[email protected]>

* Update app/en/home/local-deployment/configure/engine/page.mdx

Co-authored-by: Nate Barbettini <[email protected]>

* Update app/en/home/local-deployment/configure/engine/page.mdx

Co-authored-by: Nate Barbettini <[email protected]>

---------

Co-authored-by: Nate Barbettini <[email protected]>

Author: byrro

app/en/home/local-deployment/configure/configuration-templates/page.mdx

@@ -3,10 +3,10 @@ title: "Configuration Templates"
 description: "Arcade Engine Configuration Templates"
 ---
 
-
 # Engine Config Templates
 
 ### engine.yaml
+
 ```yaml
 # yaml-language-server: $schema=https://raw.githubusercontent.com/ArcadeAI/schemas/main/engine/config/1.0/schema.json
 $schema: https://raw.githubusercontent.com/ArcadeAI/schemas/main/engine/config/1.0/schema.json
@@ -15,115 +15,115 @@ api:
   development: ${env:API_DEVELOPMENT}
   host: ${env:ARCADE_API_HOST}
   port: ${env:ARCADE_API_PORT}
-
+  # Optionally set public_host, in case the Arcade Engine is hosted in a container or behind a reverse proxy
+  #public_host: ${env:ARCADE_API_PUBLIC_HOST}
 
 auth:
   providers:
     - id: default-atlassian
-      description: 'The default Atlassian provider'
+      description: "The default Atlassian provider"
       enabled: false
       type: oauth2
       provider_id: atlassian
       client_id: ${env:ATLASSIAN_CLIENT_ID}
       client_secret: ${env:ATLASSIAN_CLIENT_SECRET}
 
     - id: default-discord
-      description: 'The default Discord provider'
+      description: "The default Discord provider"
       enabled: false
       type: oauth2
       provider_id: discord
       client_id: ${env:DISCORD_CLIENT_ID}
       client_secret: ${env:DISCORD_CLIENT_SECRET}
 
     - id: default-dropbox
-      description: 'The default Dropbox provider'
+      description: "The default Dropbox provider"
       enabled: false
       type: oauth2
       provider_id: dropbox
       client_id: ${env:DROPBOX_CLIENT_ID}
       client_secret: ${env:DROPBOX_CLIENT_SECRET}
 
     - id: default-github
-      description: 'The default GitHub provider'
+      description: "The default GitHub provider"
       enabled: false
       type: oauth2
       provider_id: github
       client_id: ${env:GITHUB_CLIENT_ID}
       client_secret: ${env:GITHUB_CLIENT_SECRET}
 
     - id: default-google
-      description: 'The default Google provider'
+      description: "The default Google provider"
       enabled: false
       type: oauth2
       provider_id: google
       client_id: ${env:GOOGLE_CLIENT_ID}
       client_secret: ${env:GOOGLE_CLIENT_SECRET}
 
     - id: default-linkedin
-      description: 'The default LinkedIn provider'
+      description: "The default LinkedIn provider"
       enabled: false
       type: oauth2
       provider_id: linkedin
       client_id: ${env:LINKEDIN_CLIENT_ID}
       client_secret: ${env:LINKEDIN_CLIENT_SECRET}
 
     - id: default-microsoft
-      description: 'The default Microsoft provider'
+      description: "The default Microsoft provider"
       enabled: false
       type: oauth2
       provider_id: microsoft
       client_id: ${env:MICROSOFT_CLIENT_ID}
       client_secret: ${env:MICROSOFT_CLIENT_SECRET}
 
     - id: default-reddit
-      description: 'The default Reddit provider'
+      description: "The default Reddit provider"
       enabled: false
       type: oauth2
       provider_id: reddit
       client_id: ${env:REDDIT_CLIENT_ID}
       client_secret: ${env:REDDIT_CLIENT_SECRET}
 
     - id: default-slack
-      description: 'The default Slack provider'
+      description: "The default Slack provider"
       enabled: false
       type: oauth2
       provider_id: slack
       client_id: ${env:SLACK_CLIENT_ID}
       client_secret: ${env:SLACK_CLIENT_SECRET}
 
     - id: default-spotify
-      description: 'The default Spotify provider'
+      description: "The default Spotify provider"
       enabled: false
       type: oauth2
       provider_id: spotify
       client_id: ${env:SPOTIFY_CLIENT_ID}
       client_secret: ${env:SPOTIFY_CLIENT_SECRET}
 
     - id: default-twitch
-      description: 'The default Twitch provider'
+      description: "The default Twitch provider"
       enabled: false
       type: oauth2
       provider_id: twitch
       client_id: ${env:TWITCH_CLIENT_ID}
       client_secret: ${env:TWITCH_CLIENT_SECRET}
 
     - id: default-x
-      description: 'The default X provider'
+      description: "The default X provider"
       enabled: false
       type: oauth2
       provider_id: x
       client_id: ${env:X_CLIENT_ID}
       client_secret: ${env:X_CLIENT_SECRET}
 
     - id: default-zoom
-      description: 'The default Zoom provider'
+      description: "The default Zoom provider"
       enabled: false
       type: oauth2
       provider_id: zoom
       client_id: ${env:ZOOM_CLIENT_ID}
       client_secret: ${env:ZOOM_CLIENT_SECRET}
 
-
 llm:
   models:
     - id: my-openai-model-provider
@@ -143,14 +143,12 @@ llm:
     #    base_url: 'https://api.groq.com/openai/v1'
     #    api_key: ${env:GROQ_API_KEY}
 
-
 security:
   root_keys:
     - id: key1
       default: true
       value: ${env:ROOT_KEY_1}
 
-
 storage:
   postgres:
     user: ${env:POSTGRES_USER}
@@ -160,15 +158,13 @@ storage:
     db: ${env:POSTGRES_DB}
     sslmode: require
 
-
 telemetry:
   environment: ${env:TELEMETRY_ENVIRONMENT}
   logging:
     # debug, info, warn, error
     level: ${env:TELEMETRY_LOGGING_LEVEL}
     encoding: ${env:TELEMETRY_LOGGING_ENCODING}
 
-
 tools:
   directors:
     - id: default
@@ -185,6 +181,7 @@ tools:
 ```
 
 ### engine.env
+
 ```bash
 ### Engine configuration ###
 API_DEVELOPMENT=true

app/en/home/local-deployment/configure/engine/page.mdx

@@ -80,11 +80,13 @@ topic:
 HTTP is the supported protocol for Arcade Engine's API. The following configuration options are available:
 
 - `api.development` _(optional, default: `false`)_ - Enable development mode, with more logging and simple [worker authentication](/home/local-deployment/configure/engine#http-worker-configuration)
-- `api.http.host` _(default: `localhost`)_ - Address to which Arcade Engine binds its server (e.g., `localhost` or `0.0.0.0`)
-- `api.http.read_timeout` _(optional, default: `30s`)_ - Timeout for reading data from clients
-- `api.http.write_timeout` _(optional, default: `1m`)_ - Timeout for writing data to clients
-- `api.http.idle_timeout` _(optional, default: `30s`)_ - Timeout for idle connections
-- `api.http.max_request_body_size` _(optional, default: `4Mb`)_ - Maximum request body size
+- `api.host` _(default: `localhost`)_ - Address to which Arcade Engine binds its server (e.g., `localhost` or `0.0.0.0`)
+- `api.port` _(default: `9099`)_ - Port to which Arcade Engine binds its server (e.g., `9099` or `8080`)
+- `api.public_host` _(optional)_ - External hostname of the API (e.g., `my-public-host.com`), if it differs from `api.host` (for example, when Arcade Engine is behind a reverse proxy)
+- `api.read_timeout` _(optional, default: `30s`)_ - Timeout for reading data from clients
+- `api.write_timeout` _(optional, default: `1m`)_ - Timeout for writing data to clients
+- `api.idle_timeout` _(optional, default: `30s`)_ - Timeout for idle connections
+- `api.max_request_body_size` _(optional, default: `4Mb`)_ - Maximum request body size
 
 A typical configuration for production looks like:
 
@@ -95,6 +97,16 @@ api:
   port: 9099
 ```
 
+When the Arcade Engine is hosted in a container or behind a reverse proxy, set `api.public_host` to the external hostname of the API:
+
+```yaml
+api:
+  development: false
+  host: localhost
+  port: 9099
+  public_host: my-public-host.com
+```
+
 For local development, set `api.development = true`. In development mode, Arcade Engine does not require [worker authentication](/home/local-deployment/configure/engine#http-worker-configuration).
 
 ## Auth configuration
@@ -144,8 +156,8 @@ Two cache implementations are available:
 cache:
   api_key_ttl: 10s
   redis:
-    addr: 'localhost:6379'
-    password: ''
+    addr: "localhost:6379"
+    password: ""
     db: 0
 ```
 
@@ -263,7 +275,7 @@ tools:
         - id: local_worker
           enabled: true
           http:
-            uri: 'http://localhost:8002'
+            uri: "http://localhost:8002"
             timeout: 30
             retry: 3
             secret: ${env:ARCADE_WORKER_SECRET}