Setting up OPF for Gitlab
Open Project Framework (OPF) is a project template used by Jamk. It consists of a documentation site based on MkDocs and Gitlab integrations like git repository, issue tracker, and CI/CD pipelines for automated site deploys. The documentation for the site is written in markdown files.
Introduction#
The OPF-project environment is a preorganized Gitlab repository with selected files and folders. Several Gitlab features like git repository, issue tracker and CI/CD Pipeline are used a foundation for a working environment. As a student you will be working with independent project and template documents. Project environment is generated automatically by request.
Target of PT-1#
Primary target for PT1-exercise is to build on top of the project documentation template and modify some configuration files to make it better suitable for student use.
Here are the next steps:
- Naming the project, adding important information and publish project pages to external world
- Execute first CI/CD-pipeline jobs
- Get familiar with the OPF folder structure and documents
- First document edits with Markdown documents
- Creation of Markdown Table
- Add images and links
- Add images from local git repository
- Editing PlantUML diagrams and dealing with problems in CI/CD Pipeline
Getting to know the OPF project framework#
We have created for you a personal project repository in Labranet Gitlab according to the OPF project framework. Now we begin to get acquainted with its content and purpose.
- There is lot of guides for MarkDown like this https://www.markdownguide.org/cheat-sheet/ Do some googling and find best for you
Some important steps to create and link files and creation of new from template files
The content of the OPF framework may seem extensive, but it is worth reading the material in section ** 2.4 Project documentation ** and on the basis of this it is conceived that the framework works in the so-called project folder.
More on the tooling#
Git#
We assume that at this point you are pretty comfortable with Git as ICT students because a lot of courses require you to create Git projects for your assignments. If you are not yet familiar with Git, there are plenty of free online resources that you can use to learn git. Jamk also offers a course on Git that you can take to be better prepared for this course.
- Git course by Jamk
- How to Contribute to an Open Source Project on GitHub is a free course from Egghead.io. It is aimed at Github users but can easily be used for Gitlab as well if you know the basics
Gitlab (CI/CD) pipelines#
Every time you edit a file in your project's git repo, it builds and deploys the updated version of the site. This is being done with Gitlab pipelines. The file with the configuration of your pipelines is called .gitlab-ci.yml and it is written in the YAML format. Here is a cheatsheet on YAML
Markdown#
Markdown is a document syntax which you should already be familiar with as an ICT student if you have worked with Git in any of your courses. Below are some resources if you need a refresher:
MkDocs#
MkDocs is the static site generator used by OPF to build the documentation site. You will not have to mess around with it too much because everything is already set up for you.
PlantUML#
PlantUML makes Diagrams as Code possible. It is a tool that let's you create diagrams by writing them as fenced code blocks inside your markdown files. While prmarily aimed at UML diagrams, it also lets you create other diagrams like mindmaps, and GANTT charts etc. We will be creating a bunch of UML diagrams to include in our documentation, and PlantUML is integrated to make editing and generating diagrams easier. You can specify what you want the diagram to show in text and it will generate a PNG image for you.
For example, the following code inside your markdown file
```plantuml
@startmindmap
+ Product
++ Internal Messaging System
+++ Users can send and receive messages.
+++ Functionality: Secure communication
++ Billing Management
+++ Users can pay bills through the system.
+++ Functionality: Payment processing integration
++ Cart Management
+++ Tracks and stores customer selections.
+++ Functionality: Purchase history management
++ Real-Time Analytics
+++ Provides real-time transaction insights.
+++ Functionality: Data visualization and reporting
@endmindmap
```
will get replaced by this PNG image of a mindmap
What the hell are UML diagrams?!
UML diagrams are a widely used way to describe the structures / architecture and implementation of software products. Definitely worth a look Unified Modelling Language -descriptions independently. In the current course, a few diagrams are lightly used as part of the documents. To produce these diagrams, the PlantUML generator, which works as part of the Gitlab service, is utilized.