4.8.2. Jenkins installation procedure

<< Click to Display Table of Contents >>

Navigation:  4. How to use Anatella? > 4.8. Scheduling Anatella Graphs >

4.8.2. Jenkins installation procedure

 

 

ANATEL~1_img8

One pre-requisite to be able to run an Anatella graph inside Jenkins is to register your Anatella/TIMi licences as a “System-Wide” License: More precisely: You must follow the procedure given in section “7.4.4: Enter a Server-Wide Licence”.

 

 

Here, we’ll give instructions for the installation of Jenkins under Windows. The installation process under Linux is similar. A simplified Jenkins installation procedure is also documented using a youtube tutorial video available here: https://www.youtube.com/watch?v=MtuUpn2GskI

 

 

Follow these steps:

 
 

1.Inside Anatella, open the “Automation” drop-down menu and select “Configure Jenkins”:

 

clip1229

 
 

2.Inside the Jenkins configuration screen, click on the blue URL link:

 

clip1230

 
 

3.Your browser should now display the URL: http://download.timi.eu/Jenkins/

 
Download the 3 files: “jenkins.xml”, “jenkins_xxx.msi” and “jre_xxx.exe”:

 

clip1231

 

These files are placed there for your convenience.
 

You can also download them from their original location: These are:
 

For the Jenkins installer (“Jenkins_xxx.msi”): https://www.jenkins.io/download/
 

For the Java Virtual Machine (“jre_xxx.exe”):
…either from here: https://www.oracle.com/java/technologies/downloads/

…or from here: https://adoptium.net/temurin/releases/

 
 

4.Install the “Java Virtual Machine”: Run the file “jre_xxx.exe”. Click the “Install” button and wait until completion of the install process. For exemple, you should see:

 

clip1232

 
 

5.Run the file “jenkins_xxx.msi”, click the “Next” button and select the Jenkins installation directory. I usually choose: “C:\soft\Jenkins\” like that: number1

 

clip1233

 

 ..and click “Next”. number2

 
 

6.On the next configuration screen, select the radio button “Run the service as LocalSystem (not recommended)number1 and click the “Next” buttonnumber2:

 

clip1234

 
 

More Details: We really need to execute the Jenkins service “as a local or domain user” otherwise we’ll run into many troubles (see section 4.8.3.2. for a list of all the bad things that can happen when running the Jenkins service as the “LocalSystem” account). …But, unfortunately, the Jenkins installer has a bug that prevents us to select the better option (i.e. we cannot select “Run service as local or domain user”), so we select instead here the worse option (i.e. we selected “Run service as LocalSystem (not recommended)”) and we’ll perform a few extra operations (during step 11 of this installation procedure) to ensure that the Jenkins Service is still running “as local or domain user”.
 

 

7.Click on the “Test Port” button number1, click on the “Next” button: number2

 

clip1235

 

Select the “Java Virtual Machine” that will be used to run Jenkins. By default, it’s:
 

C:\Program Files\Java\jre1.8.0_291\
 

…And click the “Next” Button:
 

  clip1236

 

You might get a warning message about installing “Java 11” instead of “Java 8”. Disregard this warning.

 

 

8.Click the “Next” button:

 

clip1237

 
 

9.Click the “Install” button:

 

clip1238

 

 

10.After a few minutes, you should see:

 

clip1239

 
 
If you get a message about “impossible to start service”, you need to open the “service manager” ([Win]+[R] and run “services.msc”) and manually start the “Jenkins” service:
 

 

Open the “Service” Manager: Press simultaneously the keys [WIN]+[R] on your keyboard to open the “Run” window. Then write “services.msc” number1 and click the “OK” buttonnumber2:
 

clip1240

 
 

Inside the “Service” Manager window: select the “Jenkins” service number1 and click the restart buttonnumber2:

 

clip1241

 

 

If Jenkins still does not start, please refer to the section 4.8.3.3. to know how to diagnostic & fix the error.
 

 

11.We really need to execute the Jenkins service “as a local or domain user” otherwise we’ll run into many troubles. Unfortunately, up to this point, the Jenkins service is running “as the LocalSystem account”. Let’s correct that!

 

 

11.1.Navigate  to the Jenkins installation directory (usually “c:\soft\jenkins”). By default, you don’t have the rights to see the content of the “jenkins” directory. To get these rights, the easiest way is to double-click the “Jenkins” directory inside the MS-File-Explorer windows:

 

clip1242

 

Then you see:

 
clip1243

 

 

Just click on the “Continue” button:          
 

You should now see:

 

clip1244

 

This step is important because your user MUST have the write access rights to the Jenkins directory (otherwise the Jenkins service won’t start because it needs to be able to write LOG files inside this directory). If you installed Jenkins inside “c:\program files”, you need to change the user access rights of the “c:\program files\jenkins” directory  to allow your user to write inside  this directory.

 

 

11.2.Replace the file “Jenkins.xml” inside the Jenkins installation directory with the one downloaded from: http://download.timi.eu/Jenkins/ . You should already have downloaded this file (during the step 3 of this installation procedure). If you don’t have it yet, right-click the “jenkins.xml” link number1 and select “Save link as…” number2 :

 

clip1245

 

 

ANATEL~1_img8

The difference between this new “Jenkins.xml” and the original “Jenkins.xml” is: We just replaced all occurrences of “%ProgramData%” with “%LocalAppData%” everywhere in the file (i.e. these three lines changed).

clip1247b
 

 

 
 

11.3.Optional: By default, Jenkins runs    on port 8080. If you changed the value of the default port (during the step 8 of this procedure), you need to edit the “Jenkins.xml” (with “notepad”) and write the new port value here:

 

clip1247

 
 

