Nacos Native Quick Start

This quick start guide is designed to help you quickly download, install, and use Nacos on your computer.

Starting with Nacos 3.3.0, Nacos supports the Native build and runtime workflow described here. This guide builds a platform-specific executable from source for standalone, merged Server and Console deployment with external MySQL on Linux/macOS.

For ordinary JDK deployment, see the standard quick start.

1. Prepare the Build Environment

• Use Nacos 3.3.0 sources and run the following commands from the source root.
• Install Maven and set JAVA_HOME to GraalVM 25+ with native-image, as required by the Spring Boot 4 Native toolchain.
• Install the platform C/C++ toolchain and system libraries. Ubuntu uses build-essential and zlib1g-dev; macOS uses Xcode Command Line Tools. See the GraalVM Native Image prerequisites for other platforms.
• The Native builder heap limit defaults to 8g. Adjust it with nacos.native.build.heap.

export JAVA_HOME='/path/to/graalvm-25'
export PATH="$JAVA_HOME/bin:$PATH"
java -version
native-image --version
mvn -version

Build with an operating system, CPU architecture, and system libraries matching the runtime environment. This guide uses Linux/macOS startup scripts.

2. Build the Native Distribution

2.1. Select Build Settings and Plugins

Select the database type at build time to include its components. Configure database connections, credentials, and authentication when deploying in section 3.

Create a work directory beside the source directory to hold build settings, additional plugins, and reachability metadata so Maven clean does not remove them:

export NACOS_VERSION='3.3.0'
export NACOS_NATIVE_WORK="$(cd .. && pwd)/nacos-native-work"
mkdir -p "$NACOS_NATIVE_WORK/plugins" "$NACOS_NATIVE_WORK/metadata"
printf '%s\n' 'nacos.plugin.datasource-dialect.type=mysql' > "$NACOS_NATIVE_WORK/build.properties"

The native profile includes the default plugins. For custom SPI plugins or additional JDBC drivers, place their JARs and all dependencies in $NACOS_NATIVE_WORK/plugins. Maven runtime dependencies can also provide these implementations. Prepare the corresponding Native metadata when using external MySQL, PostgreSQL, or custom plugins.

Metadata shipped in a plugin’s META-INF/native-image directory participates in compilation. Place additional metadata in $NACOS_NATIVE_WORK/metadata. Before building, confirm that it covers the selected plugins and drivers. If reflection, JNI, or resource metadata needs to be collected, follow the appendix before running the build command below.

2.2. Run the Build

Run this command from the source root:

mvn -B '-Pnative,release-native,!dev' -pl distribution -am clean package \
  -DskipTests \
  -Dnacos.native.config="$NACOS_NATIVE_WORK/build.properties" \
  -Dnacos.native.metadata="$NACOS_NATIVE_WORK/metadata" \
  -Dnacos.native.plugins="$NACOS_NATIVE_WORK/plugins" \
  -Dnacos.native.deployment=merged \
  -Dnacos.native.standalone=true

Enable both native and release-native to compile Native Image and package the distribution. The example uses -DskipTests to skip unit tests.

The build produces:

• Executable: bootstrap/target/native/nacos-server (.exe on Windows).
• Distribution: distribution/target/nacos-server-<version>-native-<os>-<arch>.tar.gz, plus a ZIP package. For example, macOS ARM64 uses the suffix native-macos-aarch64.

The package contains the executable, companion native libraries, configuration templates, scripts, and the AOT structural manifest.

3. Prepare the Database and Runtime Configuration

Extract the package produced by your build. For example, on macOS ARM64:

mkdir -p "$NACOS_NATIVE_WORK/run"
tar -xzf "distribution/target/nacos-server-${NACOS_VERSION}-native-macos-aarch64.tar.gz" \
  -C "$NACOS_NATIVE_WORK/run"
cd "$NACOS_NATIVE_WORK/run/nacos"

On Linux, replace the suffix with the actual native-linux-<arch> from your build. Apply the following settings to conf/application.properties in the extracted directory.

3.1. Prepare MySQL

Follow the datasource plugin guide to create a MySQL database and import the schema for the selected version. Configure the database connection, replacing the example address and credentials with your own:

nacos.plugin.datasource-dialect.type=mysql
nacos.plugin.datasource.db.num=1
nacos.plugin.datasource.db.url.0=jdbc:mysql://127.0.0.1:3306/nacos_native_test?characterEncoding=utf8&useSSL=false&serverTimezone=UTC
nacos.plugin.datasource.db.user=nacos_native_test
nacos.plugin.datasource.db.password=<test-database-password>

Keep the database type set to MySQL to match the build. See section 5 for other settings that must remain consistent.

3.2. Configure Authentication

nacos.core.auth.server.identity.key=native-test
nacos.core.auth.server.identity.value=<test-server-identity>
nacos.plugin.auth.nacos.token.secret.key=<base64-token-secret>

Nacos 3.3 enables authentication by default. When using the default authentication plugin, fill in the server identity and token signing secret above:

