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 application
  • 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 radiant 4.5 it is possible to have multiple expansionSettings files with the same micro radiant project. It is recommended to use at least this version when using the project-expanders.

  1. Install the org-normalizedsystems-northstar-project-plugin plugin if you haven't already.
  2. Import a new project in the micro radiant
  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 radiant can be found here.

Artifacts​

caution

Neither the artifact name nor the technicalName should contain any /! If there is a group for the docker images they should be added as the group field.

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-application
    • artifacts:
      • 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
    • artifact: project::backendImage
    • environments
      • projectSetup::default
    • type: jee-application
    • softwareProject: projectSetup::softwareProject
  • database
    • artifact: projectSetup::databaseImage
    • environments
      • projectSetup::default
    • type: database

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

  • frontend
    • artifact: projectSetup::frontendImage
    • environments
      • projectSetup::default
    • type: angular-frontend
    • softwareProject: projectSetup::softwareProject
  • gateway
    • artifact: projectSetup::gatewayImage
    • environments
      • projectSetup::default
    • type: gateway
    • softwareProject: projectSetup::softwareProject

Step 4: Prepare for expansion​

Each artifact defined in your softwareProject expects a directory within the docker directory named <artifact.name; format="kebabcase">.

E.g. an artifact 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 artifact to their respective directory (e.g. Dockerfile, tomee.xml, ...).

Step 5: Expand​

In the micro radiant, 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 artifacts 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 application using micro radiant 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)