Nacos Docker

This project contains a Docker image meant to facilitate the deployment of Nacos.

中文

Note

The following environment variables have been removed from the default values in the new version(Nacos 2.2.1) for the sake of system security, please add them yourself when starting up, otherwise an error will be reported at startup.

1. NACOS_AUTH_IDENTITY_KEY
2. NACOS_AUTH_IDENTITY_VALUE
3. NACOS_AUTH_TOKEN

Starting with Nacos 3.3, Client API authentication (nacos.core.auth.enabled) is enabled by default when NACOS_AUTH_ENABLE is unset. Set NACOS_AUTH_ENABLE=true or NACOS_AUTH_ENABLE=false to override it explicitly. Explicit false is available as a temporary upgrade-compatibility option while clients are being configured with credentials. Earlier versioned images continue to use the defaults built into those image versions.

Client API authentication is independent of Admin API and Console API authentication. This default change does not disable or otherwise change NACOS_AUTH_ADMIN_ENABLE or NACOS_AUTH_CONSOLE_ENABLE. Use unique, strong token and server identity values in production; credentials committed in this repository are for local examples only and must not be reused.

Project directory

• build：Nacos makes the source code of the docker image
• env: Environment variable file for compose yaml
• example: Docker compose example for Nacos server

Precautions

• The database master-slave image is no longer provided. For specific reasons, refer to Removing the Master-Slave Image Configuration
• Since Nacos 1.3.1 version, the database storage has been upgraded to 8.0, and it is backward compatible
• If you use a custom database, you need to initialize the database script yourself for the first time.

Quick Start

Nacos v3.x

docker run --name nacos-standalone-derby \
    -e MODE=standalone \
    -e NACOS_AUTH_TOKEN=${your_nacos_auth_secret_token} \
    -e NACOS_AUTH_IDENTITY_KEY=${your_nacos_server_identity_key} \
    -e NACOS_AUTH_IDENTITY_VALUE=${your_nacos_server_identity_value} \
    -p 8080:8080 \
    -p 8848:8848 \
    -p 9848:9848 \
    -d nacos/nacos-server:latest

Nacos v2.x

docker run --name nacos-standalone-derby-v2.5.1 \
    -e MODE=standalone \
    -e NACOS_AUTH_ENABLE=true \
    -e NACOS_AUTH_TOKEN=${your_nacos_auth_secret_token} \
    -e NACOS_AUTH_IDENTITY_KEY=${your_nacos_server_identity_key} \
    -e NACOS_AUTH_IDENTITY_VALUE=${your_nacos_server_identity_value} \
    -p 8848:8848 \
    -p 9848:9848 \
    -d nacos/nacos-server:v2.5.1

Advanced Usage

• Tips: You can change the version of the Nacos image in the compose file from the following configuration. example/.env

NACOS_VERSION=v3.3.0-RC

Both Standard and Slim support linux/amd64 and linux/arm64; Arm Macs do not require the Slim variant. Example Slim tag:

NACOS_VERSION=v3.3.0-RC-slim

Run the following command：

• Clone project

  git clone --depth 1 https://github.com/nacos-group/nacos-docker.git
  cd nacos-docker
  

• Standalone Derby

  docker compose -f example/standalone-derby.yaml up
  

• Standalone Mysql

  cd example
  ./mysql-init.sh && docker compose -f standalone-mysql.yaml up
  

• Standalone Independent Mysql（Only Nacos 3.x is supported）

  cd example
  ./mysql-init.sh && docker compose -f standalone-independent-mysql.yaml up
  

• Standalone Nacos Cluster

  bash example/mysql-init.sh
  docker compose -f example/cluster-hostname.yaml up --build
  

• Log in (required for Client API requests by default in Nacos 3.3 and later)

  On a new deployment, open http://127.0.0.1:8080/ to initialize the administrator password first.

  curl -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' -d 'username=nacos' -d "password=${your_password}"
  

• Service registration

  curl -X POST 'http://127.0.0.1:8848/nacos/v3/client/ns/instance?serviceName=quickstart.test.service&ip=127.0.0.1&port=8080' -H "accessToken:${your_access_token}"
  

• Service discovery

  curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/ns/instance/list?serviceName=quickstart.test.service' -H "accessToken:${your_access_token}"
  

• Publish config

  curl -X POST 'http://127.0.0.1:8848/nacos/v3/admin/cs/config?dataId=quickstart.test.config&groupName=test&content=HelloWorld' -H "accessToken:${your_access_token}"
  

• Get config

    curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/cs/config?dataId=quickstart.test.config&groupName=test' -H "accessToken:${your_access_token}"
  

• Open the Nacos console in your browser

  link：http://127.0.0.1:8080/

Common property configuration

Advanced configuration

Copy build/conf/application.properties, customize it, and mount it at /home/nacos/conf/application.properties. Migrate older settings into the 3.3 template and retain the environment placeholders; do not replace it with an entire 2.x/3.2 configuration. The custom configuration example mounts example/init.d/application.properties:

bash example/mysql-init.sh
docker compose -f example/custom-application-config.yaml up --build

If you need to load extra plugin jars or dependency jars without rebuilding the image, mount those directories into the container and append them through NACOS_EXT_PLUGIN_DIRS.

