Try Valence
21
Oct
2024

Set up Git for your NAB development environment

0

In the ever-evolving landscape of application development, efficient version control and seamless integration are paramount for maintaining robust and scalable solutions. We’re excited to introduce the latest enhancement to Valence’s Nitro App Builder (NAB): Git Integration. This powerful feature allows you to synchronize, commit, track history, and rollback changes effortlessly using Git, directly within your IBM i environment. In this blog post, we’ll guide you through setting up and leveraging this integration to optimize your NAB development workflow.

Overview

Valence has introduced a dedicated node folder in the root directory of its instance on the IBM i Integrated File System (IFS). This folder hosts a new Node.js server responsible for managing Git operations related to Nitro App Builder. With this integration, you can:

  • Sync: Automatically synchronize your Git repository with NAB data sources, widgets, and apps.
  • Commit: Push changes from NAB to your Git repository directly through the NAB interface or the NAB Checkout Manager application.
  • History: Retrieve the change history for data sources, widgets, or apps within NAB.
  • Rollback: Revert to previous versions of data sources, widgets, or apps from Git and update your Valence instance accordingly.

Prerequisites

Before diving into the setup, ensure you have the following:

  1. IBM i Environment: Access to an IBM i system where Valence is installed.
  2. Node.js Installed: The latest stable version of Node.js is installed on your IBM i.
  3. Git Installed: Git is installed on your IBM i system. Note: No additional configuration is required as Git operations will be handled remotely via NAB. This integration is available exclusively for Git and GitLab repositories.
  4. Git Repository: A dedicated Git or GitLab repository for your NAB items.

Step 1: Install Node.js and Git on IBM i

To ensure that your IBM i environment is ready for Git integration with Nitro App Builder, you need to install Node.js and Git. Follow the steps below to set up these essential tools.

1.1 Install Node.js

First, verify if Node.js is already installed on your IBM i system:

node -v

If Node.js is not installed:

  1. Install Node.js: Refer to the IBM i OSS Docs for instructions on installing Node.js on IBM i.

1.2 Install Git

Git is essential for version control. Follow these steps to install Git on IBM i:

  1. Access IBM i PASE Environment: Enter the PASE environment:
   CALL QP2TERM
  1. Check if Git is Installed:
   git --version

If Git is not installed, proceed with the installation.

  1. Install via Yum (Recommended): IBM i supports the Yum package manager, which simplifies software installations.
  • Install Yum (if not already installed): If Yum is not installed, you can install it using the IBM official instructions.
  • Update Yum Repositories: sudo yum update
  • Install Git: sudo yum install git
  • Verify Installation:
   git --version

You should see the installed Git version.

Step 2: Set Up the Node Server for Git Integration

With Node.js and Git installed, you can now set up the Node server responsible for managing Git operations related to Nitro App Builder.

2.1 Navigate to the Node Server Directory

Access the node directory within your Valence instance’s IFS directory using IBM i PASE:

cd /path/to/valenceInstance/node

Replace /path/to/valenceInstance/node with the actual path to your Valence instance’s node directory.

2.2 Install Required Node Packages

Ensure all necessary Node.js packages are installed by running:

npm install

This command reads the package.json file and installs all listed dependencies.

2.3 Start the Node Server

You can start the Node.js server to manage Git operations. While using a process manager like PM2 is recommended for production environments to ensure the server runs continuously, it is optional and not required for NAB Git integration.

Optional: Install PM2 (Process Manager for Node.js Applications)

If you choose to use PM2, install it globally using npm:

npm install -g pm2

Verify the installation:

pm2 -v

Start the Node Server with PM2:

pm2 start app.js --name "valence-node" -i max
  • --name "valence-node" assigns a recognizable name to the process.
  • -i max allows PM2 to run as many instances as there are CPU cores, optimizing performance.

Verify the PM2 Process:

pm2 status

You should see valence-node listed and running.

If you choose not to use PM2, you can start the Node server directly:

node app.js

Step 3: Create a Dedicated Git Repository

