Version: latest

Deploy with Docker Compose

Docker Compose is a convenient method for rapid prototyping, local development, and small-scale testing of API7 Enterprise. In the current workflow, Docker Compose brings up the control plane components on a single host, and the Dashboard generates the Docker command that bootstraps the data plane gateway with the required mTLS credentials.

note

Docker Compose is suitable for development and testing only. For production, use Kubernetes and high availability deployments.

Prerequisites

Docker (v20.10.x or later)
Docker Compose (v2.x or later)
A valid API7 Enterprise license. Get a trial license.

Step 1: Create the directory layout

Create a working directory with subdirectories for each component's configuration:

mkdir -p api7-ee/{dashboard_conf,dp_manager_conf}
cd api7-ee

Step 2: Write the control plane configuration files

API7 Enterprise control plane components read their configuration from YAML files. Create the files below and mount them into the containers in Step 4.

`dashboard_conf/conf.yaml`

This file configures the integrated Dashboard and Admin API. The database.dsn value must match the PostgreSQL credentials you will set in the Compose file.

dashboard_conf/conf.yaml
server:
  listen:
    disable: true
    host: "0.0.0.0"
    port: 7080
  tls:
    disable: false
    host: "0.0.0.0"
    port: 7443
    key_file: ""
    cert_file: ""
  status:
    disable: false
    host: "127.0.0.1"
    port: 7081
  pprof:
    enable: true
    host: "127.0.0.1"
    port: 6060

log:
  level: warn
  output: stderr
  access_log: stdout

database:
  dsn: "postgres://api7ee:YOUR_DB_PASSWORD@postgresql:5432/api7ee"
  max_open_conns: 30
  max_idle_time: 30s
  # max_lifetime: 60s
  timeout: 5s

session_options_config:
  same_site: "lax"
  secure: false
  max_age: 86400

prometheus:
  addr: "http://prometheus:9090"
  query_path_prefix: ""
  whitelist:
    - "/api/v1/query_range"
    - "/api/v1/query"
    - "/api/v1/format_query"
    - "/api/v1/series"
    - "/api/v1/labels"
    - "/api/v1/labels/.*/values"

jaeger:
  addr: "http://jaeger:16686"
  timeout: 30s

audit:
  retention_days: 60

consumer_proxy:
  enable: false
  cache_success_count: 512
  cache_success_ttl: 60
  cache_failure_count: 512
  cache_failure_ttl: 60

developer_proxy:
  cache_success_count: 256
  cache_success_ttl: 15
  cache_failure_count: 256
  cache_failure_ttl: 15

security:
  trusted_proxies: ["0.0.0.0/0", "::/0"]
  ip_restriction:
    allow_list: []
    deny_list: []
    message: "Access denied"
    response_code: 403

`dp_manager_conf/conf.yaml`

This file configures the DP Manager, which exposes the etcd-compatible API on port 7943 that data planes connect to.

dp_manager_conf/conf.yaml
server:
  listen:
    host: "0.0.0.0"
    port: 7900
  tls:
    host: "0.0.0.0"
    port: 7943
  status:
    disable: false
    host: "127.0.0.1"
    port: 7901
  pprof:
    enable: true
    host: "127.0.0.1"
    port: 6060

log:
  level: warn
  output: stderr
  access_log: stdout

database:
  dsn: "postgres://api7ee:YOUR_DB_PASSWORD@postgresql:5432/api7ee"
  max_open_conns: 30
  max_idle_time: 30s
  timeout: 5s

prometheus:
  addr: "http://prometheus:9090"
  remote_write_path: "/api/v1/write"

jaeger:
  collector_addr: "http://jaeger:4318"
  timeout: 30s

consumer_cache:
  size: 50000
  max_ttl: 2h
  evict_interval: 5s

developer_cache:
  size: 50000
  max_ttl: 2h
  evict_interval: 5s

rate_limit:
  enable: false
  time_window: 1
  count: 1000

Step 3: Create the PostgreSQL database

Before starting the stack, ensure the database user and database referenced in the DSNs above exist. The bundled PostgreSQL image will create them from environment variables on first start, so you only need to make sure the values in your conf.yaml files match.

Step 4: Create the Docker Compose file

Create docker-compose.yaml in the same directory:

