Advanced configuration

Configuration sources

The gateway reads configuration in this order:

1. The baseline JSON file included in the container image.
2. The JSON file at VIEWBRIDGE_CONFIG_FILE, normally /etc/viewbridge/gateway.json.
3. VIEWBRIDGE_CONFIG_OVERRIDES_JSON, for nested JSON overrides.
4. Individual environment variables such as VIEWBRIDGE_BIND_ADDRESS and VIEWBRIDGE_GATEWAY_TOKEN.

Later values win. The local configuration page writes the JSON file; it does not change environment variables. An environment-controlled value therefore remains in control after a page edit or container restart.

The standard container command mounts /etc/viewbridge as viewbridge-config and /data as viewbridge-data:

-v viewbridge-config:/etc/viewbridge `
-v viewbridge-data:/data

Keep both volumes. The first stores the editable gateway configuration. The second stores the generated certificate, gateway-local TLS key, and restart-safe pending certificate order state. The ACME account key remains in the cloud certificate worker. Losing the second volume can require operator-assisted certificate recovery.

Gateway identity and network address

VIEWBRIDGE_BIND_ADDRESS must be the Docker host’s private address, not the camera address and not a container address. If the host receives a new DHCP address, update the variable and recreate the container with the new port bindings.

The gateway hostname is assigned from the gateway key. Leave hostname configuration alone.

Portal connection

The API URL must not contain credentials, query parameters, or fragments. The gateway key is not a camera credential and must not be reused as one. Keep it out of public issue reports and logs.

If you pass VIEWBRIDGE_GATEWAY_TOKEN, the local page cannot change that key. To rotate it from the page, remove the environment variable and let the page save the replacement into the JSON file. Restart the container after changing either form of configuration.

TLS files

These are filenames, not arbitrary paths. The certificate and private key are kept under the gateway data directory. Never put a private key in the portal, an environment file committed to source control, or a support bundle.

Local configuration page

The page is intended for the trusted home network. If you disable it, set VIEWBRIDGE_WEB_UI_ENABLED=false and manage the JSON configuration through your deployment process. Keep port 8443 on the home network; do not expose the setup page to the public Internet.

The standard Docker port mapping is:

If you change the web UI or WebRTC ports, change the Docker mappings at the same time. Keep port 443 mapped to the gateway’s TLS listener.

Camera configuration

The local page is the normal way to add cameras. For automation, cameras can be supplied in JSON or replaced with VIEWBRIDGE_CAMERAS_JSON:

[
  {
    "path": "front-door",
    "name": "Front Door",
    "source": "rtsp://camera-user:camera-password@192.168.1.50:554/stream",
    "enabled": true,
    "expectedVideo": {
      "codec": "h264",
      "width": 1280,
      "height": 720
    }
  }
]

Each camera needs:

• A unique lower-case path containing letters, digits, and single hyphens.
• A friendly name used by Alexa.
• An rtsp:// or rtsps:// source URL.
• H.264 video dimensions between 1 and 8192 pixels.
• enabled: true or false.

VIEWBRIDGE_CAMERAS_JSON replaces the complete camera list. When it is set, the local page cannot add or edit cameras. Camera URLs may contain camera credentials, so keep this variable private and avoid putting it in shell history where possible.

WebRTC options

WebRTC is the default and recommended mode for current Echo devices. RTSP is retained as a direct camera-stream mode. In the current gateway, WebRTC media uses 8189/udp and 8190/tcp, but the container still retains its TLS/RTSP listener, so port 443 is still required in the standard setup. The WebRTC ports do not replace it. The UDP and TCP ports must be different and between 1024 and 65535.

JSON override example

Use VIEWBRIDGE_CONFIG_OVERRIDES_JSON when several related values should be changed without replacing the whole configuration file:

docker run ... `
  -e VIEWBRIDGE_BIND_ADDRESS=192.168.1.42 `
  -e VIEWBRIDGE_CONFIG_OVERRIDES_JSON='{"webUi":{"port":9443},"webrtc":{"enabled":false}}' `
  ... viewbridge-gateway:latest

The value must be valid JSON. It is merged into the JSON configuration before the individual environment variables are applied, so VIEWBRIDGE_WEB_UI_PORT would win over the webUi.port value in this example.

Restart and inspect

After changing an environment variable, recreate the container so Docker supplies the new value:

docker rm -f viewbridge-gateway

Run the original docker run command again. Do not remove viewbridge-config or viewbridge-data unless you intentionally want to discard gateway state.

For startup output:

docker logs --tail 200 viewbridge-gateway

The gateway redacts configured camera source URLs from its own error messages. Treat Docker’s environment inspection, shell history, and host backups as sensitive because they can still contain values you supplied yourself.

Safe boundaries

• Keep the gateway and camera on the home network.
• Do not publish the camera’s RTSP port to the Internet.
• Do not forward the gateway’s setup page to the public Internet.
• Use one gateway key for one gateway and rotate it if the host is no longer trusted.
• Keep camera credentials, gateway keys, and TLS keys out of Git and support requests. The ACME account material is cloud-worker-only and must never be copied to the gateway.