Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
The zheng project is a large-scale, modular, distributed system built using Java and Maven. This guide outlines the project's structure, build process, and deployment strategies for its various components, including web applications and standalone RPC services. The deployment model relies on Maven for building artifacts, managing environment-specific configurations through profiles, and packaging services for execution.
The system is composed of several high-level modules such as zheng-upms (User Permission Management System), zheng-cms (Content Management System), and zheng-common, each containing sub-modules for specific functionalities like RPC services, web interfaces, and data access layers. Deployment involves building these modules into their respective formats (WARs for web apps, JARs for services) and deploying them into appropriate runtime environments.
Project Structure
The project is organized as a multi-module Maven project. The root pom.xml defines the main modules that constitute the system.
This diagram illustrates the high-level modular architecture of the zheng project.
Sources: pom.xml:21-34, zheng-upms/pom.xml:25-32
Build & Configuration Management
The project uses Maven for building and managing dependencies. A key feature of the build process is the use of Maven profiles to handle environment-specific configurations.
Maven Profiles
Three standard profiles are defined across most modules: dev, test, and prod. The dev profile is active by default. These profiles determine which properties file is used to filter resources during the build, allowing for different database connections, server ports, and other settings for each environment.
| Profile ID | Environment | Properties File |
|---|---|---|
dev | Development | src/main/resources/profiles/dev.properties |
test | Testing | src/main/resources/profiles/test.properties |
prod | Production | src/main/resources/profiles/prod.properties |
| Sources: zheng-cms/zheng-cms-admin/pom.xml:41-60, zheng-upms/zheng-upms-server/pom.xml:47-66 |
The build process uses these profiles to filter resources, as shown in the configuration below.
<!-- Example from zheng-cms-admin/pom.xml -->
<build>
<finalName>zheng-cms-admin</finalName>
<filters>
<filter>src/main/resources/profiles/${env}.properties</filter>
</filters>
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
...
</build>
Sources: zheng-cms/zheng-cms-admin/pom.xml:63-73
Web Application Deployment
Many modules, such as zheng-cms-admin and zheng-upms-server, are web applications packaged as WAR files. For local development, these modules are configured with the jetty-maven-plugin.
Embedded Jetty Server
The Jetty plugin allows developers to run the web applications directly from the command line without needing to deploy to a separate servlet container. Each web application is configured to run on a specific port to avoid conflicts.
The following table lists some of the web modules and their default development server ports.
| Module | Final Name | Default Port |
|---|---|---|
zheng-upms-server | zheng-upms-server | 1111 |
zheng-cms-admin | zheng-cms-admin | 2222 |
zheng-cms-job | zheng-cms-job | 2223 |
zheng-cms-web | zheng-cms-web | 2224 |
zheng-api-server | zheng-api-server | 6666 |
zheng-oss-admin | zheng-oss-admin | 7772 |
zheng-message-server | zheng-message-server | 8881 |
zheng-demo-web | zheng-demo-web | 9999 |
Sources: zheng-upms/zheng-upms-server/pom.xml:85, zheng-cms/zheng-cms-admin/pom.xml:83, zheng-cms/zheng-cms-job/pom.xml:77, zheng-cms/zheng-cms-web/pom.xml:87, zheng-api/zheng-api-server/pom.xml:85, zheng-oss/zheng-oss-admin/pom.xml:85, zheng-message/zheng-message-server/pom.xml:91, zheng-demo/zheng-demo-web/pom.xml:85
For production, the generated WAR file (e.g., zheng-upms-server.war) would be deployed to a standard servlet container like Tomcat or a standalone Jetty instance.
RPC Service Deployment
The RPC services, such as zheng-upms-rpc-service, are packaged as executable JARs and distributed as a bundled archive using the maven-assembly-plugin. This creates a self-contained package that includes the service JAR, all its dependencies, configuration files, and startup scripts.
Assembly Packaging
The maven-assembly-plugin is configured in the service's pom.xml to trigger during the package phase.
<!-- from zheng-upms-rpc-service/pom.xml -->
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<descriptor>src/main/assembly/assembly.xml</descriptor>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
Sources: zheng-upms/zheng-upms-rpc-service/pom.xml:88-102
The assembly.xml descriptor file defines the structure of the final distribution package.
The diagram below shows the structure of the generated archive for an RPC service.
This diagram illustrates the contents of the assembly package created for RPC services.
Sources: zheng-upms/zheng-upms-rpc-service/src/main/assembly/assembly.xml:5-41
Assembly Contents:
id: The assembly process generates aziparchive.formats: The output format is azipfile.fileSets:- Copies startup scripts (
.sh,.bat) into thebindirectory. - Copies configuration files (
.properties,.xml) into theconfdirectory. - Sources: zheng-upms/zheng-upms-rpc-service/src/main/assembly/assembly.xml:13-29
- Copies startup scripts (
dependencySets:- Copies all project dependencies (JARs) into the
libdirectory. - Sources: zheng-upms/zheng-upms-rpc-service/src/main/assembly/assembly.xml:30-35
- Copies all project dependencies (JARs) into the
To deploy an RPC service, one would unzip the archive on the target server, modify the files in the conf directory as needed for the production environment, and use the start.sh or start.bat script to launch the service.
Core Technologies
The deployment environment must support the core technologies used by the zheng project. The zheng-common module defines many of these foundational dependencies.
| Technology | Dependency | Version | Purpose |
|---|---|---|---|
| Spring Framework | spring-context-support, spring-webmvc | 4.3.20.RELEASE | Core application framework |
| Spring Security | spring-security-web, spring-security-config | 4.2.8.RELEASE | Authentication and Authorization |
| MyBatis | mybatis, mybatis-spring | 3.4.2, 1.3.1 | Persistence framework |
| Dubbo | com.alibaba:dubbo | 2.5.6 | RPC framework |
| Zookeeper Client | com.github.sgroschupf:zkclient | 0.1 | Service discovery for Dubbo |
| Redis Client | redis.clients:jedis | 2.9.0 | Caching, Session management |
| Druid | com.alibaba:druid | 1.0.14 | Database connection pooling |
| ActiveMQ | org.apache.activemq:activemq-core | 5.7.0 | Message queue |
| Shiro | org.apache.shiro:shiro-spring | 1.3.2 | Security framework |
Sources: zheng-common/pom.xml:21-255
A successful deployment requires properly configured instances of external services like MySQL, Redis, Zookeeper, and ActiveMQ, with connection details specified in the configuration files of each deployed module.