docker-compose.yaml
services:
  prometheus:
    image: api7/prometheus:2.48.1-debian-11-r0
    hostname: prometheus
    user: root
    command:
      - --config.file=/opt/bitnami/prometheus/conf/prometheus.yml
      - --web.enable-remote-write-receiver
    healthcheck:
      test: ["CMD", "/opt/bitnami/prometheus/bin/promtool", "check", "healthy"]
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 10s
    networks:
      - api7

  postgresql:
    image: api7/postgresql:15.4.0-debian-11-r45
    hostname: postgresql
    user: root
    environment:
      POSTGRES_USER: api7ee
      POSTGRES_PASSWORD: YOUR_DB_PASSWORD
      POSTGRES_DB: api7ee
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "api7ee"]
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 10s
    networks:
      - api7

  jaeger:
    image: cr.jaegertracing.io/jaegertracing/jaeger:2.14.1
    hostname: jaeger
    restart: always
    networks:
      - api7

  dashboard:
    image: api7/api7-ee-3-integrated:${API7_VERSION}
    hostname: dashboard
    restart: always
    volumes:
      - ./dashboard_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro
    command:
      - -c
      - /nodejs/bin/node /app/server.js & /usr/local/api7/api7-ee-dashboard -c /usr/local/api7/conf/conf.yaml
    ports:
      - "7080:7080"
      - "7443:7443"
    healthcheck:
      test:
        - CMD
        - /nodejs/bin/node
        - -e
        - "const net=require('net');const socket=net.connect(7443,'127.0.0.1');socket.on('connect',()=>{socket.end();process.exit(0)});socket.on('error',()=>process.exit(1));setTimeout(()=>process.exit(1),3000);"
      interval: 10s
      timeout: 5s
      retries: 12
    depends_on:
      prometheus:
        condition: service_healthy
      postgresql:
        condition: service_healthy
    networks:
      - api7

  dp-manager:
    image: api7/api7-ee-dp-manager:${API7_VERSION}
    hostname: dp-manager
    restart: always
    volumes:
      - ./dp_manager_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro
    command:
      - /usr/local/api7/api7-ee-dp-manager
      - -c
      - /usr/local/api7/conf/conf.yaml
    ports:
      - "7900:7900"
      - "7943:7943"
    depends_on:
      dashboard:
        condition: service_healthy
    networks:
      - api7

networks:
  api7:
    driver: bridge

Step 5: Set image versions and secrets

Replace the following placeholders in your docker-compose.yaml and conf.yaml files:

Placeholder	Description
`${API7_VERSION}`	API7 Enterprise control plane release tag (for example, `3.9.10`). Always pin to an explicit version in production rather than using `latest`.
`YOUR_DB_PASSWORD`	A strong PostgreSQL password. Must be identical in `docker-compose.yaml` and in both `conf.yaml` DSNs.

You can export the control plane version before running Compose:

export API7_VERSION=3.9.10

Step 6: Start the services

docker compose up -d

Check the status of the containers:

docker compose ps

All control plane services should reach the Up (or healthy) state within a minute.

Step 7: Apply your license

Open your browser and navigate to https://localhost:7443. Log in with the default credentials (admin / admin). On first login, the dashboard prompts you to reset the password. After that, the dashboard opens the Activate License screen, where you can upload and activate your license.

Step 8: Verify the control plane

Confirm the Dashboard and DP Manager are reachable:

curl -k -I https://localhost:7443
curl http://localhost:7900/version

Step 9: Add the data plane gateway

In the API7 Dashboard, select a gateway group such as default, navigate to Gateway Instances, and click Add Gateway Instance. Choose Docker and generate the deployment command.

The generated command includes the required environment variables for the data plane, including:

API7_CONTROL_PLANE_ENDPOINTS
API7_GATEWAY_GROUP_SHORT_ID
API7_CONTROL_PLANE_CERT
API7_CONTROL_PLANE_KEY
API7_CONTROL_PLANE_CA

Run the generated docker run command. If your control plane is running in Docker Compose on the same machine, make sure the DP Manager address in the generated command points to an address the gateway container can reach, such as https://host.docker.internal:7943 on Docker Desktop.

Step 10: Verify the data plane

In the API7 Dashboard, go to Gateway Groups > default > Gateway Instances and confirm that the instance is connected and healthy. You should also be able to reach the data plane directly:

curl -i "http://localhost:9080/"

A 404 Not Found response is expected at this point — it confirms that the data plane is running and ready to accept traffic once you create your first route.

Cleanup

To stop the control plane containers and remove the PostgreSQL volume, run:

docker compose down -v

If you started a gateway instance with the generated docker run command, remove it separately:

docker rm -f <gateway-container-name>

Next steps

System Requirements — check production hardware needs.
Deploy on Kubernetes — scale your deployment for production.
Configure the Control Plane — tune CP settings for your environment.

Prerequisites​

Step 1: Create the directory layout​

Step 2: Write the control plane configuration files​

dashboard_conf/conf.yaml​

dp_manager_conf/conf.yaml​

Step 3: Create the PostgreSQL database​

Step 4: Create the Docker Compose file​

Step 5: Set image versions and secrets​

Step 6: Start the services​

Step 7: Apply your license​

Step 8: Verify the control plane​

Step 9: Add the data plane gateway​

Step 10: Verify the data plane​

Cleanup​

Next steps​