11.4.Open the “Service” Manager: Press simultaneously the keys [WIN]+[R] on your keyboard to open the “Run” window. Then write “services.msc” number1 and click the “OK” button number2:
 

clip1248

 

 

11.5.Inside the “Service” Manager window: We setup the Jenkins service to run under your local user:
 

clip1249

 
 

11.6.Let’s select your Local Windows account:

 

clip1250
 

clip1269
 

clip1251

 
 

11.7.Enter your windows password (2 times) and press the “Ok” button:

 

clip1252

 

 

11.8.You should see:  

 

clip1253

 

 

11.9.Restart the Jenkins service:

 

clip1254

 

 

12.Open a browser and navigate to http://localhost:8080 (this is the default jenkins URL). You should see:
 

clip1255

 
 
Open with “notepad” the file located here: number1  ..and copy the content of this file here number2:

 

clip1255

 
Click the “Continue” button number3.

 
 

13.Click the “Install suggested plugins” button (you’ll still be able to install more plugins later):

 

clip1256

 

 

14.Please wait until the default Jenkins plugins are downloaded&installed. This might take some time, depending on your internet connection speed. Do not worry if some plugins do not install directly because:
 

you don’t need any of these optional plugins to use Jenkins with Anatella.

you can always install any of them later.

 

 

clip1257

 
 

15.Create you first administrative user. You need to remember the login/password that you used here, on this step, because you’ll need to enter it again later inside Anatella during step 18. Click on the “Save and Continue” button:

 

clip1258

 

 

16.You should now see:      

 

clip1259

 

Click on the “Save and Finish” button.
 

 

17.Click on the “Start using Jenkins” button:

 

clip1260

 
 

18.Inside Anatella, go back to the Jenkins configuration screen (i.e. open the “Automation” drop-down menu and select “Configure Jenkins” option). Enter in the Anatella window your Jenkins login and your Jenkins password that you used during step 15 and click the “Test” button:

 

clip1261

 

 

19.You should see “Status: OK” number1. Click the “Save & Close” button number2.

 

        clip1262

 
 

20.Open a browser and naviguate to http://localhost:8080 (this is the default jenkins URL).
 

Alternatively, to navigate to your Jenkins URL, you can now press F9 inside Anatella or click here:
 

clip1263

 
 

You should see:
 

clip1264

 
 

21.Jenkins is now properly configured to work with Anatella.

 
Congratulations!

 

 

22.Optional step: At this point, you might want to add a few optional Jenkins plugins that might be of interest to you. To do so:
 

 

22.1.Open your Jenkins URL in your browser, usually it’s http://localhost:8080

 

22.2.Click on “Manage Jenkins” number1, then click on “Manage plugins” number2:

 

clip1265

 

 

22.3.Click on “Available” number1 and enter (for example) “build triggers” in the search field here number2:

 

clip1266

 
 

22.4.Here are the names of a few plugins that might interest you:

 

 

Plugin name

Plugin function

 

Generic Webhook Trigger

Can receive any HTTP request, extract any values from JSON or XML and trigger a job with those values available as variables. Works with GitHub, GitLab, Bitbucket, Jira and many more.

 

Naginator

Reschedules failed jobs.

 

Filesystem Trigger

makes it possible to monitor changes of a file or a set of files in a folder.

 

URLTrigger

makes it possible to poll changes of URLs.

 

Poll Mailbox Trigger

to poll an email inbox, and trigger jobs based on new emails.

 

Files Found Trigger

Schedules a job when certain files exist.

 

 

23.Optional Step: “Custom Jenkins Initialization Scripts”
 

It happens very often that an Anatella graph must read some data files stored on a remote “central” File Server (typically these data files are stored on a “network” drive that is named “X:” or “Z:”). This situation must be handled in a special way when executing such an Anatella-Graph inside Jenkins.

 

How are created (i.e. “mounted” in technical terms) the network drives? Usually, there exists a customized “ad-hoc” script (written by your IT department) that are “mounting” all the required network drives when you log-in on your computer. This initialization script might typically perform many different tasks, such as:
 

It mounts various network drives on your computer (using the “net use” command).

It initializes different Environmental Variables

It configures different parameters inside various ODBC/OleDB drivers (such as the character encoding of the ODBC drivers).

etc.

 

The Anatella graphs that are executed by Jenkins are each running inside their own “clean” windows session. When Jenkins creates a new “clean” session (to run a new graph), it does not execute any of the “custom initialization scripts” written by your IT department. As a consequence, this means that the network drives (i.e. the drives named “X:” or “Z:”) are not (directly) available. Since some important network drives are missing, it’s very likely that Anatella won’t be able to execute successfully the required data-transformation-graphs.

 
Hopefully, there is a solution to all these difficulties: i.e. We can define our own “custom initialization scripts” that are executed by Jenkins before running any Anatella graph inside Jenkins. In the simplest situation, you know exactly the content of the “custom initialization scripts” written by your IT department and you can simply copy/paste this script inside the “Jenkins Initialization Script Window” that is accessible here:

 
 

23.1.Inside Anatella, go back to the Jenkins configuration screen (i.e. open the “Automation” drop-down menu and select “Configure Jenkins” option) and click on the second panel that is named “Optional Parameters”:

 

clip1267

 

 

23.2.Enter all the “custom initialization scripts” (e.g. all the commands required to “mount” the network drives) here:

 

clip1268

 

 
In many situations, the “custom initialization scripts” written by your IT department will be overly complex and it might just be a better idea to use a much simpler “Custom Jenkins Initialization Scripts” that is composed of just a few lines with some “net use” commands such as these ones:

 

net use Z: \\My_File_Server\public /Y

…or:

net use Z: \\My_File_Server\public <password> /user:<login> /Y

 

 
For example, the above command “mounts” the drive “Z:” using your login so that this drive is accessible for Anatella inside Jenkins.