Directory structure
Root level
The root of a repository using the project-expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. looks like this.
<repository-root>
├── .nsproject/
│ ├── expansionSettings.xml
│ ├── harvest/
│ └── model/
│ ├── ...
│ └── projectSetup.xml
├── applications/
├── components/
├── conf/
├── docker/
├── expansions/
├── scripts/
│ ├── ...
│ └── rejuvenate_nsproject_setup.nss
├── .cleanExclude
├── .gitignore
├── CHANGELOG.md
├── Jenkinsfile
├── pom.xml
.
The .nsproject directory contains the expansionSettings.xml file as well as model files and harvest files. Files
expanded by the project setup always have an expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. comment at the top. The rejuvenate_nsproject_setup.nss script is
used to harvest and expand the project setup.
Some files are expanded at the root level.
- .cleanExpand
- Jenkinsfile
The .cleanExclude file is extremely important. It makes sure that non-expanded files are not cleaned/deleted when performing a clean expand.
ExpansionSettings
Each NS project setup requires an expansionSettings.xml. This file is located in .nsproject/expansionSettings.xml
and is the starting point of each expansion and it is different from the expansionSettings.xml file used by the
applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution..
It describes:
- Where to find the model files.
- Where to generate the expanded artifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project..
- Which expansion resourcesExpansion Resource (ExpansionResource). A reusable resource bundle containing expanders and features that provide specific application capabilities, defined in the expansion settings and added to the classpath during expansion. to use, depending on your software projects.
<expansionSettings>
<modelDirectory>..</modelDirectory>
<expansionDirectory>..</expansionDirectory>
<expansions>
<expansion>
<type component="project" name="ProjectSetup"/>
<path>.nsproject/model/projectSetup.xml</path>
</expansion>
</expansions>
<expansionResources>
<expansionResource name="net.democritus.project:jee-application-project-expanders" version="3.4.1"/>
<expansionResource name="net.democritus.project:jee-application-jenkins-ci-expanders" version="3.4.1"/>
</expansionResources>
</expansionSettings>
Since micro radiantMicro Radiant (MicroRadiant). The graphical modeling IDE and tooling environment used to design, edit, and maintain NS applications and project models. 4.5 it is possible to have multiple expansionSettings files within the same micro radiantMicro Radiant (MicroRadiant). The graphical modeling IDE and tooling environment used to design, edit, and maintain NS applications and project models. project. It is recommended to use at least this version when using the project-expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact..
docker
The docker directory contains files related to docker many of which are expanded by the project-expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact.. Each environment defined will expand a docker-compose file with the various services that are part of that environment.
ArtifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. created by the softwareProject (see Artifact) are required to have a directory within the
docker directory, named <artifact.name; format="kebabcase">.
Below is an example of the docker directory with two artifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. with the names backendImage and gatewayImage. Each folder of an artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. needs
a Dockerfile. Other files necessary for building the image should be put in the folder as well.
docker/
├── backend-image/
│ ├── ...
│ ├── Dockerfile
│ └── sql/
│ ├── BASE/
│ │ ├── V1.1__init_database.sql
│ │ └── V1.2__app_init_data.sql
│ └── MIGRATIONS/
│ ├── 1.1.0/
│ ├── 1.2.0/
│ └── NEXT/
│ └── V2.5__migration-name.sql
├── gateway-image/
│ ├── ...
│ └── Dockerfile
└── docker-compose.default.yaml
...
SQL Migrations Setup
In the example above, the backendImage artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. is of the jee-application-image type. Its sql directory follows a specific setup where in the BASE
directory are the sql files that represent the baseline of the database. The MIGRATIONS directory contains the sql migrations per release.
The NEXT directory contains the sql migrations for the next release.
This SQL Migrations Setup is optional and not required, although certain options depend on it:
project.artifact.moveSqlOnRelease and
project.softwareProject.replaceInitialDatabaseScriptsWithExpandedScripts.
scripts
scripts/
├── ...
├── expand.nss
├── harvest.nss
├── rejuvenate_nsproject_setup.nss
├── release.nss
├── set_version.nss
├── start_default_services.nss
└── stop_default_services.nss
These scripts are utility scripts. Depending on the model of your project setup you will have more or less scripts than depicted above. Custom scripts can be added next to the expanded scripts.
The project.gitFlow.disable option has an effect on the expanded scripts.
Custom scripts
It is perfectly valid to add custom scripts next to the expanded scripts.
It is a best practice to keep NSScript scripts self-contained (no file imports).