Nacos Quick Start

This Quick Start Guide helps you quickly download, install, and use Nacos on your computer.

0. Choose A Version

This page describes Nacos 3.3. Select an available release from the download page and read its release notes. Use the matching RC artifacts for RC validation and a stable release for production.

1. Prerequisites

Nacos relies on a Java environment to run. Please ensure you have the following environment set up:

1. 64-bit OS, supporting Linux/Unix/Mac/Windows. Linux/Unix/Mac is recommended.
2. 64-bit JDK 17+; Download & Configure.

2. Download and Start Nacos

2.1. One-Click Deployment with nacos-setup (Recommended)

nacos-setup provides one-click automated deployment, automatically handling download, authentication configuration, port detection, and Java environment verification.

Install nacos-setup:

Start Nacos. For a specific 3.3 release, set NACOS_VERSION to an available version from the download page first; the default command selects the latest release and may not select the RC you want to validate.

# One-click deploy the latest standalone Nacos
nacos-setup

# One-click deploy a specific version of standalone Nacos
nacos-setup -v "${NACOS_VERSION}"

# One-click deploy the latest Nacos cluster
nacos-setup -c cluster

# Configure external storage globally, enter database address, port, username and password, then re-run nacos-setup
nacos-setup --datasource-conf

For more usage, please refer to One-Click Deployment with nacos-setup.

2.2. Manual Download and Deployment

2.2.1. Download the Package

You can obtain the Nacos distribution package through the Nacos official website or Github.

2.2.2. Extract the Nacos Distribution Package

  unzip nacos-server-$version.zip
  # or tar -xvf nacos-server-$version.tar.gz
  cd nacos/bin

2.2.3. Start the Server

• Note: Nacos is recommended to run on machines with at least 2 CPU cores, 4GB RAM, and 60GB disk space.

Nacos 3.3 enables Client, Admin, and Console authentication by default. The startup script prompts for three missing settings: a token signing secret (valid Base64 decoding to at least 32 bytes) and the server identity key/value. These server settings are separate from the username and password used to log in. Example prompts:

`nacos.plugin.auth.nacos.token.secret.key` is missing, please set with Base64 string: ${your_input_token_secret_key}
nacos.plugin.auth.nacos.token.secret.key` Updated:
----------------------------------
`nacos.core.auth.server.identity.key` is missing, please set: ${your_input_server_identity_key}
`nacos.core.auth.server.identity.key` Updated:
----------------------------------
`nacos.core.auth.server.identity.value` is missing, please set: ${your_input_server_identity_value}
`nacos.core.auth.server.identity.value` Updated:
----------------------------------

3. Verify Nacos Service Started Successfully

Navigate to the ${nacos.home}/logs/ directory and use tail -f start.out to view the logs. If you see the following log, the service has started successfully.

Nacos started successfully in stand alone mode. use embedded storage

You can use the following services to quickly verify Nacos functionality.

3.1. Nacos Console Page

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

Note: The first time you open it, you will be asked to initialize the password for the admin 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. Shutdown Server

4.1. Linux/Unix/Mac

sh shutdown.sh

4.2. Windows

shutdown.cmd

Or double-click the shutdown.cmd file to run it.

Related Projects

• Nacos
• nacos-setup