Nacos Docker Quick Start

This quick start guide helps you quickly deploy and use Nacos in a Docker container through the Nacos Docker image.

1. Prepare the Environment

To install and deploy Nacos using this quick start method, install Docker.

2. Start Nacos

When this command is executed for the first time, the required Docker images are automatically downloaded. The waiting time depends on your network speed. You can also download the images in advance to reduce the waiting time when running the deployment command.

In Bash, set NACOS_VERSION to an available target image tag, NACOS_AUTH_TOKEN to a deployment-specific Base64 secret decoding to at least 32 bytes, and NACOS_AUTH_IDENTITY_KEY / NACOS_AUTH_IDENTITY_VALUE to nonempty server identity values. Use the matching image tag for 3.3 RC validation; do not assume latest points to the RC.

docker run --name nacos-standalone-derby \
    -e MODE=standalone \
    -e NACOS_AUTH_ENABLE=true \
    -e NACOS_AUTH_TOKEN="${NACOS_AUTH_TOKEN}" \
    -e NACOS_AUTH_IDENTITY_KEY="${NACOS_AUTH_IDENTITY_KEY}" \
    -e NACOS_AUTH_IDENTITY_VALUE="${NACOS_AUTH_IDENTITY_VALUE}" \
    -p 8080:8080 \
    -p 8848:8848 \
    -p 9848:9848 \
    -d "nacos/nacos-server:${NACOS_VERSION}"

3. Verify Whether Nacos Started Successfully

Run docker logs -f $container_id to view the Nacos startup logs. If you see the following log, the service has started successfully.

Nacos started successfully in xxxx mode. use xxxx storage

You can quickly verify Nacos features with the following services.

3.1. Nacos Console Page

Open any browser and enter http://127.0.0.1:8080 to access the Nacos console page.

Note: The first time you open the console, you are asked to initialize the password for the administrator user nacos.

3.1.1. Obtain An Access Token

Run the following commands in Bash (Git Bash or WSL on Windows). Replace the password with the administrator password you initialized, then copy accessToken from the login response into NACOS_ACCESS_TOKEN:

export NACOS_USERNAME='nacos'
export NACOS_PASSWORD='<your-initialized-password>'
curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
  --data-urlencode "username=${NACOS_USERNAME}" \
  --data-urlencode "password=${NACOS_PASSWORD}"

export NACOS_ACCESS_TOKEN='<accessToken-from-login-response>'

Both Client and Admin API calls below use this token. Log in again after it expires. Applications should use an account with the required resource permissions; see Access Credentials.

3.2. 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: ${NACOS_ACCESS_TOKEN}"

3.3. Service Discovery

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

3.4. Publish Configuration

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

3.5. Get Configuration

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

If authentication fails, check the username, password, token validity, and account permissions. Explicitly disabling Client authentication is a temporary migration option for existing clients without credentials; see the Upgrade Guide.

4. More Nacos Docker Use Cases

The Nacos community provides a series of Docker Compose files. You can refer to these files to deploy Nacos in more scenarios.

To install and deploy Nacos using this quick start method, use Docker Compose.

4.1. Download the nacos-docker Project

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

4.2. Use docker-compose to Start Nacos