Prerequisites

Before starting, ensure Docker is installed on your system. This guide covers the complete setup process for running YAPI, an efficient API management tool, within Docker containers.

Step 1: Launch MongoDB

YAPI reuqires MongoDB as its backend database. Create a dedicated volume and start the database container:

docker volume create mongo-data

docker run -d \
  --name mongo-yapi \
  -v mongo-data:/data/db \
  -e MONGO_INITDB_ROOT_USERNAME=yapi_admin \
  -e MONGO_INITDB_ROOT_PASSWORD=secure_pass \
  mongo

Step 2: Pull YAPI Image

Fetch the YAPI Docker image from the registry:

docker pull registry.cn-hangzhou.aliyuncs.com/anoyi/yapi

Step 3: Create Configuration File

Create a config.json file with your databace and server settings:

{
  "port": "3000",
  "adminAccount": "admin@example.com",
  "timeout": 120000,
  "db": {
    "servername": "mongo",
    "DATABASE": "yapi",
    "port": 27017,
    "user": "yapi_admin",
    "pass": "secure_pass",
    "authSource": "admin"
  }
}

Store this file at /opt/yapi/config.json.

Step 4: Initialize Database

Run the initialization script to set up the database schema and create the admin acccount:

docker run -it --rm \
  --link mongo-yapi:mongo \
  --entrypoint npm \
  --workdir /yapi/vendors \
  -v /opt/yapi/config.json:/yapi/config.json \
  registry.cn-hangzhou.aliyuncs.com/anoyi/yapi \
  run install-server

Step 5: Start YAPI Service

Launch the YAPI application container:

docker run -d \
  --name yapi \
  --link mongo-yapi:mongo \
  --workdir /yapi/vendors \
  -p 3000:3000 \
  -v /opt/yapi/config.json:/yapi/config.json \
  registry.cn-hangzhou.aliyuncs.com/anoyi/yapi \
  server/app.js

Step 6: Access YAPI

Open your browser and navigate to http://localhost:3000. Log in with the administrator credentials you configured in config.json.

Troubleshooting Common Issues

Read-Only File System Error

If you encounter Error: EROFS: read-only file system during container startup, the issue typically stems from cgroup mounting restrictions. This error often appears when running in certain container environments.

Assertion Function Not Working

When mock assertion features fail with assert.equal is not a function, you need to patch the sandbox module.

Solution

Access the container as root:

docker exec -u root -it <container_id> /bin/sh

Navigate to /yapi/vendors/server/utils and modify sandbox.js:

const Safeify = require('safeify').default;

module.exports = async function sandboxFn(context, script) {
    const safeVm = new Safeify({
        timeout: 3000,
        asyncTimeout: 60000,
        unrestricted: true,
        unsafe: {
            modules: {
                assert: 'assert'
            }
        }
    });
    
    safeVm.preset('const assert = require("assert");');
    
    script += `; return {
        Function: this.Function,
        eval: this.eval,
        header: this.header,
        query: this.query,
        body: this.body,
        mockJson: this.mockJson,
        params: this.params,
        resHeader: this.resHeader,
        httpCode: this.httpCode,
        delay: this.delay,
        Random: this.Random,
        cookie: this.cookie
    }`;

    const result = await safeVm.run(script, context);
    safeVm.destroy();
    return result;
};

Apply the fix by restarting the container:

docker restart <container_id>

Network Configuration

For multi-container setups, create a shared network:

docker network create yapi-network
docker network connect yapi-network mongo-yapi
docker network connect yapi-network yapi

Update the config.json to use service names as hostnames when containers are on the same network.