docker-compose

Docker compose

NGINX Declarative API can be deployed using docker compose on a Linux virtual machine.

Software prerequisites are:

• docker-compose v2.20+
• jq

Usage:

$ git clone https://github.com/f5devcentral/NGINX-Declarative-API
$ cd NGINX-Declarative-API/contrib/docker-compose
$ ./nginx-dapi.sh 
NGINX Declarative API - https://github.com/f5devcentral/NGINX-Declarative-API/

 This script is used to deploy/undeploy NGINX Declarative API using docker-compose

 === Usage:

 ./nginx-dapi.sh [options]

 === Options:

 -h                             - This help
 -c [start|stop|build]          - Deployment command
 -m [full|dev]                  - Deployment mode: full (with webui container) or dev (backend only for local webui development) (default: full)
 -a <port>                      - Custom port for NGINX Declarative API (default: 5000)
 -w <port>                      - Custom port for Web UI (default: 3000, only for full mode)
 -d <port>                      - Custom port for Developer Portal (default: 5001)
 -r <port>                      - Custom port for Redis (default: 6379)
 -M <port>                      - Custom port for MCP Server (default: 8800)

 === Examples:

 Deploy NGINX Declarative API (full):           ./nginx-dapi.sh -c start
 Deploy in dev mode (no webui container):       ./nginx-dapi.sh -c start -m dev
 Deploy with custom Declarative API port:       ./nginx-dapi.sh -c start -a 8080
 Deploy dev mode with custom ports:             ./nginx-dapi.sh -c start -m dev -a 8080 -d 8081 -r 6380
 Deploy with custom Web UI port:                ./nginx-dapi.sh -c start -w 8080
 Deploy with custom DevPortal port:             ./nginx-dapi.sh -c start -d 8081
 Deploy with custom MCP Server port:            ./nginx-dapi.sh -c start -M 8090
 Deploy with all custom ports:                  ./nginx-dapi.sh -c start -a 8080 -w 8081 -d 8082 -r 6380 -M 8090
 Remove NGINX Declarative API:                  ./nginx-dapi.sh -c stop
 Build docker images:                           ./nginx-dapi.sh -c build

Building docker images

$ ./nginx-dapi.sh -c build
-> Building NGINX Declarative API Docker images
[+] Building 3.6s (24/24) FINISHED
[...]
 => exporting layers
[...]

$ docker images
IMAGE                                                         ID             DISK USAGE   CONTENT SIZE   EXTRA
ghcr.io/f5devcentral/nginx-declarative-api-devportal:latest   01f457fd5336        279MB             0B        
ghcr.io/f5devcentral/nginx-declarative-api-mcp:latest         7cd4c50cdcc7        169MB             0B        
ghcr.io/f5devcentral/nginx-declarative-api-webui:latest       90db23dada16       54.3MB             0B        
ghcr.io/f5devcentral/nginx-declarative-api:latest             3809571bbc8b        115MB             0B   

How to run

1. Start NGINX Declarative API using the provided nginx-dapi.sh script
2. Start Postman using the Postman collection

Starting:

$ ./nginx-dapi.sh -c start
-> Deploying NGINX Declarative API (full mode)
   NGINX Declarative API port: 5000
   Web UI port: 3000
   Developer Portal port: 5001
   Redis port: 6379
   MCP port: 8800
[+] up 6/6
 ✔ Network nginx-dapi_dapi-network Created                                                                                                                                                                    0.0s
 ✔ Container redis                 Started                                                                                                                                                                    0.3s
 ✔ Container devportal             Started                                                                                                                                                                    0.3s
 ✔ Container nginx-dapi-mcp        Started                                                                                                                                                                    0.2s
 ✔ Container nginx-dapi            Started                                                                                                                                                                    0.3s
 ✔ Container nginx-dapi-webui      Started   

Access the Web UI at http://localhost:3000

Local Development Mode

For active development on the Web UI, you can run it locally with hot-reload while keeping the backend services in Docker:

1. Start backend services only:

$ docker-compose -f docker-compose.dev.yaml up -d
[+] Running 4/4
 ✔ Network nginx-dapi_dapi-network  Created 
 ✔ Container redis                  Started 
 ✔ Container devportal              Started 
 ✔ Container nginx-dapi             Started

1. Run Web UI locally:

$ cd ../../webui
$ npm install  # first time only
$ npm run dev

NGINX Declarative API Web UI
  ➜  Local:   http://localhost:3000/

The Vite dev server automatically proxies API requests to the containerized backend on localhost:5000.

Using custom ports:

If you started the backend with a custom DAPI port (e.g., -a 8088), you need to set the corresponding environment variable for the webui:

$ ./nginx-dapi.sh -c start -m dev -a 8088

# Then in the webui directory:
$ cd ../../webui
$ VITE_DAPI_PORT=8088 npm run dev

Or use the script with default ports:

$ ./nginx-dapi.sh -c start -m dev

# Then in the webui directory:
$ cd ../../webui
$ npm run dev  # Defaults to port 5000

Benefits:

• ⚡ Fast hot-reload for UI changes
• 🐛 Full browser debugging capabilities
• 🔧 Backend services isolated in containers
• 🔄 Easy to restart individual services

Starting with custom ports (useful when default ports are in use):

$ ./nginx-dapi.sh -c start -a 8080 -w 8081 -d 8082 -r 6380 -M 8090
-> Deploying NGINX Declarative API (full mode)
   NGINX Declarative API port: 8080
   Web UI port: 8081
   Developer Portal port: 8082
   Redis port: 6380
   MCP port: 8090
[+] up 6/6
 ✔ Network nginx-dapi_dapi-network Created                                                                                                                                                                    0.0s
 ✔ Container nginx-dapi-mcp        Started                                                                                                                                                                    0.3s
 ✔ Container redis                 Started                                                                                                                                                                    0.2s
 ✔ Container devportal             Started                                                                                                                                                                    0.2s
 ✔ Container nginx-dapi            Started                                                                                                                                                                    0.3s
 ✔ Container nginx-dapi-webui      Started     

Stopping:

$ ./nginx-dapi.sh -c stop
-> Undeploying NGINX Declarative API
[+] Running 5/5
 ✔ Container nginx-dapi-webui       Removed
 ✔ Container nginx-dapi             Removed 
 ✔ Container devportal              Removed 
 ✔ Container redis                  Removed 
 ✔ Network nginx-dapi_dapi-network  Removed