Skip to main content

Project Setup Migration

Before starting the migration

It is highly recommended to read the project setup documentation first before starting the migration.

Introduction​

This migration guide is for projects that have been created in the past and do not use the project-expanders yet. New projects should use the NS initializer.

Preparation​

  • Harvest your applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution.
  • Start from a clean working directory
  • Create a new branch to perform the migration
  • Make sure NSScript is installed and up to date
caution

Before you start, make sure that any compose file used on Jenkins does NOT contain ANY volume mounts that are bind mounts. Mounting a directory that does not exist will cause Docker to create it - breaking Jenkins. If you absolutely need to add bind mounts to your Jenkins compose file, they must contain the create_host_path: false and read_only: true options.

Step 1: Add the basic setup​

Create the following directories and files in your project:

<repository-root>
├── .nsproject/
│   ├── expansionSettings.xml
│   └── model/
│       └── projectSetup.xml
├── scripts/
│   └──rejuvenate_nsproject_setup.nss
...

File contents​

<project xmlns="https://schemas.normalizedsystems.org/xsd/project/2/1/0">
  <name>projectSetup</name>
  <!--  Replace the projectVersion -->
  <version>projectVersion</version>
</project>

Step 2: Updating files​

Update the following files. Do not blindly copy the contents of these files, merge them with the already existing files.

# IntelliJ
.idea
*.iml

# VSCode
.vscode*
.devcontainer

# Eclipse
.project
.settings
.classpath

# Expanders
/expansions*

# Maven
target
pom.xml.versionsBackup

# NS Initializer
.credentials

# Project Setup
.nsproject/harvest

Step 3: Creating the project setup model​

Micro Radiant version

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 with 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..

  1. Install the org-normalizedsystems-northstar-project-plugin plugin if you haven't already.
  2. Import a new project in the micro radiantMicro Radiant (MicroRadiant). The graphical modeling IDE and tooling environment used to design, edit, and maintain NS applications and project models.
  3. Select the root directory of your project. You should see two expansionSettings files found (.nsproject and conf/expansionSettings).
  4. Give the project a fitting name.
  5. Switch between expansionSettings files using the project facet in the left column.
  6. You can now start editing the model.

More info about importing projects in micro radiantMicro Radiant (MicroRadiant). The graphical modeling IDE and tooling environment used to design, edit, and maintain NS applications and project models. can be found here.

Artifacts​

caution

Neither the artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. name nor the technicalName should contain any /! If there is a group for the docker images they should be added as the group fieldFieldA property of a DataElement expanded to a database column and user interface input element..

Below we will use the nsapp/software-project-name(kebab-case) group as an example.

  • backendImage
    • technicalName: backend
    • group: nsapp/software-project-name(kebab-case)
    • type: jee-application-image
  • databaseImage
    • technicalName: postgres
    • version: 17.2 (use your current postgres version)
    • type: custom

When using Angular, you'll likely need a frontend and gateway image too.

  • frontendImage
    • technicalName: frontend
    • group: nsapp/software-project-name(kebab-case)
    • type: angular-frontend-image
  • gatewayImage
    • technicalName: gateway
    • group: nsapp/software-project-name(kebab-case)
    • type: gateway-image

Environments​

  • default
    • options:
      • project.environment.isLocal

SoftwareProjects​

  • softwareProjectName
    • type: jee-applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution.
    • artifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project.:
      • projectSetup::backend-image
      • projectSetup::frontend-image @angular
      • projectSetup::gateway-image @angular
    • pipelines
      • build-pipeline
        • stages
          • validate
            • type: validate
          • expand
            • type: expand
          • build
            • type: build
          • report
            • type: report
          • deploy
            • type: deploy
          • analyze
            • type: analyze
          • release-stable
            • type: release-stable
        • (possible) options:
          • project.pipeline.slackChannel: team-jenkins-slack-channel
          • project.pipeline.changelogSlackChannel: team-release-slack-channel
          • project.pipeline.onlyReportChanges
          • project.pipeline.noReleasePromotion
          • project.pipeline.relaxBranchVersionCheck
    • options:
      • project.softwareProject.frontend: angular-app-name @angular

Services​

  • backend
    • artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project.: project::backendImage
    • environments
      • projectSetup::default
    • type: jee-application
    • softwareProject: projectSetup::softwareProject
  • database
    • artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project.: projectSetup::databaseImage
    • environments
      • projectSetup::default
    • type: database

When using Angular, you'll likely need a frontend and gateway service too.

  • frontend
    • artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project.: projectSetup::frontendImage
    • environments
      • projectSetup::default
    • type: angular-frontend
    • softwareProject: projectSetup::softwareProject
  • gateway
    • artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project.: projectSetup::gatewayImage
    • environments
      • projectSetup::default
    • type: gateway
    • softwareProject: projectSetup::softwareProject

Step 4: Prepare for expansion​

Each artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. defined in your softwareProject expects a directory within the docker directory named <artifact.name; format="kebabcase">.

E.g. an artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. backendImage that is also defined in your softwareProject expect a directory docker/backend-image to exist.

If these directories do not exist create them now. Also move config and build files related to each artifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. to their respective directory (e.g. Dockerfile, tomee.xml, ...).

Step 5: Expand​

In the micro radiantMicro Radiant (MicroRadiant). The graphical modeling IDE and tooling environment used to design, edit, and maintain NS applications and project models., go to build => script and run the scripts/rejuvenate_nsproject_setup.nss script. It is also possible to execute this script using a cli.

Step 6: Configure model and custom code​

At this point you have an expanded setup, but some config is still needed. This step is the most involved. Since each project is different it is not possible to make a one size fits all guide here.

This is also the point to finetune the model to the needs of your project. Change names and add options where needed.

  1. Configure the necessary environment variables and ports in the docker compose files in the docker directory.
  2. Verify, and adapt if necessary, the artifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. in the docker directory.
  3. Verify, and adapt if necessary, the Jenkinsfile.

Step 7 is likely to trigger issues if you've looked over them. You can iterate step 6 and step 7 until all issues are resolved.

Commit your changes to git.

Step 7: Build and deploy the project​

  1. Build your applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. using micro radiantMicro Radiant (MicroRadiant). The graphical modeling IDE and tooling environment used to design, edit, and maintain NS applications and project models. or the NSScripts that have been expanded for your project setup.
  2. Run start_default_services.nss. The local docker containers should be started and you should have an environment deployed on your machine!
  3. To stop deployment, run stop_default_services.nss

Step 8: Cleanup​

Now that you've confirmed everything still works. You can delete files that are not used anymore that are still present. (e.g. docker-compose files that have been replaced by expanded docker-compose files)