For example:

docker compose -f example/custom-plugin-dir.yaml up -d

docker run --name nacos-standalone \
  -e MODE=standalone \
  -e NACOS_AUTH_TOKEN=${your_nacos_auth_secret_token} \
  -e NACOS_AUTH_IDENTITY_KEY=${your_nacos_server_identity_key} \
  -e NACOS_AUTH_IDENTITY_VALUE=${your_nacos_server_identity_value} \
  -e NACOS_EXT_PLUGIN_DIRS=/home/nacos/ext-plugins,/home/nacos/ext-libs \
  -v /path/to/plugins:/home/nacos/ext-plugins \
  -v /path/to/libs:/home/nacos/ext-libs \
  -p 8080:8080 \
  -p 8848:8848 \
  -p 9848:9848 \
  -d nacos/nacos-server:latest

This is useful when a plugin jar and its runtime dependency jars need to be mounted separately. For example, an LDAP deployment can mount the LDAP auth plugin jar in one directory and the required spring-ldap-core dependency jars in another.

Upgrade to 3.3.0-RC

This branch's Dockerfiles and configuration template target 3.3.0-RC and retain Java 17. To build older Nacos versions, use the corresponding repository revision; changing only NACOS_VERSION back to 3.2 is not supported by this template.

1. Back up the database and each node's data, configuration and plugins. Apply reviewed incremental DDL from the target schema. mysql-init.sh and the MySQL example Dockerfiles initialize new databases; they do not upgrade existing MySQL volumes.
2. Add ai_resource_search_document, ai_resource_search_chunk, ai_resource_task and their indexes to external databases. Search is enabled by default. NACOS_AI_RESOURCE_SEARCH_ENABLED=false temporarily disables it, but ARD then cannot be enabled. Check the actual permissions.resource size and other database-specific changes; never replay the full initialization SQL against production data.
3. Docker variable names are retained. Auth properties now use nacos.plugin.auth.*, the dialect uses nacos.plugin.datasource-dialect.type, and JDBC/pool settings use nacos.plugin.datasource.db.*. Canonical keys override legacy aliases even when empty. Auth gates and server identity remain under nacos.core.auth.*.
4. Client API authentication defaults to enabled. Initialize the administrator password in Console on a new deployment, then log in for an accessToken. Set NACOS_AUTH_ENABLE=false explicitly during a client migration window. All members must share the token secret and server identity; JRaft still needs server identity with Client auth disabled.
5. Retain each node's existing data. Plugin states and runtime configuration live under data/plugin; persisted overrides take precedence over static settings. .enabled supplies initial state, so update existing states through plugin management. RESTART properties still require a restart. Never share one data volume between nodes.
6. Mount only plugins verified for 3.3. Old AI Pipeline Builders, AI Resource Import SPIs and removed Config migration Mappers require migration. Follow the official runbook for historical A2A/MCP, Raft data and rollback boundaries; changing the image tag alone is not a rollback plan.

See the 3.3.0-RC release notes and next upgrade manual.

Persistent data and optional capabilities

Compose examples mount a separate named volume at /home/nacos/data for each Nacos service, including independent Console. Reuse that volume when replacing the image. docker compose down -v deletes the volumes and their data. Cluster Console host ports are 8080, 8081 and 8082.

If an older deployment has no data mount, copy /home/nacos/data out of each old container before recreating it (for example, docker cp <container>:/home/nacos/data ./data-backup). Restore that data into the new volume, or bind-mount the copied directory. Adding an empty volume does not migrate data from the old container layer.

Standard/Slim store bundled AI archives in /home/nacos/data-seed. Startup copies only missing zip files to data, preserving existing archives and supporting empty bind mounts. The volume retains plugin state, Derby and Raft files.

# MCP, Skill and ARD share port 9080; authentication remains enabled
docker compose -f example/standalone-ai-registry.yaml up

NACOS_AI_REGISTRY_ENABLED continues to control only MCP; Skill and ARD have separate switches. Update Compose port mappings when changing Registry/DNS ports. Private-network MCP tool imports require an explicit IP/CIDR allowlist.

Standard/Slim bundle Skill Scanner and disable SkillSpector by default. Install or mount the SkillSpector runtime before setting its command and enabling it; existing persisted states may also need updating in Console. Lite defaults to FUNCTION_MODE=microservice with Pipeline disabled and bundles no Python, scanners or AI archives. The existing build/Dockerfile.Lite is for local builds; the publishing workflow releases only Standard/Slim.

Local validation

bash test/auth-defaults.sh
bash test/mysql-init.sh
docker build -f build/Dockerfile -t nacos-smoke:test build
bash example/mysql-init.sh
python3 test/docker-smoke.py --image nacos-smoke:test --mysql

Image tests cover default auth, explicit Client auth opt-out, configuration mapping, a custom Registry port, DNS TCP/UDP, persisted plugin configuration/state after container replacement, MySQL and independent Console. Tests create isolated containers, networks and volumes and remove their own resources on exit.

Nacos + Grafana + Prometheus

Usage reference：Nacos monitor-guide

Note: When Grafana creates a new data source, the data source address must be http://prometheus:9090