Skip to main content

New Project

Header

Level: Intermediate

Keywords: new SAMO project

The result: initial metadata needed for new project set up

How to set up new SAMO Project?​

This page describes the steps needed to set up a new SAMO project, meaning its structure on GitLab (optional), configuration of project environments and initialization metadata. The part concerning installation of Application and DB Server and Deployment of project software components is described in the Installation section on the SAMO SharePoint portal. The results after finishing this guide are:

  1. created collaboration environment for implementation works
  2. established continuous delivery of changes to different project environments
  3. on server running SAMO application with empty Cockpit

GitLab set up (optional)​

GitLab is managed by SAMO support, who takes care of creating structure for new projects, setting up the delivery process using GitLab Continuous Integration, creating new user groups and assigning access rights.

Internal GitLab​

Each customer should have its own space in GitLab where we should manage all of its projects. There should be someone (Maintainer) who will take care about the customer and this person should also add memberships to others.

GitLab group: https://gitlab/samo/customers/CUSTOMER

Developer can ask customer's Maintainer for membership. Maintainer should receive membership in the same time when the group is created.

In newly created group we should create project for the customer

If necessary create metadata-packages archive folder and projects in the archive folder for metadatas of the project.

If developer team wants to keep tracks on changes create changelog.md file and doc folder

Continuous integration​

For building of docker images we use CI in GitLab. Each project should have its own dev server with GitLab runners installed. More information about installation of Gitlab runners can be found in Lighthouse, for Windows and Linux.

The CI in GitLab project and share runners must be enabled.

  • Settings -> General -> Permissions -> Pipelines
  • Settings -> CI/CD -> Runners -> Enable shared runners

Create customer group in external GitLab​

External GitLab (https://git.asseco-ce.com) is used as Docker registry for our delivery for Docker images. Therefore, each project that creates Docker image has to have the same repository also in the external GitLab - this has to be manually created and maintained.

The delivery of docker images at customer's side id done through Docker and login to our <docker.asseco-ce.com> registry. For these purposes new customer specific credentials must be created.

This require multiple steps for customer's Maintainer to do:

  • ask HelpDesk for email group in this form samo-CUSTOMER-git@asseco-ce.com
  • ask GitLab administrators to create external user for the email group
  • create groups and projects that should have Docker registry
  • assign the newly created user for all projects that should be accessible

Repository structure​

In order to understand how to manage all your project metadata, at first you need to understand the folder structure of corresponding repositories. If you work on conventional project (project consisting of only one repository), you have all your content in one repository. However, more often you will have a packaged project, and then you use two kinds od repositories for your project:

  1. ONE project repository with configuration of your project environments, docker, continuous integration and others
  2. MANY package repositories containing metadata configurations for the content and functionality of your application

Project repository structure​

Project repository structure is generally very variable and depends on which software components are being used in your project. It is usually set up together with the server installation.

Next, the common project repository structure will be described.

project-repository (e.g. samo-demo-project)
│
└───environments
│   │
│   └───dev                       //environment files for developers project environment
│   │   │
│   │   └───.env                  //variables for docker compose
│   │   └───dev.env               //variables for software components
│   │   └───docker-compose.yml    //Docker setup, delivery
│   │   └───environment.properties    //gateway environment specific properties
│   │   └───local.env             //environment variables for local project setup
│   │   └───remote.env            //environment variables for remote project setup
│   │   └───local.properties      //gateway local environment properties
│   │   └───localtron.json        //presets for <a href = "/howToStart/prerequisites/tools/#localtron">Localtron</a>
│   │   └───package-lock.json     //project (dev env) specific versions of packages for installation
│   │   └───packages.json         //project (dev env) dependencies to packages containing metadata configurations
│   │
│   └───test                      //environment files for test project environment
│   └───distrib                   //environment files for distrib project environment
└───artefacts                     //used to store migration and update SQL scripts
└───doc                           //contains files needed to integrate project to Lighthouse
│
└───.gitlab-ci.yml                //contains definition of the Gitlab CI configuration
└───changelog.md                  //file for storing latest updates on project

Package repository structure​

Package repository structure on the highest level consists of package.json, dynamic-app, gateway, lids-business-service and lids-as folders. The package.json file contains dependencies to other packages.

package.json - configuration example

    {
        "name": "samo-init-demo",
        "version": "1.0.0",
        "dependencies": {
            "samo-base": "git+ssh://git@gitlab:20022/samo/metadata/packages/base/samo-base.git#master",
            "lids-base": "git+ssh://git@gitlab:20022/samo/metadata/packages/base/lids-base.git#master"
        }
    }

With the new packageing approach, there is a possibility to include multiple packages in one gitlab repository. Also the configuration of dependencies in package.json is different.

package.json new packaging - configuration example
    {
        "name": "@samo-demo/samo-demo",
        "version": "7.7.0",
        "configurationPackage" : true,
        "dependencies": {
            "@samo/samo-base": "~8.3.0",
            "@samo-demo/lids-demo": "~7.7.0"
        }
    }

Structure of remaining folders is described in Lighthouse separately for each software component (Gateway, Dynamic-App, Lids-business-service).

Initialization metadata​

In order to get the application up and running (with empty cockpit), some basic initialization metadata are needed. To make their preparation easier, you can downlaod prepared samo-init-demo package from Gitlab.

First, you need to copy the content either to the metadata folder of your conventional project or to some base package repository which is being used by your project.

Second, you need to edit certain parts in these sample metadata. Basically you can search for init keyword (which represents our project/application name) and change it according to your application and project name.

  1. Rename the samo-init-demo folder according to your project package name.
  2. Change the name and version of the package in package.json (or completely remove this file for conventional projects). Also check, if you want to use the packages, which are referenced in dependencies.
  3. Rename ..gateway/applications/init.json file based on your own application name. In this file change clients name and application name in defaultDataSource and defaultAuthorization.requiredRole.
  4. Rename ..gateway/clients/init-dynamic-client.json file base on your own client name. In this file change init application part in configurationParts based on your own application name. Notice that the version of Dynamic-App components is defined using environment property. You will find it in your project repository file environment.properties.
  5. Rename ..lids-business-service/tenants/asseco-ce.json file names with your own tennant name.
  6. Change application name in your tennant configuration (..gateway/tenants/asseco-ce.json).
  7. Rename ..\dynamic-app\init folder based on your own application name.
  8. Change your client name (which you have defined in step 4.) also in ..\dynamic-app\init\components\index.html.
  9. Change your application name in ..\dynamic-app\init\components\manifest.json in name and short_name.
  10. Replace the base ..lids-as/project/lids-as/model/model.xm with your own LIDS model.

Third, you need to commit and push these changes to Gitlab and usually start the Pipeline, which will upload the content to the project server.

Publish project packages​

The project-install command which starts the local implementation environment uses published packages from packages-repository. Therefore after setting up new packaged project, you also need to publish first versions of your project packages either manually and set up Gitlab pipeline. For more informations, see Using packages in project.