In this assignment, you will be writing a web application where you have to include some real-time web technologies. You should also publish your application on a real (public) production server.
The idea behind the application is that you should be able to list issues from your GitLab repository for this assignment (e.g., https://gitlab.lnu.se/1dvX23/xx222xx/assignment-3). You will use this repository for your code but also test the application by creating issues (and comments) and include these in your application through the GitLab API and webhooks.
Do you want to use GitHub instead of GitLab? Read the instructions for GitHub instead.
The assignment aims to give the student practical and theoretical experience about developing real-time web applications through Web socket and webhooks. The student should also get practical experience on how to put the built web application into production in a secure way.
Requirements of the application
The image above tries to explain the application flow in this assignment.
- When a client connects to the application, it will use GitLab API (https://docs.gitlab.com/ee/api/README.html), a REST API, and fetch all created issues on your repository. The response will be in JSON, which is good because we work with Node.js.
- One thing the client-script needs to do is, for example, the ability to connect to your server´s WebSocket channel.
- When a new "issue-event" happens on GitLab, they will fire a (by you) registered HTTP POST, which should point to your application.
- The webhook will send you data, and your application should use the web socket channel(s) to update the client in real-time.
- Design your application with security in mind.
- For instance, your code must check that the webhook POST comes from GitLab.
- Along with your code, and installation scripts, you should also commit an assignment report that answers some questions (see below).
- You are free to choose and use third-party packages to solve the problem, but they should be mention and motivated in your assignment report.
We also have the following requirements:
- You must use GitLab, and make several commits, to show how your completed assignment has evolved from the start to the end.
- To announce that you have completed the assignment, you must make a release of your assignment at its repository on GitLab. If a release is not made, the assignment will not be assessed.
To handle API keys
To be able to request data from GitLab API, you must get an API token that identifies yourself. Send the key in the Authorization header in every request so that GitLab could authorize the request. Please note that this key is personal to your GitLab account. That means that the key should never be stored in a repository or shared with anyone (not even the teachers).
There are several ways to authenticate your calls to GitLab: https://docs.gitlab.com/ee/api/README.html#authentication We are going to use Basic Authentication, and you should create a "personal access token". You allow this key to work with issues and send it along with the correct header.
When you register a callback for the webhook, you should also define a secret so that you can validate the hook-requests to your application. This is also one thing to keep secret. You can solve this in a couple of ways. In this assignment, you should use environment variables. This way, you can read from the environment variables in your application and add it when you start your node-application.
Production of application
The application shall be running on a public web server in a production environment. Each student will get their virtual public server (see the production part of this course), but feel free to choose your provider. During the examination, the application should be able to run on your production server (we will not run it locally) therefore, you must add the URL to the application in your repository README.
- The Node.js application should have a reversed proxy (Nginx) in front.
- The application shall be running through HTTPS (no requirement of buying a domain name, so the self-signed certificate is OK - fixing an own certificate I preferred).
- The server should only listen to port 80, 443, and 22(ssh). That means you should not be able to make requests directly to your node application and that all requests go through the reversed proxy.
- The Node.js application should be running through PM2 and be in production mode.
- If you use some kind of installation script on your production server, this should be added to your repository.
As a complement to your code, you should provide an assignment report. You do this by answering the following questions in your repositories RELEASE.md.
- What is the URL to your application?
- Describe what you have done to make your application secure, both in code and when configuring your application server.
- Describe the following parts, how you are using them, and what their purpose is in your solution:
- Reversed proxy
- Process manager
- TLS certificates
- Environment variables
- What differs in your application when running it in development from running it in production?
- Which extra modules did you use in the assignment? Motivate the use of them and how you have to make sure that they are secure enough for production.
- Have you implemented any extra features (see below) that could motivate a higher grade of this assignment? If so, describe them.
Extra features [optional]
For those of you aiming for higher grades in this course, there will be some suggestions for extra features that you could implement.
- First of all - You probably have other ideas feel free to try them.
- Implement a richer web client that can control the issues through the application (closing issues, adding comments, etc.). Think about security!
- Add some kind of custom authentication before the user can enter the application.
- Do an authentication through GitLab's OAuth provider instead of the Basic Authentication. This way, a user could log into your applications through their OAuth credentials and will see all of their resources.
- The user could then choose what repository to watch, and the server application creates the webhook through the web API.
To be able to solve the assignment, you may do some reading in the documentation at GitLab. Here are some links:
- https://serveo.net/ - Alternative to ngrok for exposing local server when developing with web-hooks
During the examination, your code will be reviewed. To pass the exam, you must be able to answer questions about your code.
Demo of the application
Deadline and submission
Deadline: 2020-03-18 12:00
To tell the course management that your application is ready to be assessed, you need to make a release.
The release must be made before the deadline to get the assignment assessed. To make a release you need to add a RELEASE.md-file with certain content to your repository.
- Make sure you are located in the root of your repository.
- Get the template. ‘wget https://gitlab.lnu.se/1dv023/content/examination-assignments/examination-3-template/raw/master/RELEASE.md’
- Edit the file and make sure to follow the instructions in the file.
- Save the file and add it to git (`git add RELEASE.md`)
- Commit (`git commit`) the file and push (`git push`) it to GitLab.
- Visit CodeGrade and make sure you pass the “Release”-rubric category.
To tell you that you intend to submit the assignment, it is important that you make a complete submission for the assignment to be assessed.
To be able to book a time slot for the oral examination you must make a release before the deadline. Booked time slots without a release made will be cleared without further notice.
The examination will be an oral hearing, including the theory raised to this point of the course. During the examination, you will be asked a couple of questions. You will also defend your solution for the assignment. Notes will be taken on how well you answered the questions and how good your application is depending on security, functionality, and code quality. The notes will be used when setting the final grade on the course. For this assignment, however, the grade is U (failed, “underkänd”), and G (pass, “godkänd”).
Book time for examination
You book a time slot in MyMoodle, https://mymoodle.lnu.se/course/view.php?id=45628.