Skip to main content

Project Setup Structure

In the getting started section, we have already taken a look at the root level of the project setup. In this section we take a deeper look at the project directory where the project-expanders actually expand the artifacts.

<repository-root>
├── ...
├── project/
│   └── environments/
│   └── <software-project>/
│   └── scripts/
│   └── services/
│   └── .cleanExclude
│   └── .gitignore
├── ...
.

It is important to note that both expanded and regular files are present in the project directory. This can make it confusing to know which files are expanded. As a general rule, expanded files are ignored by git, which is often indicated in an IDE. Furthermore expanded files should always have an expander comment at the top of the file.

  • .cleanExclude this file is extremely important. It makes sure that non-expanded files are not cleaned when performing a clean expand.
  • .gitignore this file will ignore the expanded files in git. (It is also a list of the expanded files, which can be useful)

Environments​

environments/
├── overrides/
│   └── compose-default.yaml
│   └── compose-test.yaml
├── compose-default.yaml
└── compose-test.yaml

In the above example of the environments directory has two environments default and test and for each an expanded general yaml file which combines all the services and the override file. And an override file which contains custom anchors to change environment variables and configuration.

SoftwareProject​

The actual directory of the softwareProject will take on the name of the softwareProject. In the example below the softwareProject has the name spaceApp and there is a local environment with the name default.

space-app/
├── ...
├── applications/
├── components/
├── conf/
├── docker/
├── expansions/
├── scripts/
│   └── build_space_app.nss
│   └── expand.nss
│   └── harvest.nss
│   └── start_default_services.nss
│   └── stop_default_services.nss
├── ...
├── Jenkinsfile
...

The file structure of this folder should feel familiar as it is the old structure. However there are a few changes:

  • The Jenkinsfile is expanded
  • The scripts are expanded (although it is possible to add custom scripts alongside them)
  • Depending on the artifact types used, some files in the docker directory are expanded

Artifacts​

Artifacts created by the softwareProject (this is explained in more detail later when describing the model) are required to have a directory within the docker directory. The name of the directory is based on the name of the artifact. Below is an example of the docker directory with two artifacts with the names backendImage and gatewayImage. Each folder of an artifact needs a Dockerfile. Other files necessary for building the image should be put in the folder as well.

space-app/
├── ...
├── 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
│       └── ...
...

SQL Migrations Setup​

In the example above, the backendImage artifact is of the jee-application-image type. It's 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.

Option
project.artifact.moveSqlOnRelease Artifact

Move the sql files of this artifact on release.

Using the example above, when creating a 1.3.0 release, the V2.5__migration-name.sql file will be moved from the NEXT directory to a new 1.3.0 directory.

Prerequisite

This option requires the SQL Migration Setup to be used.

<options>
  <project.artifact.moveSqlOnRelease/>
</options>

Scripts​

scripts/
├── release.nss
└── set_version.nss

These scripts are utility scripts for updating the version of the project and create a release using Git Flow.

Option
project.gitFlow.disable Project

Indicate that the project does not follow the Git Flow development flow. Has an effect on the expanded scripts and Jenkinsfile.

Warning

Using Git Flow is highly recommended. Only use this option if absolutely necessary, otherwise follow the best practices of Git Flow.

<options>
  <project.gitFlow.disable/>
</options>

Services​

services/
├── compose-backend.yaml
├── compose-database.yaml
├── compose-frontend.yaml
├── compose-gateway.yaml
└── compose-keycloak.yaml

The services directory has a yaml file for each service. Each yaml file contains a basic configuration of the service. More finegrained control of ports and environment variables should be configured in the environment override files. These files are used by the expanded environment files. Having a service of type custom expands custom anchors in that service.