Version: 3.10.x

Deploy with Docker Compose

Use Docker Compose to run a complete API7 Gateway deployment on one host for evaluation, local development, or small-scale testing. Choose a quick installation for a ready-to-use stack, or use the manual workflow when you need to customize the control plane or deploy the gateway separately.

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)
curl
A valid API7 Enterprise license. Get a trial license.

Quick Installation

Choose the installation method that matches the host's network access:

Online installation downloads the deployment files and container images from the internet.
Offline installation uses a bundle that contains the deployment files and all required container images.

Both methods create an api7-ee directory and start the Dashboard, DP Manager, data plane gateway, PostgreSQL, Prometheus, and other supporting services. They also create a default gateway group and connect the gateway instance to it.

Online Installation

Use online installation when the host can access the internet and pull container images.

Run the quickstart script:

curl -fsSL "https://run.api7.ai/api7/quickstart" -o api7-quickstart.sh &&
  bash api7-quickstart.sh

The script downloads the current deployment package to ./api7-ee, pulls the container images, and starts the complete service stack.

caution

Run the script from a working directory that does not already contain an api7-ee directory. If the directory exists, the script stops the existing quickstart deployment before reinstalling it.

Offline Installation

Use the offline bundle when the target host cannot access the internet or a container registry. The bundle URLs resolve to the current release.

On the offline host, identify its CPU architecture:

uname -m

On a machine with internet access, download the bundle that matches the output from the offline host. The download machine and offline host do not need to use the same architecture.

AMD64 (`x86_64`)

curl -fSL "https://download.apiseven.com/api7-ee/api7-ee-offline-latest.tar.gz" \
  -o api7-ee-offline.tar.gz

ARM64 (`arm64` or `aarch64`)

curl -fSL "https://download.apiseven.com/api7-ee/api7-ee-offline-arm64-latest.tar.gz" \
  -o api7-ee-offline.tar.gz

Transfer api7-ee-offline.tar.gz to the offline host, then extract it and start the service stack:

tar -xzf api7-ee-offline.tar.gz
cd api7-ee
bash run.sh

The startup script loads the bundled container images before starting the services. No internet or external container registry access is required on the target host.

Verify the Deployment

Enter the deployment directory if you are not already in it, then check the container status:

cd api7-ee
docker compose ps
docker ps --filter "name=api7-ee-gateway-1"

The gateway runs as a separate container, so it does not appear in docker compose ps. Wait until the Compose services and api7-ee-gateway-1 are running, then verify the Dashboard and gateway:

curl -k -I "https://127.0.0.1:7443/"
curl -i "http://127.0.0.1:9080/"

A response from the Dashboard and a 404 Not Found response from the gateway confirm that the complete stack is running. The gateway returns 404 Not Found until you create a route.

Open https://<host-ip>:7443/ in a browser and log in with the default credentials (admin / admin). Change the default password when prompted, then upload and activate your API7 Enterprise license.

The package also includes an optional Developer Portal frontend. After activating a license that includes the API7 Portal feature, follow Start a Local Developer Portal to run it.

The primary API7 services use the following ports:

Port	Component
`3001`	Developer Portal frontend over HTTP (default)
`4321`	Portal API backend over HTTPS
`7443`	Dashboard and Admin API over HTTPS
`7900`	DP Manager over HTTP
`7943`	DP Manager over HTTPS and mTLS
`9080`	Gateway traffic over HTTP
`9443`	Gateway traffic over HTTPS

Allow the required ports through the host firewall before accessing API7 Gateway from another machine. See System Requirements for component communication requirements.

Manage the Deployment

Run management commands from the api7-ee directory. To follow logs for the Compose services:

docker compose logs -f

Press Ctrl+C to stop following the logs. To follow the gateway logs instead:

docker logs -f api7-ee-gateway-1

To stop the deployment without removing its containers:

docker stop api7-ee-gateway-1
docker compose stop

Restart the Compose services before restarting the gateway:

docker compose start
until curl -fsS "http://127.0.0.1:7900/version" > /dev/null; do
  sleep 2
done
docker start api7-ee-gateway-1

When you finish the evaluation, remove the gateway and Compose containers:

docker rm -f api7-ee-gateway-1
docker compose down

PostgreSQL and Prometheus data remain under the api7-ee directory after these commands. Do not delete this directory while you need the deployment data.

Manual Deployment

Use the following workflow when you need to customize the control plane configuration or deploy the data plane separately. Docker Compose brings up the control plane components on one host, and the Dashboard generates a Docker command that bootstraps the data plane gateway with the required mTLS credentials.

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 connection strings 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
    volumes:
      - prometheus_data:/opt/bitnami/prometheus/data
    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
    volumes:
      - postgresql_data:/bitnami/postgresql
    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

volumes:
  prometheus_data:
  postgresql_data:

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 Gateway control-plane image tag (for example, `v3.10.5`). 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` connection strings.

You can export the control plane version before running Compose:

export API7_VERSION=v3.10.5

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 generated DP Manager address is reachable from the gateway container.

For example, use 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.

Clean Up the Manual Deployment

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

docker rm -f YOUR_GATEWAY_CONTAINER_NAME

Then stop the control plane containers and remove the PostgreSQL and Prometheus volumes:

docker compose down -v

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​

Quick Installation​

Online Installation​

Offline Installation​

AMD64 (x86_64)​

ARM64 (arm64 or aarch64)​

Verify the Deployment​

Manage the Deployment​

Manual Deployment​

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​

Clean Up the Manual Deployment​

Next Steps​