For effective version control, create a new Git repository dedicated to storing your Nitro App Builder items, including data sources, widgets, and apps. This ensures that all NAB-related changes are isolated and manageable.

3.1 Creating a Repository on GitHub

  1. Log In: Sign in to your GitHub account.
  2. New Repository: Click the “+” icon in the top-right corner and select “New repository”.
  3. Repository Details:
    • Name: e.g., valence-nab-repo.
    • Description: (Optional) Provide a brief description.
    • Visibility: Choose between Public or Private based on your preference.
  4. Initialize Repository: You can initialize with a README, .gitignore, or license if desired.
  5. Create: Click “Create repository”.

Note: If you’re using GitLab or another supported platform, the steps are similar.

Step 4: Configure Git User Credentials in NAB Checkout Manager App

To enable seamless interactions between NAB and your Git repository, each developer must configure their Git user credentials within the NAB Checkout Manager application.

4.1 Access the Git Configuration Section in NAB Checkout Manager App

  1. Open NAB Checkout Manager App:
  • Open the “NAB Checkout Manager” application within your Valence instance and click on the Git section.

4.2 Add or Edit Git User Information

  1. Add New Git User:
    • Click on the Add Git User button.
    • Username: Enter your Git username.
    • Email: Enter your Git email address.
    • Token: Enter your personal access token (explained below).
    • Click Save to store the credentials securely.
  2. Edit Existing Git User:
    • Select the user from the list.
    • Modify the necessary fields (Username, Email, or Token).
    • Click Save to apply changes.
  3. Delete Git User:
    • If a Git user is no longer needed, select the user and click Delete to remove their credentials from the system.

4.31 Creating a Personal Access Token (example using GitLab)

  1. Navigate to Settings:
    • Click on your profile picture in GitLab and select “Preferences”.
  2. Access Tokens:
    • In the sidebar, click on “Access Tokens”.
  3. Add New Token:
    • Click “Add new token” button.
    • Note: Provide a descriptive name, e.g., “NAB Integration Token”.
  4. Set expiration date:
    • Set an expiration date, or leave blank if desired
  5. Select Scopes:
    • “api” must be checked.
  6. Generate and Copy Token:
    • Click “Create personal access token”.
    • Important: Copy the token immediately as it won’t be shown again.

4.32 Creating a Personal Access Token (example using GitHub)

  1. Navigate to Settings:
    • Click on your profile picture in GitHub and select “Settings”.
  2. Developer Settings:
    • In the sidebar, click on “Developer settings”.
  3. Personal Access Token:
    • Select “Personal access tokens” and then “Tokens (classic)”.
  4. Generate New Token:
    • Click “Generate new token” button.
    • Note: Provide a descriptive name, e.g., “NAB Integration Token”.
    • Set an expiration date, or set to “no expiration” if desired
  5. Select Scopes:
    • For full repository access, select “repo”.
  6. Generate and Copy Token:
    • Scroll to the bottom and Click “Generate token”.
    • Important: Copy the token immediately as it won’t be shown again.

Store your token securely, as it grants access to your repositories.

Step 5: Configure Git Repository in Valence Portal Admin Settings

Link your Git repository with your Valence instance to enable synchronization and version control.

  1. Log In to Valence Portal:
    • Ensure you have administrative privileges.
  2. Navigate to Admin Settings:
    • Find and select the “Settings” option in the Valence Portal.
  3. Access Nitro App Builder Section:
    • Within Settings, locate the “Nitro App Builder” section.
  4. Enable Features:
    • Check-Out/Check-In: Enable by checking the corresponding box.
    • Git Integration: Enable by checking the Git checkbox.
  5. Provide Git Repository URL:
    • In the field labeled “Git Repository URL”, enter the HTTP(S) URL of your Git repository. Example: https://github.com/xxxx/valence-nab-repo.git
  6. Save Settings
    • Click “Save” to apply the configurations.

Automatic Sync:

  • Once Git Integration is enabled and the repository URL is provided, the system will automatically perform a synchronization between your Valence instance and the specified Git repository. This ensures that your NAB data sources, widgets, and apps are up-to-date with the repository without any manual intervention.

