221 lines
9.9 KiB
HTML
221 lines
9.9 KiB
HTML
<html>
|
|
<head>
|
|
<title>PVT course Project 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?a"/>
|
|
</head>
|
|
<body>
|
|
<h1>Project setup with SpringBoot, Git and Maven</h1>
|
|
<h2>Tools</h2>
|
|
<p>
|
|
The recommended toolchain for this course is:
|
|
</p>
|
|
<ul>
|
|
<li><a href="https://adoptium.net/">OpenDJK</a></li>
|
|
<li><a href="https://spring.io/">SpringBoot</a></li>
|
|
<li><a href="https://www.eclipse.org/eclipseide/">Eclipse IDE</a></li>
|
|
<li><a href="https://spring.io/tools">Spring Tools for Eclipse</a></li>
|
|
<li><a href="https://git-scm.com/downloads">Git</a></li>
|
|
<li><a href="https://gitea.dsv.su.se/">Gitea</a></li>
|
|
<li><a href="./jenkins.html">Jenkins</a></li>
|
|
</ul>
|
|
<h2>Resources</h2>
|
|
<ul>
|
|
<li>Guides for using Spring Boot:
|
|
<a href="https://spring.io/guides">https://spring.io/guides</a></li>
|
|
<li>A REST service example: <a href="https://spring.io/guides/gs/rest-service/">
|
|
https://spring.io/guides/gs/rest-service/</a></li>
|
|
<li>Quickstart guide that covers project setup and a simple hello world
|
|
program: <a href="https://spring.io/quickstart">https://spring.io/quickstart</a></li>
|
|
<li>Spring Initializr, a tool to quickly configure your project:
|
|
<a href="https://start.spring.io/">https://start.spring.io/</a></li>
|
|
<li>
|
|
This is a video guide to setting up a hello world example in spring: <br/><a target="_blank" href="https://play.dsv.su.se/player/38a73fe6-2141-4716-ab80-0b193ff03b0c"><img src="https://play-store-prod.dsv.su.se/presentation/38a73fe6-2141-4716-ab80-0b193ff03b0c/GV6y9MmhiLjEhfvhDy9TiBDGkNAoeEmBVdrsGXub.png" width="560" height="315"></a>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
These instructions are also available in video format: <br/><a target="_blank" href="https://play.dsv.su.se/player/f0352361-4099-4fe3-8622-7a413d33fac2"><img src="https://play-store-prod.dsv.su.se/presentation/f0352361-4099-4fe3-8622-7a413d33fac2/nJSD14aDmqzfoSEGrh4em4PaS2vuKZiGtk8Hgcb2.png" width="560" height="315"></a>
|
|
</p>
|
|
<h2>Git</h2>
|
|
<p>
|
|
Once you have familiarized yourself a bit with Spring, you should set
|
|
up version control. There are lots of options, but the recommended
|
|
approach is to use Git and host your project at
|
|
<a href="https://gitea.dsv.su.se/">the DSV Gitea instance</a>.
|
|
</p>
|
|
<p>
|
|
In order to be able to deploy your code using an external tool like Jenkins,
|
|
you will need to create a local git repository, add your code to it, and
|
|
regularly push the updates in your local repository to a server-based
|
|
mirror that Jenkins can pull the code from.
|
|
</p>
|
|
<h3>Setting up gitea remote</h3>
|
|
<p>
|
|
In order to set up the remote mirror, start by logging in at
|
|
<a href="https://gitea.dsv.su.se/">Gitea</a>. Once logged in, do the following:
|
|
</p>
|
|
<ul>
|
|
<li>Click the "+" icon in the upper right of the window and choose
|
|
"New Repository"<br/><img src="img/git-1.png"></li>
|
|
<li>Enter a repository name. The name can't contain whitespace since
|
|
it will be part of the git URL.<br/><img src="img/git-2.png"></li>
|
|
<li>If you want the repository to not be publically viewable, check the box
|
|
marked "Make Repository Private"</li>
|
|
<li>All the other fields can be left blank</li>
|
|
<li>Click the green button labeled "Create Repository"<br/>
|
|
<img src="img/git-3.png"></li>
|
|
</ul>
|
|
<p>
|
|
You now have an empty repository prepared on the server, where you will be
|
|
pushing your code. Under the heading "Clone this repository" you should see
|
|
the git URL to this repository. In order to minimize authentication-related
|
|
confusion, you should always be using the "SSH" variant of the git URL.
|
|
</p>
|
|
<p>
|
|
Keep this page open, you will need the git URL later.
|
|
</p>
|
|
<h3>Adding a public key for pushing your code</h3>
|
|
<p>
|
|
In order to push code from your computer to the gitea remote, you will need to
|
|
configure public key authentication for gitea. If you don't already have a
|
|
public key to use, you will need to create one now:
|
|
</p>
|
|
<ul>
|
|
<li>Open a terminal (linux/mac) or git bash (widows)</li>
|
|
<li>Run the command <code>ssh-keygen</code></li>
|
|
<li>Press enter through the prompts <em>except</em> if it asks to
|
|
overwrite an existing key, in which case you should answer no and use
|
|
your existing key instead</li>
|
|
</ul>
|
|
<p>
|
|
Now you have a key pair that you can use for pushing your code. You now need
|
|
to add the public part of that key to your gitea user.
|
|
</p>
|
|
<ul>
|
|
<li>In order to find your public key, run <code>cat ~/.ssh/id_*.pub</code>
|
|
in your terminal/git bash. A long string of alphanumeric characters should
|
|
be printed in the terminal. Keep the window around, you will need it later.
|
|
<br/><img src="img/git-4.png"></li>
|
|
<li>Open <a href="https://gitea.dsv.su.se/">gitea</a> in your web browser</li>
|
|
<li>Click your avatar in the upper right of the screen and choose "Settings"
|
|
<br/><img src="img/git-5.png"></li>
|
|
<li>Click the "SSH/GPG Keys" heading</li>
|
|
<li>Under "Manage SSH keys", click "Add key"</li>
|
|
<li>Go back to the window with the public key in it, highlight the output and
|
|
copy it (right-click -> copy)</li>
|
|
<li>Paste the public key in the "Content" box in gitea. <em>Do NOT</em> use the
|
|
keys from <a href="./">the keys page</a> here!</li>
|
|
<li>Click the green button labeled "Add Key"<br/><img src="img/git-6.png"></li>
|
|
</ul>
|
|
<h3>Setting up your local repository and connecting it to the remote</h3>
|
|
<p>
|
|
This is how to set up your repository using the command-line git tools:
|
|
</p>
|
|
<ul>
|
|
<li>Open a terminal (on linux/mac) or git bash (windows) and navigate to the
|
|
directory where you keep your source code for this project.</li>
|
|
<li>Initialize an empty repository in the current directory:
|
|
<code>git init</code></li>
|
|
<li>Add the gitea remote using the SSH URL from when you created your repository
|
|
on gitea: <code>git remote add origin [your git URL]</code>
|
|
<li>Instruct git to track all existing files in this directory and any
|
|
subdirectories: <code>git add .</code></li>
|
|
<li>Make the initial commit of the files you just staged:
|
|
<code>git commit -m "First commit"</code></li>
|
|
<li>Push your code to the remote: <code>git push -u origin master</code></li>
|
|
</ul>
|
|
<p>
|
|
Your code should now be browseable in the gitea web UI.
|
|
</p>
|
|
<p>
|
|
The core git commands you will be needing when developing are:
|
|
</p>
|
|
<ul>
|
|
<li><code>git add [file]</code> - Add a new file to be tracked by git, or
|
|
stage new changes to an already tracked file</li>
|
|
<li><code>git commit</code> - Commit your currently staged changes</li>
|
|
<li><code>git push</code> - Push local commits to the remote</li>
|
|
<li><code>git pull</code> - Pull commits fro mthe remote to your local copy</li>
|
|
<li><code>git status</code> - View the current state of your repository;
|
|
both any local changes and how your local copy differs from the remote</li>
|
|
</ul>
|
|
<p>
|
|
You will need to find out a number of things yourself in order for the group to
|
|
be able to share a single repository with a reasonable workflow:
|
|
</p>
|
|
<ul>
|
|
<li>Granting other users write access to a repository you own</li>
|
|
<li>Resolving merge conflicts</li>
|
|
<li>Using git integrations in IDEs</li>
|
|
</ul>
|
|
<h3>Preparing your project for deployment to tomcat</h3>
|
|
<p>
|
|
If you usually run your project in SpringBoot's embedded tomcat server,
|
|
your <code>pom.xml</code> will need to be updated to be buildable by
|
|
jenkins and produce a deployable artifact.
|
|
</p>
|
|
<ul>
|
|
<li>Make sure maven produces a war package:
|
|
<pre><packaging>war</packaging></pre></li>
|
|
<li>Add a dependency to jenkins core libraries: <pre>
|
|
<dependency>
|
|
<groupId>com.fasterxml.jackson.core</groupId>
|
|
<artifactId>jackson-core</artifactId>
|
|
</dependency>
|
|
</pre></li>
|
|
<li>Add a maven extension for git integration: <pre>
|
|
<build>
|
|
...
|
|
<extensions>
|
|
...
|
|
<extension>
|
|
<groupId>ar.com.synergian</groupId>
|
|
<artifactId>wagon-git</artifactId>
|
|
<version>0.2.5</version>
|
|
</extension>
|
|
</extensions>
|
|
</build>
|
|
</pre></li>
|
|
<li>Add the source repositories for the new dependencies: <pre>
|
|
<repositories>
|
|
<repository>
|
|
<id>spring-releases</id>
|
|
<url>https://repo.spring.io/libs-release</url>
|
|
</repository>
|
|
</repositories>
|
|
<pluginRepositories>
|
|
<pluginRepository>
|
|
<id>spring-releases</id>
|
|
<url>https://repo.spring.io/libs-release</url>
|
|
</pluginRepository>
|
|
<pluginRepository>
|
|
<id>synergian-repo</id>
|
|
<url>https://raw.github.com/synergian/wagon-git/releases</url>
|
|
</pluginRepository>
|
|
</pluginRepositories>
|
|
</pre></li>
|
|
<li>Add the URL to your gitea remote: <pre>
|
|
<distributionManagement>
|
|
<repository>
|
|
<id>internal.repo</id>
|
|
<name>Internal repo</name>
|
|
<url>git@gitea.dsv.su.se/[auser]/[arepo].git</url>
|
|
</repository>
|
|
</distributionManagement>
|
|
</pre></li>
|
|
</ul>
|
|
<p>
|
|
Now your <code>pom.xml</code> should be all set. The remaining thing
|
|
to be done is to modify your main application to extend
|
|
<code>SpringBootServletInitializer</code>:
|
|
</p>
|
|
<img src="./img/git-7.png" />
|
|
</a>
|
|
<p>
|
|
Once these changes have all been made, commit and push your code to the
|
|
remote as usual. Once the updates have been pushed to the remote, you should be able to build and deploy yor project using <a href="./jenkins.html">Jenkins</a>.
|
|
</p>
|
|
</body>
|
|
</html>
|