Hybrid Docker Deployment

Overview

This guide details the process of deploying the Apidog Enterprise On-Premises using a Hybrid Docker Architecture.

In a hybrid configuration, the Apidog Application runs in a Docker container within self-hosted environment (e.g., a local Linux server or EC2 instance), while the Database (MySQL) and Cache (Redis) are offloaded to managed cloud services (such as AWS RDS, Google Cloud SQL, Azure Database for MySQL, or Amazon ElastiCache).

This approach combines the control of self-hosting the application with the scalability, automated backups, and high availability provided by managed cloud infrastructure.

Requirements & Prerequisites

System Requirements

Docker Version 20.10.0 or higher is required. We recommend the latest stable release (e.g., 26.x).

Verify version: docker --version

Hardware & Software: For hardware and software requirement, please refer to the System Requirements documentation.

External Dependencies

Database: A PostgreSQL or MySQL instance. See Database Configuration.

Storage: An S3-compatible object storage service. See Storage Services Configuration

Docker Registry Access: Ensure you have the Access Token (received via email) to pull the private image.

Preparation: Image Pull

Authenticate with Docker Hub using the credentials provided by the Apidog support team to access the private enterprise image.

Log in to Docker Hub manually to verify credentials

Pull the Image
Enter your Access Token (password) when prompted for the password and pull the specific image tag:

Deployment Approach 1: Docker Run (CLI)

In this approach, we deploy only the Apidog application container. We do not need to create a custom bridge network or deploy database containers locally.

Step 1: Database Initialization

This guide utilizes a MySQL database. If you are using PostgreSQL, please refer to the PostgreSQL Guidelines

Even though the database is in the cloud, Apidog does not automatically create the database. You must manually connect to your Cloud database instance to initialize the database. Once connected, execute:

Step 2: Deploy Apidog Application

Execute the following command.

Important

Replace the MYSQL_HOST and REDIS_HOST variables with your specific Cloud Endpoint URLs and also all placeholder values (e.g., <JWT secret>, <Apaidog On-Premises License>, <Your BASE_URL>, <image_tag> etc.) with your actual configuration details.

For more information on the environment variables and how to configure them, please refer to the Configuration Guide

💡

Configuration Notes:

Database configuration:

If you prefer to use PostgreSQL instead of MySQL, you can set up a PostgreSQL instance and update the relevant environment variables accordingly:

For more details, please refere to Configuration Guide.

Storage configuration:

The s3 storage configuration is required for Kubernetes deployments and is also recommended for Docker based deployment

For non-AWS S3-compatible storage solutions (e.g., MinIO), additional environment variables may be required. These include:

For more details, please refere to Configuration Guide.

Deployment Approach 2: Docker Compose

This approach defines the application service in a streamlined configuration file.

Step 1: Database Initialization

Unlike the Standalone deployment, this Compose file does not include a command instruction to initialize the database (e.g., mysqld --default-authentication...). Since the database is managed by an external cloud provider (like AWS RDS or Azure SQL), the server process and character set configurations are handled directly within your cloud provider's console, not through the Docker container. Consequently, the database must be created manually before starting the application.

Once connected to the cloud database instance, execute the following SQL command to create the database with the required character set:

Step 2: Prepare the Configuration

Unlike the Standalone version, this file will not contain services for mysql or redis. It will define a single service: apidog. Save the following compose.yaml file and modify the environment variables in the compose.yaml file that match your specific configuration (License Key, Base URL, SMTP settings, etc.).

Step 3: Execute Deployment

Run the following command in the directory containing your compose.yaml file.

Restart Commands

Verify System Health Check

Run the internal health check to confirm the application container can reach the external cloud endpoints.

The application has started successfully if the output includes lines similar to the following:

...
[WARN] This Redis server's `default` user does not require a password, but a password was supplied
connect succeeded! value is  null
Executing (default): SELECT 1+1 AS result
...
Connecting to 127.0.0.1:3000 (127.0.0.1:3000)
remote file exists
Connecting to 127.0.0.1 (127.0.0.1:80)
remote file exists
Connecting to 127.0.0.1 (127.0.0.1:80)
remote file exists
Checking BASE_URL: https://your-base-url.com
API base URL matches expected BASE_URL

If the output differs from the above, the application has either not started successfully or is still in the process of starting. A typical graceful startup time is around 30 seconds, though this may vary depending on hardware performance.

Run the application

To run the application, refer to the documentations:

Accessing Apidog Web Interface
Accessing Apidog Admin Panel
Installing Apidog On-Premises Client

Other Resources

Using LDAP for Authentication
Using OKTA for Authentication
Using OAuth2.0 for Authentication
Troubleshooting Guide
Configuration Guide
Updating Apidog
Backing up Apidog
License Renewal

Overview#

Requirements & Prerequisites#

System Requirements#

External Dependencies#

Preparation: Image Pull#

Deployment Approach 1: Docker Run (CLI)#

Step 1: Database Initialization#

Step 2: Deploy Apidog Application#

Deployment Approach 2: Docker Compose#

Step 1: Database Initialization#

Step 2: Prepare the Configuration#

Step 3: Execute Deployment#

Restart Commands#

Verify System Health Check#

Run the application#

Other Resources#

Overview

Requirements & Prerequisites

System Requirements

External Dependencies

Preparation: Image Pull

Deployment Approach 1: Docker Run (CLI)

Step 1: Database Initialization

Step 2: Deploy Apidog Application

Deployment Approach 2: Docker Compose

Step 1: Database Initialization

Step 2: Prepare the Configuration

Step 3: Execute Deployment

Restart Commands

Verify System Health Check

Run the application

Other Resources