Step 6: Utilizing Git Features in Nitro App Builder

With the integration set up, you can now leverage Git functionalities directly within Nitro App Builder to enhance your development workflow. All Git operations such as commit, history, and rollback are managed through the NAB interface, eliminating the need for manual Git commands.

6.1 Sync

Purpose: Automatically ensures that your Git repository is up-to-date with the latest NAB data sources, widgets, and apps.

How It Works:

  • After enabling Git Integration in the Valence Portal Admin Settings, synchronization occurs automatically. This keeps your Git repository in sync with your NAB environment without any manual intervention.

6.2 Commit

Purpose: Pushes changes made in NAB to your Git repository. This includes new widgets, updated data sources, or modified apps.

How to Use:

Commit Within NAB Application

  1. Make Changes in NAB:
    • Develop or modify data sources, widgets, or apps within Nitro App Builder.
  2. Request to Save the Item:
    • After making your changes, request to save the data source, widget, or app.
  3. Hit the Commit Button:
    • Once the item is saved, click the Commit button within the NAB interface.
  4. Enter Commit Message:
    • You will be prompted to enter a commit message summarizing your changes.
    • Provide a clear and descriptive commit message that reflects the modifications made.
  5. Confirm Commit:
    • After entering the commit message, confirm the commit action.
    • Your changes will be pushed to the Git repository seamlessly. This is the most common method used by developers during their regular workflow.

Commit via NAB Checkout Manager Application

  1. Use Case: Ideal when a developer is out of the office or unable to access the main NAB application.
  2. Open NAB Checkout Manager Application:
    • Launch the NAB Checkout Manager application within your Valence instance.
  3. Select Items to Commit:
    • Choose the data sources, widgets, or apps you wish to commit from the list.
  4. Enter Commit Message:
    • Provide a descriptive commit message summarizing the changes.
  5. Hit the Commit Button:
    • Click the Commit button to push changes to the Git repository.

No Git commands are required as the process is handled entirely within the NAB interfaces.

6.3 History

Purpose: Retrieves the change history for specific data sources, widgets, or apps. This is invaluable for tracking modifications and understanding project evolution.

How to Use:

  1. Select Item:
    • Choose the data source, widget, or app you want to review within Nitro App Builder.
  2. View History:
    • Click on the History option associated with the selected item.
  3. Review Changes:
    • A log of all changes, including commit messages and timestamps, will be displayed for your review.

6.4 Rollback

Purpose: Reverts to a previous version of a data source, widget, or app from Git and updates your Valence instance accordingly.

How to Use:

  1. Navigate to the Item:
    • Select the data source, widget, or app you wish to rollback within Nitro App Builder.
  2. Access History:
    • Click on the History option associated with the selected item to view its commit history.
  3. Select Commit for Rollback:
    • Browse through the list of commits and select the specific commit you want to revert to. The system will display the diff for that commit, highlighting the changes made.
  4. Initiate Rollback:
    • After reviewing the diff, click the Rollback button associated with the selected commit.
  5. Confirm Rollback:
    • Confirm the rollback action to revert the item to the selected version.

Note: Always ensure that you have reviewed the changes and understand the implications before performing a rollback to prevent unintended disruptions.

The rollback process is streamlined within NAB, allowing you to effortlessly revert changes without the need to manually execute Git commands.

Conclusion

The new Git integration in Valence’s Nitro App Builder is a transformative addition for developers working within the IBM i environment. By providing robust version control and seamless synchronization, it enhances collaboration, ensures code integrity, and streamlines the development process.

By following the steps outlined in this guide, you can set up the integration swiftly and begin leveraging its full potential to manage your data sources, widgets, and apps efficiently. Embrace this powerful tool to ensure your projects are well-organized, traceable, and maintainable.

Need Assistance?
If you encounter any challenges or have questions about the setup process, feel free to reach out to our support team or consult the detailed Nitro App Builder documentation.