# How to Configure Traefik Reverse Proxy with Docker Profiles for OpenWA

> Learn to configure Traefik reverse proxy with Docker profiles for OpenWA. Easily manage API and full stack routing using simple profile commands for efficient deployment.

- Repository: [Yudhi Armyndharis/OpenWA](https://github.com/rmyndharis/OpenWA)
- Tags: how-to-guide
- Published: 2026-05-21

---

**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`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/traefik/traefik.yml) and [`traefik/dynamic.yml`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/docker-compose.yml), the `traefik` service declares specific profiles that control when the container starts:

```yaml
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:

```yaml
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:

```yaml
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:

```bash
docker compose --profile with-proxy up -d

```

### Deploy the Complete Core Stack

Start the proxy, API, and dashboard together:

```bash
docker compose --profile full up -d

```

### Full Production Stack with Dependencies

Combine profiles to include persistent storage and caching:

```bash
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`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/traefik/traefik.yml) (static settings) and [`traefik/dynamic.yml`](https://github.com/rmyndharis/OpenWA/blob/main/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`](https://github.com/rmyndharis/OpenWA/blob/main/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.