147 lines
6.0 KiB
HTML

<html>
<head>
<title>PVT course Jenkins instructions</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="./style.css"/>
</head>
<body>
<h1>Jenkins</h1>
<p>
Jenkins is a web-based continuous integration (CI) server that can build,
test and deploy software automatically based on various triggers.
</p>
<p>
Once you have created your Spring Boot project and pushed your code to a
git server, you can configure jenkins to build and deploy your project
to your group's tomcat container.
</p>
<p>
The address of your group's own jenkins instance and the corresponding
container to deploy to, along with the necessary credentials, are available
to all group members on <a href='./'>the keys page</a>.
</p>
<h2>Configure your build</h2>
<p>
On the jenkins dashboard, click "New Item" in the upper left, enter a job name,
choose the project type "Maven project" and click "OK"
<br/><img src="img/jenkins-1.png" />
</p>
<p>
You are now looking at the project configuration page, where most of the
configuration is done.
</p>
<p>
In order to save disk space, check "Discard old builds"
<br/><img src="img/jenkins-2.png" />
</p>
<h3>Git settings</h3>
<p>
Under "Source code management", choose "git" and enter your project's git URL
under "Repository URL" (usually something like
<code>git@gitea.dsv.su.se:[ausername]/[aprojectname].git</code>). Make sure
you're using the SSH version of the git URL, otherwise you may run into a lot
of authentication issues.
<br/><img src="img/jenkins-3.png" />
</p>
<p>
If your repo isn't public, jenkins will need to authenticate in order to
pull the code.
<ul>
<li>Under "Credentials", click "Add", followed by "jenkins" in the drop-down
<br/><img src="img/jenkins-4.png" /></li>
<li>Change "Kind" to "SSH username with private key"</li>
<li>Enter a useful description, e.g "gitea pull key" or similar</li>
<li>Under "Username", fill in "git"</li>
<li>Under "Private key", click "Enter directly" and paste the <em>private</em>
key from <a href='./'>the keys page</a></li>
<li>Leave the passphrase blank and click "Add"
<br/><img src="img/jenkins-5.png" /></li>
</ul>
Once you have set up the private key in jenkins, you will need to add the
public key as a deploy key on the git server. How to do this depends on the
server, but this is how to do it in gitea (github works very similarly):
<ul>
<li>Open your repo in the gitea web interface</li>
<li>Click "Settings" in the upper right (same row as Code and Issues)
<br/><img src="img/jenkins-6.png" /></li>
<li>Click the "Deploy Keys" heading and choose "Add Deploy Key"
<br/><img src="img/jenkins-7.png" /></li>
<li>Paste the <em>public</em> key from <a href="./">the keys page</a> into
the "Content" box</li>
<li>Click the green "Add Deply Key" button below the form
<br/><img src="img/jenkins-8.png" /></li>
</ul>
If you don't give the key a title it will be pulled from the public key
itself, using the comment at the end of the key which will be "group-X-Y@pvt".
</p>
<h3>Maven settings</h3>
<p>
If your <code>pom.xml</code> file isn't located in the project's root
directory, you need to change the default configuration in the field
"Root POM" under "Build".
<br/><img src="img/jenkins-9.png" />
</p>
<p>
At this point the build configuration should be complete enough to build
(but not yet deploy) your project. You may try to run your job - it should
finish successfully if your git and maven configurations are correct. The
job will not deploy anything yet though, it only compiles according to
your <code>pom.xml</code>.
</p>
<h3>Deployment settings</h3>
<p>
In order to actually deploy your compiled code, click "Add post-build
action" at the very bottom of the configuration page and choose
"Deploy war/ear to a container".
<br/><img src="img/jenkins-10.png" />
</p>
<p>
In the field "WAR/EAR files" you need to point to the war file you want
to deploy. If your project only produces a single WAR file, you can use
the shorthand "**/*.war" here. Otherwise, enter the path to your WAR file,
relative to the project's root directory.
</p>
<p>
In the field "Context path" you should enter "/". You can also enter a
different path such as "/myproject", but deploying directly to the root
context is a good default behaviour.
<br/><img src="img/jenkins-11.png" />
</p>
<h4>Tomcat settings</h4>
<p>
Click "Add Container" and choose "Tomcat 9.x Remote".
<br/><img src="img/jenkins-12.png" />
</p>
<p>
You will need to store credentials in a similar way to the git pull key:
</p>
<ul>
<li>Under "Credentials", click "Add", followed by "jenkins"
in the drop-down
<br/><img src="img/jenkins-13.png" /></li>
<li>Under "Username", fill in "tomcat"</li>
<li>Under "Password", paste the tomcat manager password from
<a href='./'>the keys page</a></li>
<li>Enter a useful description, e.g "tomcat deploy credentials"
or similar
<br/><img src="img/jenkins-14.png" /></li>
</ul>
<p>
Under "Tomcat URL", enter the container URL listed on
<a href='./'>the keys page</a>.
<br/><img src="img/jenkins-15.png" />
</p>
<h3>Finished</h3>
<p>
Your job should now be fully set up. Given that everything is set up
correctly and your code compiles and passes any tests you may have, your
application should be running in your container once the job has finished.
</p>
<p>
Any failures will be indicated by the job status (it wil be shown as failed),
and the log will contain details about what exactly went wrong.
</p>
</body>
</html>