In this series of articles, I'd like to present and discuss several possible approaches toward software development with
InterSystems technologies and GitLab. I will cover such topics as:Git 101Git flow (development process)GitLab installationGitLab WorkflowContinuous DeliveryGitLab installation and configurationGitLab CI/CDIn the first article, we covered Git basics, why a high-level understanding of Git concepts is important for modern software development, and how Git can be used to develop software.In the second article, we covered GitLab Workflow - a complete software life cycle process and Continuous Delivery.I this article we'll discuss:GitLab installation and configurationConnecting your environments to GitLabGitLab installationWe're going to install GitLab on premise. There are many ways to install GitLab - from source, package, in a container. I'm not actually going to describe all the steps here, there is a guide for that. But still, some notes.Prerequisites:Separate server - since it's a web application and a fairly resource intensive it's better to run it on a separate serverLinux(Optional but strongly recommended) Domain - required to run pages and secure the whole setupConfigurationFirst of all, you'd probably need to send emails with notifications.Next, I recommend installing Pages. As we discussed in the previous article - artifacts from the script can be uploaded into GitLab. User can download them but it's useful to be able to open them directly in browser and for that we need pages.Why do you need pages:To display some generated wiki or a static page for your projectTo display html artifactsOther stuff you can do with pagesAnd as html pages can have an onload redirect, they can be used to send the user wherever we need. For example here's the code that generates html page which sends a user to the last executed unit test (at the moment of html generation):
ClassMethod writeTestHTML()
{
set text = ##class(%Dictionary.XDataDefinition).IDKEYOpen($classname(), "html").Data.Read()
set text = $replace(text, "!!!", ..getURL())
set file = ##class(%Stream.FileCharacter).%New()
set name = "tests.html"
do file.LinkToFile(name)
do file.Write(text)
quit file.%Save()
}
ClassMethod getURL()
{
set url = "http://host:57772"
set url = url _ $system.CSP.GetDefaultApp("%SYS")
set url = url_"/%25UnitTest.Portal.Indices.cls?Index="_ $g(^UnitTest.Result, 1) _ "&$NAMESPACE=" _ $zconvert($namespace,"O","URL")
quit url
}
XData html
{
<html lang="en-US">
<head>
<meta charset="UTF-8"/>
<meta http-equiv="refresh" content="0; url=!!!"/>
<script type="text/javascript">window.location.href = "!!!"</script>
</head>
<body>
If you are not redirected automatically, follow this <a href='!!!'>link to tests</a>.
</body>
</html>
}
There's is a bug I encountered using pages (502 error when browsing artifacts) - here's a fix.
Connecting your environments to GitLab
To run CD scripts you need environments - configured servers to run your application. Assuming you have a Linux server with
InterSystems product installed (let's say
InterSystems IRIS, but it would work with Caché and Ensemble too) these steps would connect environment to GitLab:
Install GitLab runnerRegister runner with GitLabAllow runner to call
InterSystems IRIS
Important note on installing GitLab runner - DON'T clone servers after you installed GitLab runner. Results are unpredictable and most unwelcome.
Register runner with GitLab
After you run the initial:
sudo gitlab-runner register
you'd be presented with several prompts and While most of the steps are fairly straightforward several are not:
Please enter the gitlab-ci token for this runner
There are several tokens available:
One for the whole system (available in administration settings)One for each project (available in project settings)
As you connect a runner to run CD for a specific project you need to specify a token for this project.
Please enter the gitlab-ci tags for this runner (comma separated):
In your CD configuration, you can filter which scripts run on which tags. So in the most simple case specify one tag which would be environment name.
Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:docker
If you're using the usual server without docker choose shell. Docker would be discussed in the later parts.
Allow runner to call
InterSystems IRIS
After connecting runner to GitLab we need to allow it to interact with
InterSystems IRIS, to do that:
gitlab-runner user should be able to call csession. To do that add him to cacheusr group:
usermod -a -G cacheusr gitlab-runnerCreate gitlab-runner user in
InterSystems IRIS and give him roles to do CD tasks (write to DB, etc)Allow OS-level authentication
For 2 and 3 other approaches can be used, such as passing user/pass but I think that OS authentication is preferable.
Conclusion
In this part:
Installed GitLabConnected environments to GitLab
Links
Installation instructionsPagesRunnerPart I: GitPart II: GitLab workflow
What's next
In the next part, we'd write our Continuous Delivery configuration. Hi Eduard,
I have followed your Article. On our own Linux environment it works well but when I try to run it on a clients windows server; and the following command is run by the runner
irissession IRISHEALTH -U TEST "##class(isc.git.GitLab).load()"
we get the following "error"
<NOTOPEN>>
I do not know why this happens, it does look like it has something to do with user rights but I am totally lost at this point as we have done everything I can think off relating to grant correct access etc.
Do you perhaps have something you can point me to to try and get this working, the client running the Windows server does does not want to move to Linux as they do not have IT people that can work on it. If it's a non-production instance you can try running iris windows service (IRIS controller for IRISHEALTH in your case) under your windows user account, instead of the default system one. That usually helps.
If it's not possible, either give system account rights to irissession or create a new user with rights for irissession and run the iris service under that account.
