nacos-docker: Running Nacos 3.x with Docker

Why nacos-docker Exists and Which Deployments It Covers

nacos-docker addresses the operational gap between the main Nacos repository and a container deployment. Its stated purpose is to facilitate deployment of Nacos by providing Docker images, Compose examples, environment files, and the source used to build the image. The target audience is engineers who already need Nacos and want to package it as a Docker service rather than learn the image layout from scratch.

The repository covers several deployment shapes through its example files. These include standalone Derby, standalone MySQL, standalone independent MySQL, and a hostname-based Nacos cluster. There are also files for embedded and IP-based clusters, AI registry operation, custom application configuration, custom plugins, and Prometheus-related setup. That breadth is useful when comparing configurations, but it also means the examples are not interchangeable. The filename indicates the topology being assembled, while the Compose file defines the actual services and environment.

The project is not the Nacos application source itself. Its primary language is Shell, and its repository separates the image build code under `build/` from Compose assets under `example/` and shared environment data under `env/`. That distinction matters during review: an application feature request may belong in the main Nacos project, while image entrypoint behavior, container defaults, or Compose deployment configuration belongs here.

A notable boundary is explicit. The database master-slave image is no longer provided, and the README refers readers to the project wiki for the removal rationale. Teams whose design assumes that particular container image cannot adopt this repository unchanged. For custom databases, the operator must initialize the database script during the first setup.

Image Entry Points, Compose Topology, and Configuration Flow

The documented quick start passes deployment choices through environment variables when Docker starts `nacos/nacos-server`. `MODE=standalone` selects standalone operation, while three authentication variables supply a secret token and server identity values. Port publishing exposes the documented server endpoints. The image is therefore the execution layer, while `MODE`, credentials, ports, and database-related configuration form the operator-controlled deployment boundary.

Compose users receive the same basic model through files in `example/`. The repository includes `standalone-derby.yaml`, `standalone-mysql.yaml`, `standalone-independent-mysql.yaml`, and `cluster-hostname.yaml`. The last example uses a different startup sequence, including a build flag, which indicates that its services are not merely another way to publish the same container. Cluster operation also depends on `NACOS_SERVERS` or the configuration used by the selected cluster file.

The default mode listed in the property table is `cluster`, so omitting `MODE` is not equivalent to choosing a local single-node installation. Other listed properties shape functionality and topology. `FUNCTION_MODE` accepts `config`, `naming`, `microservice`, `ai`, or `all`, with different defaults depending on the image variant. `NACOS_SERVERS` accepts cluster addresses in `ip1:port1 ip2:port2 ip3:port3` form.

The README also separates Standard and Slim image variants. Both support `linux/amd64` and `linux/arm64`, and the documentation states that Arm Macs do not require Slim. This is a packaging distinction rather than a change to Nacos itself. Based on the repository layout, Compose files are executable examples that should be inspected as deployment configuration, not treated as a complete configuration reference.

Starting Nacos 3.x as a Local Standalone Container

The shortest documented Nacos 3.x path uses the `latest` image, standalone mode, explicit authentication values, and ports `8080`, `8848`, and `9848`. Replace the shell placeholders with deployment values before running the command. This starts from the official quick-start configuration rather than the Compose examples.

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

The command names the container `nacos-standalone-derby`, passes its security values as environment variables, publishes three ports, and requests detached execution. The README does not provide expected container output, so the first operational check described by the project is the later console initialization and API flow.

For Nacos 3.3 and later, `nacos.core.auth.enabled` follows Client API authentication by default when `NACOS_AUTH_ENABLE` is unset. The README explicitly permits setting `NACOS_AUTH_ENABLE=true` or `NACOS_AUTH_ENABLE=false`. That choice is independent of `NACOS_AUTH_ADMIN_ENABLE` and `NACOS_AUTH_CONSOLE_ENABLE`. Setting one does not change the others. The documentation describes explicit `false` as a temporary upgrade compatibility option while clients are being configured with credentials, not as a production target.

Cloning the Repository for Derby, MySQL, or Cluster Examples

The repository-based workflow starts by cloning `nacos-docker` and entering its directory. The example environment file selects `v3.3.0-RC` in the documented configuration. A Slim deployment uses the corresponding `v3.3.0-RC-slim` tag when that packaging variant is desired.

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

After cloning, the README gives separate commands for each topology. Derby needs no separate database initialization command in its documented startup path:

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

The MySQL example invokes the repository's initialization script before Compose. The command is documented from the repository root and should be run there:

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

Only Nacos 3.x supports the standalone independent MySQL example. Its documented sequence is:

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

The cluster-hostname example is presented differently because it builds as part of startup:

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

These commands should not be treated as one generic startup path. Select the file that matches the required database and topology, then review its service definitions before exposing ports outside the local environment.

Initializing Authentication and Exercising Nacos APIs

On a new Nacos 3.3 deployment, the README says to open `http://127.0.0.1:8080/` and initialize the administrator password first. Client API requests require login by default in this release line. The documented login endpoint uses the default `nacos` username with the password initialized through the console.

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

The returned access token is then passed in the `accessToken` header for the documented client operations. Service registration is a POST request that includes the service name, instance IP, and instance port:

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 reads the instance list for that same service name:

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

Configuration publishing uses the admin config endpoint, while retrieval uses the client config endpoint:

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}"

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}"

The differing admin and client paths are a concrete sign that API authentication boundaries matter. A token that works for one path should not be assumed to remove authentication from another.

Database, Release, Maintenance, and Licensing Boundaries

The repository documents a database compatibility change for Nacos versions since 1.3.1 and states that database storage was upgraded to 8.0 with backward compatibility. This is a claim about the documented storage compatibility, not a guarantee for every external database arrangement. With a custom database, the operator must apply the linked `nacos-datasource-plugin-mysql/src/main/resources/META-INF/mysql-schema.sql` script during the first initialization.

Version selection is an explicit operational choice. The examples reference `v3.3.0-RC`, while the release list also includes `v3.2.4`, `v2.5.4`, and `v3.3.0-RC`. The README presents separate quick starts for Nacos v3.x and v2.x because authentication defaults differ. Earlier versioned images continue to use defaults built into those images, so a tag change can alter behavior without changing the repository code.

The repository is not archived, and its last push was on 2026-09-23. That is recent maintenance activity based on the repository record, but it does not remove upgrade work. Operators must still review release notes, image tags, authentication changes, database requirements, and Compose files before changing versions. The repository contains both image build sources and deployment examples, so a container tag can package application changes and infrastructure changes at once.

The project is licensed under Apache-2.0. That identifier tells reviewers the stated license, but it does not establish legal suitability for a particular deployment. The documentation also warns that credentials committed in the repository are for local examples only and must not be reused in production. Production deployments should supply unique, strong token and server identity values.

Editorial conclusion

Adopt nacos-docker when the deployment target is Nacos and container packaging is acceptable. Do not choose it if you require the removed database master-slave image or need an undocumented image-building procedure. First verify the selected Nacos tag, authentication settings, exposed ports, database initialization, and whether the example configuration matches the intended standalone or cluster topology.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. nacos-group/nacos-docker on GitHub
4. README
5. Releases