Docker Compose Configuration Guide

This document details the Docker Compose configuration options for New API, applicable to various deployment scenarios.

Basic Configuration Structure

The docker-compose.yml file defines New API and its dependencies. The standard configuration prefers PostgreSQL with Redis; MySQL remains available as a compatible alternative.

Standard Configuration (Recommended for Production)

Below is the standard Docker Compose configuration, suitable for most production environments:

# New-API Docker Compose Configuration
#
# Quick Start:
#   1. docker-compose up -d
#   2. Access at http://localhost:3000
#
# Using MySQL instead of PostgreSQL:
#   1. Comment out the postgres service and SQL_DSN line 15
#   2. Uncomment the mysql service and SQL_DSN line 16
#   3. Uncomment mysql in depends_on (line 28)
#   4. Uncomment mysql_data in volumes section (line 64)
#
# ⚠️  IMPORTANT: Change all default passwords before deploying to production!

version: '3.4' # For compatibility with older Docker versions

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    command: --log-dir /app/logs
    ports:
      - '3000:3000'
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    environment:
      - SQL_DSN=postgresql://root:123456@postgres:5432/new-api # ⚠️ IMPORTANT: Change the password in production!
      #      - SQL_DSN=root:123456@tcp(mysql:3306)/new-api  # Point to the mysql service, uncomment if using MySQL
      - REDIS_CONN_STRING=redis://redis
      - TZ=Asia/Shanghai
      - ERROR_LOG_ENABLED=true # Whether to enable error logging
      - BATCH_UPDATE_ENABLED=true # Whether to enable batch update
    #      - STREAMING_TIMEOUT=300  # Streaming timeout in seconds, default is 120s. Increase if experiencing empty completions
    #      - SESSION_SECRET=random_string  # For multi-node deployment, this random string must be changed!
    #      - SYNC_FREQUENCY=60  # Cache synchronization frequency; also the maximum Session stale window with independent Redis

    depends_on:
      - redis
      - postgres
    #      - mysql  # Uncomment if using MySQL
    healthcheck:
      test:
        [
          'CMD-SHELL',
          "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1",
        ]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:latest
    container_name: redis
    restart: always

  postgres:
    image: postgres:15
    container_name: postgres
    restart: always
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: 123456 # ⚠️ IMPORTANT: Change this password in production!
      POSTGRES_DB: new-api
    volumes:
      - pg_data:/var/lib/postgresql/data
#    ports:
#      - "5432:5432"  # Uncomment if you need to access PostgreSQL from outside Docker

#  mysql:
#    image: mysql:8.2
#    container_name: mysql
#    restart: always
#    environment:
#      MYSQL_ROOT_PASSWORD: 123456  # ⚠️ IMPORTANT: Change this password in production!
#      MYSQL_DATABASE: new-api
#    volumes:
#      - mysql_data:/var/lib/mysql
#    ports:
#      - "3306:3306"  # Uncomment if you need to access MySQL from outside Docker

volumes:
  pg_data:
#  mysql_data:

Simplified Configuration (Suitable for Testing)

For testing purposes, you can use the following simplified version, which only includes the New API service itself:

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    ports:
      - '3000:3000'
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/data

Configuration Details

New API Service Configuration

Parameter	Description
`image`	Image name, usually `calciumion/new-api:latest` to get the latest version
`container_name`	Container name, customizable
`restart`	Container restart policy, recommended to set to `always` for automatic restart
`command`	Startup command, customizable startup parameters
`ports`	Port mapping, by default maps container's 3000 port to host's 3000 port
`volumes`	Volume mapping, ensures data persistence
`environment`	Environment variable settings, used to configure New API behavior
`depends_on`	Dependent services, ensures startup in the correct order
`healthcheck`	Health check configuration, used to monitor service status

Environment Variable Description

New API supports various environment variable configurations. Here are some commonly used ones:

