How to Run and Customize Nacos from Source for Seamless Microservice Development

Official Standard Run Method

Download and extract runnable package

curl -O https://github.com/alibaba/nacos/releases/download/1.3.2/nacos-server-1.3.2.tar.gz
 tar -zxvf nacos-server-1.3.tar.gz
 cd nacos/bin

Execute Run

# Linux/Unix/macOS startup command (standalone means single‑node mode)
sh startup.sh -m standalone

# If using Ubuntu or encountering a "[[" symbol error, try:
bash startup.sh -m standalone

# Windows startup command (or double‑click startup.cmd)
cmd startup.cmd

Why Run from Source?

1. Convenience during development

If you migrate from Spring Cloud Netflix to Spring Cloud Alibaba, Nacos becomes a core dependency for service discovery and configuration management. Starting the microservice business requires checking whether the Nacos Server is up, and the traditional unzip‑install method is cumbersome. Running Nacos directly from source as part of the framework simplifies this process.

2. UI customization

With the unzip‑run method, modifying the UI is nearly impossible; you would need to download the source, adjust the UI, and rebuild.

git clone https://github.com/alibaba/nacos.git

cd nacos/

mvn -Prelease-nacos -Dmaven.test.skip=true clean install -U
ls -al distribution/target/
# change the $version to your actual path
cd distribution/target/nacos-server-$version/nacos/bin

Running from source allows you to tweak the UI and rebuild to see the effect immediately.

3. Keep Server & Client versions consistent

Microservice projects evolve quickly; each Nacos Client version may require a matching Server version, leading to high upgrade costs for users.

Nacos maintains good backward compatibility for minor versions, but major versions (e.g., 1.2 → 1.3) can introduce significant changes such as permission updates. Keeping versions aligned is recommended.

Running from source makes it easy to ensure version consistency.

Implementation Steps

1. Download Nacos source code

Only retain the nacos-console module; other modules can be removed.

2. Nacos source structure overview

├── pom.xml
└── src
    ├── main
    │   ├── java
    │   │   └── com
    │   │       └── alibaba
    │   │           └── nacos
    │   │               ├── Nacos.java   # main entry class
    │   │               └── console      # console related source
    │   └── resources
    │       ├── application.properties  # Nacos config file
    │       └── static                  # static page directory
    └── test                           # unit tests

3. Modify Nacos.java class

Add two parameters in the main method: whether to run in standalone mode and whether to disable permission checks.

@SpringBootApplication(scanBasePackages = "com.alibaba.nacos")
@ServletComponentScan
@EnableScheduling
public class Nacos {
    public static void main(String[] args) {
        // set standalone mode via environment variable
        System.setProperty(ConfigConstants.STANDALONE_MODE, "true");
        // disable authentication via environment variable
        System.setProperty(ConfigConstants.AUTH_ENABLED, "false");
        SpringApplication.run(Nacos.class, args);
    }
}

4. Update console/pom.xml

Since the Nacos BOM is not used, add explicit version numbers to all dependencies.

Some packages (nacos-config, nacos-naming) are not available in the central repository; change their groupId to com.pig4cloud.nacos to download them.

<dependency>
  <groupId>com.pig4cloud.nacos</groupId>
  <artifactId>nacos-config</artifactId>
  <version>1.3.2</version>
</dependency>
<dependency>
  <groupId>org.apache.tomcat.embed</groupId>
  <artifactId>tomcat-embed-jasper</artifactId>
  <version>7.0.59</version>
</dependency>
<dependency>
  <groupId>com.pig4cloud.nacos</groupId>
  <artifactId>nacos-naming</artifactId>
  <version>1.3.2</version>
</dependency>
...

Summary

After applying the above modifications, the source reference is: https://gitee.com/log4j/pig [1].

Whether to run Nacos from source depends on your specific scenario; choose the approach that best fits your project.

References

[1] https://gitee.com/log4j/pig: https://gitee.com/log4j/pig/blob/master/pig-register/pom.xml