• The token signing secret signs and verifies login tokens. It must be a valid Base64 string that decodes to at least 32 bytes. Use openssl rand -base64 32 to generate a random secret, or generate one yourself that meets these requirements, and replace <base64-token-secret> with it.
• The server identity is used for server-to-server communication. Both nacos.core.auth.server.identity.key and nacos.core.auth.server.identity.value must be custom, non-empty strings. The example key is native-test; set <test-server-identity> yourself or generate a random value with openssl rand -hex 16.

Use the same secret and server identity on all nodes in a cluster. Generate them independently for each deployment.

See the authentication guide for more configuration details.

4. Start, Verify, and Stop

4.1. Start Native

Run from the extracted Nacos directory:

NACOS_NATIVE_OPTS='-Xmx1g' bash bin/startup-native.sh
tail -f logs/startup.log

startup-native.sh runs the executable directly without JAVA_HOME. Complete the authentication settings in section 3.2 before starting. NACOS_NATIVE_OPTS accepts whitespace-separated Native VM flags. The script defaults to the deployment and function modes selected at build time.

Startup output is written to logs/startup.log under the installation directory, with other logs under logs/ as well.

4.2. Initialize the Administrator and Verify

After Native starts successfully, visit http://127.0.0.1:8080 and follow the prompt to initialize the administrator password on first use. Then follow the verification steps in the standard quick start to log in, obtain an accessToken, and verify configuration publishing and retrieval, and service registration and discovery. If the database already has an administrator account, log in with that account.

4.3. Stop Native

When only one Nacos test process is running on the host, use the distribution’s stop script:

bash bin/shutdown.sh

This script finds processes by the Nacos process marker. When multiple instances share a host, use your process manager to send SIGTERM to the intended instance so that other instances are not stopped.

5. Configuration Changes That Require Rebuilding

When changing configuration, use the following table to determine whether a rebuild is needed:

6. Use Embedded Derby

Derby inside a Native Server requires GraalVM’s experimental RuntimeClassLoading capability. Use a GraalVM distribution that supports this capability, add -Dnacos.native.derby.experimental=true to the build command in section 2.2, and set nacos.plugin.datasource-dialect.type=derby in both the build and runtime configuration.

This setup has been verified with macOS ARM64, GraalVM CE 25.4.4.1.1, and standalone merged deployment.

7. Build Your Own Docker Image

Nacos does not currently provide an official Native Docker image. Native plugin selection is determined at build time. Adding or upgrading plugins requires rebuilding the Native executable and the image.

Include the default plugins, custom plugins, JDBC drivers, and dependencies you need in the build above, then package the executable and companion files into a Docker image for your target platform.

Retain companion native libraries, configuration, and the AOT structural manifest. Use a base image with compatible system libraries and supply configuration and credentials at deployment time. startup-native.sh starts a background process; a container needs an entrypoint that keeps the application in the foreground and forwards termination signals correctly.

8. Troubleshooting

Appendix: Collect Missing Native Metadata

When the selected plugins or drivers need additional metadata, use the GraalVM tracing agent to run a JVM application temporarily and record reflection, JNI, and resource access required for Native compilation. Stop the JVM when collection finishes, then return to section 2.2 to build Native.

Complete the build environment, work directory, and plugin preparation in sections 1 and 2.1. From the source root, create a JVM package for tracing:

mvn -B '-Prelease-nacos,!dev' clean install -DskipTests
mkdir -p "$NACOS_NATIVE_WORK/jvm"
tar -xzf "distribution/target/nacos-server-${NACOS_VERSION}.tar.gz" -C "$NACOS_NATIVE_WORK/jvm"

Tracing requires a running Nacos instance. Follow sections 3.1 and 3.2 to prepare a separate test database and authentication credentials, and set them in $NACOS_NATIVE_WORK/jvm/nacos/conf/application.properties. Keep the database type, plugins, and feature switches consistent with the intended Native build. Then start tracing:

"$JAVA_HOME/bin/java" \
  "-agentlib:native-image-agent=config-output-dir=$NACOS_NATIVE_WORK/metadata" \
  -Dnacos.standalone=true -Dnacos.deployment.type=merged \
  "-Dnacos.home=$NACOS_NATIVE_WORK/jvm/nacos" \
  "-Dloader.path=$NACOS_NATIVE_WORK/jvm/nacos/plugins,$NACOS_NATIVE_WORK/plugins" \
  -jar "$NACOS_NATIVE_WORK/jvm/nacos/target/nacos-server.jar" \
  "--spring.config.additional-location=file:$NACOS_NATIVE_WORK/jvm/nacos/conf/" \
  "--logging.config=$NACOS_NATIVE_WORK/jvm/nacos/conf/nacos-logback.xml"

Once the test JVM starts, use another terminal to follow the verification steps in the standard quick start: initialize a test account and exercise login, configuration, and service operations. Use an SDK for the gRPC calls you need, and exercise any enabled AI or custom plugin features. These operations let the agent record the paths used by the application.

Stop the tracing process gracefully with Ctrl+C. Replace config-output-dir with config-merge-dir in the command, retain the test data, and restart to exercise reads and merge the additional paths. Stop the process again, review the generated metadata, then return to section 2.2.

See the GraalVM tracing agent documentation for tool usage, and bootstrap/README-AOT.md in the source tree for JVM AOT tracing instructions.