Environment Variable	Description	Example
`SQL_DSN`	Database connection string	`postgresql://root:123456@postgres:5432/new-api`
`REDIS_CONN_STRING`	One Redis-compatible connection endpoint	`redis://redis`
`REDIS_POOL_SIZE`	Redis connection pool size	`10`
`TZ`	Time zone setting	`Asia/Shanghai`
`SESSION_SECRET`	Session secret (required for multi-node deployment)	`your_random_string`
`CRYPTO_SECRET`	Cache-key HMAC secret; must match on nodes sharing Redis	Defaults to `SESSION_SECRET`
`NODE_TYPE`	Node type (master/slave)	`master` or `slave`
`SYNC_FREQUENCY`	Cache synchronization frequency and maximum Session-cache stale window with independent Redis (seconds)	`60`

For a more complete list of environment variables, please refer to the Environment Variables Configuration Guide.

Multi-Node Deployment Configuration

For multi-node deployment scenarios, the configuration for master and slave nodes differs slightly:

Master Node Configuration

services:
  new-api-master:
    image: calciumion/new-api:latest
    container_name: new-api-master
    restart: always
    ports:
      - '3000:3000'
    environment:
      - SQL_DSN=postgresql://newapi:123456@your-db-host:5432/new-api
      - REDIS_CONN_STRING=redis://your-master-redis-host:6379 # May be shared with other nodes or dedicated to this node
      - SESSION_SECRET=your_unique_session_secret
      - CRYPTO_SECRET=your_unique_crypto_secret
      - SYNC_FREQUENCY=60
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/data

Slave Node Configuration

services:
  new-api-slave:
    image: calciumion/new-api:latest
    container_name: new-api-slave
    restart: always
    ports:
      - '3001:3000' # Note the different port mapping
    environment:
      - SQL_DSN=postgresql://newapi:123456@your-db-host:5432/new-api # Must point to the same database as the master
      - REDIS_CONN_STRING=redis://your-slave-redis-host:6379 # Use the master's address instead to share Redis
      - SESSION_SECRET=your_unique_session_secret # Must be the same as the master node
      - CRYPTO_SECRET=your_unique_crypto_secret # Must match the master when Redis is shared
      - NODE_TYPE=slave # Set as slave node
      - SYNC_FREQUENCY=60
      - TZ=Asia/Shanghai
    volumes:
      - ./data-slave:/data

Both nodes must use the same SQL_DSN and SESSION_SECRET. Redis can be configured in any of these ways:

Mode	Compose configuration	Session and rate-limit behavior
Shared Redis	Set the same `REDIS_CONN_STRING` and effective `CRYPTO_SECRET` on every node	Session revocation is normally immediate; Redis rate-limit quotas are shared across nodes
Independent Redis per node	Give each node its own `REDIS_CONN_STRING`	Session state falls back to the database and converges within the effective `SYNC_FREQUENCY`; rate-limit quotas are counted per node and the cluster-wide allowance may scale with node count
No Redis	Remove `REDIS_CONN_STRING`	Session validation reads the shared database directly; each node uses its local in-memory rate limiter

The database remains authoritative for Session state and account-level Session limits in all three modes. SYNC_FREQUENCY defaults to 60 seconds. Session cache reads do not renew their TTL; delayed active-cache fills retain only the unused portion of their original database-observation window. With independent Redis, a newly rotated Access JWT may briefly receive 401 responses during the convergence window.

New API accepts one Redis-compatible endpoint in REDIS_CONN_STRING and does not natively parse Redis Cluster or Sentinel node lists. For Redis high availability, use a managed service or proxy that exposes one compatible endpoint.

Usage

Installation

Save the configuration as docker-compose.yml and then run the following command in the same directory:

docker compose up -d

Viewing Logs

docker compose logs -f

Stopping Services

docker compose down

Tip

For more information on using Docker Compose, please refer to the Docker Compose Installation Guide.

Docker Compose Configuration Guide

On this page