How to Configure Traefik Reverse Proxy with Docker Profiles for OpenWA

OpenWA ships with a built-in Traefik v3 reverse proxy that is activated via Docker Compose profiles, allowing you to start only the proxy (with the with-proxy profile) or the complete stack including API and dashboard routing (with the full profile).

The OpenWA repository provides a production-ready container orchestration setup that leverages Traefik for unified HTTP routing between the API and dashboard services. By utilizing Docker profiles defined in docker-compose.yml, you can configure Traefik reverse proxy with Docker profiles for OpenWA to match your specific deployment topology—whether running a minimal edge proxy or a full-featured stack with databases and caching. This configuration relies on two static files, traefik/traefik.yml and traefik/dynamic.yml, to define entry points and routing rules without requiring application code changes.

Understanding the Traefik Architecture in OpenWA

OpenWA implements a split-configuration pattern for Traefik v3 that separates static settings from dynamic routing rules.

Static configuration resides in traefik/traefik.yml and establishes the entry point on port 80, enables the Traefik dashboard API, and configures file-based provider settings. Dynamic configuration in traefik/dynamic.yml declares the HTTP routers and services that map specific URL paths to the underlying containers.

The static configuration uses providers.file.watch: true to enable hot-reload, meaning changes to routing rules take effect immediately without restarting the Traefik container.

Docker Profiles: with-proxy vs full

In docker-compose.yml, the traefik service declares specific profiles that control when the container starts:

profiles: ['with-proxy', 'full']

with-proxy starts only the reverse proxy. Use this profile when the OpenWA API runs externally or when you need to add TLS termination and routing to an existing deployment.

full starts the proxy alongside all core OpenWA services, including the openwa-api and openwa-dashboard containers. This profile provides a complete, self-contained environment.

Additional infrastructure services carry independent profiles: postgres for PostgreSQL, redis for caching, and minio for S3-compatible storage. You can combine these modularly to build your desired stack.

Configuration Files Deep Dive

Static Configuration (traefik/traefik.yml)

The static settings define how Traefik listens and exposes its administrative interface:

api:
  dashboard: true
  insecure: true          # set to false for production

entryPoints:
  web:
    address: ':80'
providers:
  file:
    filename: /etc/traefik/dynamic.yml
    watch: true
log:
  level: INFO

This configuration creates the web entry point on port 80 and exposes the Traefik dashboard on port 8080. The insecure: true setting allows dashboard access without authentication, suitable for local development.

Dynamic Routing Rules (traefik/dynamic.yml)

The dynamic file defines three critical routers that handle all inbound traffic:

1. api router: Matches PathPrefix(/api/) and forwards to the API service at http://openwa-api:2785
2. websocket router: Matches PathPrefix(/socket.io) for real-time WebSocket connections
3. dashboard router: Matches PathPrefix(/) with lower priority, acting as a catch-all for the dashboard at http://openwa-dashboard:80

Router priorities ensure that API and WebSocket paths take precedence over the dashboard catch-all rule.

Compose Service Definition (docker-compose.yml)

The Traefik container mounts the configuration files and exposes network ports:

services:
  traefik:
    image: traefik:v3.0
    container_name: openwa-traefik
    profiles: ['with-proxy', 'full']
    restart: unless-stopped
    ports:
      - '127.0.0.1:${DASHBOARD_PORT:-2886}:80'   # HTTP entry point

      - '127.0.0.1:8080:8080'                    # Traefik UI

    volumes:
      - ./traefik/traefik.yml:/etc/traefik/traefik.yml:ro
      - ./traefik/dynamic.yml:/etc/traefik/dynamic.yml:ro

The DASHBOARD_PORT environment variable defaults to 2886 for external HTTP access, while port 8080 remains fixed for the Traefik administrative interface.

Common Deployment Patterns

Run Only the Reverse Proxy

Use this command when connecting to an externally running OpenWA instance:

docker compose --profile with-proxy up -d

Deploy the Complete Core Stack

Start the proxy, API, and dashboard together:

docker compose --profile full up -d

Full Production Stack with Dependencies

Combine profiles to include persistent storage and caching:

docker compose \
  --profile full \
  --profile postgres \
  --profile redis \
  up -d

Customizing the Proxy Setup

Modify exposed ports: Edit the ports array in docker-compose.yml to change the external HTTP entry point or bind the Traefik dashboard to a specific interface.

Enable dashboard security: Change api.insecure to false in traefik/traefik.yml and add middleware for HTTP basic authentication or IP whitelisting.

Extend routing: Add new entries under http.routers in traefik/dynamic.yml to route traffic to additional services. The file provider automatically detects changes and updates routing without container restarts.

Summary

• OpenWA uses Traefik v3 with configurations split between traefik/traefik.yml (static settings) and traefik/dynamic.yml (routing rules)
• The with-proxy profile starts only the reverse proxy, while full launches the proxy with API and dashboard containers
• Dynamic routing automatically directs /api/* and /socket.io traffic to the API container (port 2785) and all other requests to the dashboard (port 80)
• Docker Compose profiles enable modular deployments, allowing selective inclusion of PostgreSQL, Redis, or MinIO
• Configuration updates apply automatically via Traefik's file watcher, requiring zero application downtime

Frequently Asked Questions

What is the difference between the with-proxy and full Docker profiles?

The with-proxy profile starts only the Traefik container, suitable for external API routing or adding reverse proxy capabilities to existing infrastructure. The full profile starts Traefik alongside the OpenWA API and dashboard containers, providing a complete self-hosted deployment with internal service discovery.

How do I access the Traefik dashboard for monitoring?

The Traefik dashboard is available at http://127.0.0.1:8080 when the container is running. This administrative interface shows active routers, services, and middleware chains. Note that external HTTP traffic enters through port 2886 (or your configured DASHBOARD_PORT), while port 8080 serves only the Traefik web UI.

Can I run the proxy without starting the OpenWA API container?

Yes. Executing docker compose --profile with-proxy up -d starts only the Traefik service. This pattern works when your OpenWA API runs outside Docker, such as on a remote server or as a native process, and you need local routing or TLS termination.

How does WebSocket support work for socket.io connections?

WebSocket support is pre-configured in traefik/dynamic.yml via the websocket router, which specifically matches the /socket.io path prefix and routes traffic to the API service. This configuration maintains persistent connections for real-time events without additional proxy settings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}