2021-07-31 16:29:30 +00:00
# Project Info
First of all, thank you everyone who made pull requests for Uptime Kuma, I never thought GitHub Community can be that nice! And also because of this, I also never thought other people actually read my code and edit my code. It is not structed and commented so well, lol. Sorry about that.
2021-09-12 17:23:51 +00:00
The project was created with vite.js (vue3). Then I created a sub-directory called "server" for server part. Both frontend and backend share the same package.json.
2021-07-31 16:29:30 +00:00
2021-10-03 08:04:16 +00:00
The frontend code build into "dist" directory. The server (express.js) exposes the "dist" directory as root of the endpoint. This is how production is working.
# Key Technical Skills
- Node.js (You should know what are promise, async/await and arrow function etc.)
- Socket.io
- SCSS
- Vue.js
- Bootstrap
- SQLite
# Directories
- data (App data)
- dist (Frontend build)
- extra (Extra useful scripts)
- public (Frontend resources for dev only)
- server (Server source code)
- src (Frontend source code)
- test (unit test)
2021-07-31 16:29:30 +00:00
2021-08-24 06:42:35 +00:00
# Can I create a pull request for Uptime Kuma?
2021-10-04 15:31:36 +00:00
Generally, if the pull request is working fine and it do not affect any existing logic, workflow and perfomance, I will merge into the master branch once it is tested.
2021-08-24 06:42:35 +00:00
If you are not sure, feel free to create an empty pull request draft first.
## Pull Request Examples
### ✅ High - Medium Priority
- Add a new notification
- Add a chart
- Fix a bug
2021-09-12 17:23:51 +00:00
### *️⃣ Requires one more reviewer
2021-08-24 06:42:35 +00:00
2021-08-28 05:46:47 +00:00
I do not have such knowledge to test it.
2021-08-24 06:42:35 +00:00
2021-09-12 17:23:51 +00:00
- Add k8s supports
2021-08-24 06:42:35 +00:00
2021-09-12 17:23:51 +00:00
### *️⃣ Low Priority
2021-08-24 06:42:35 +00:00
2021-08-28 05:46:47 +00:00
It changed my current workflow and require further studies.
2021-08-24 06:42:35 +00:00
- Change my release approach
### ❌ Won't Merge
- Duplicated pull request
- Buggy
- Existing logic is completely modified or deleted
- A function that is completely out of scope
2021-07-31 16:29:30 +00:00
# Project Styles
2021-09-12 17:23:51 +00:00
I personally do not like something need to learn so much and need to config so much before you can finally start the app.
2021-07-31 16:29:30 +00:00
- Easy to install for non-Docker users, no native build dependency is needed (at least for x86_64), no extra config, no extra effort to get it run
- Single container for Docker users, no very complex docker-composer file. Just map the volume and expose the port, then good to go
2021-10-03 08:04:16 +00:00
- Settings should be configurable in the frontend. Env var is not encouraged.
2021-07-31 16:29:30 +00:00
- Easy to use
2021-08-24 06:06:23 +00:00
# Coding Styles
2021-10-03 08:04:16 +00:00
- 4 spaces indentation
2021-09-12 17:23:51 +00:00
- Follow `.editorconfig`
- Follow ESLint
2021-08-24 06:06:23 +00:00
## Name convention
- Javascript/Typescript: camelCaseType
- SQLite: underscore_type
- CSS/SCSS: dash-type
2021-07-31 16:29:30 +00:00
# Tools
2021-09-12 17:23:51 +00:00
2021-07-31 16:29:30 +00:00
- Node.js >= 14
- Git
2021-10-03 08:04:16 +00:00
- IDE that supports ESLint and EditorConfig (I am using Intellji Idea)
- A SQLite tool (SQLite Expert Personal is suggested)
2021-07-31 16:29:30 +00:00
2021-09-12 17:23:51 +00:00
# Install dependencies
2021-07-31 16:29:30 +00:00
```bash
2021-10-03 08:04:16 +00:00
npm ci
2021-08-31 12:36:17 +00:00
```
2021-10-03 08:04:16 +00:00
# How to start the Backend Dev Server
2021-07-31 16:29:30 +00:00
2021-09-23 14:48:19 +00:00
(2021-09-23 Update)
2021-07-31 16:29:30 +00:00
2021-09-23 14:48:19 +00:00
```bash
npm run start-server-dev
2021-07-31 16:29:30 +00:00
```
2021-09-12 17:23:51 +00:00
It binds to `0.0.0.0:3001` by default.
2021-07-31 16:29:30 +00:00
## Backend Details
It is mainly a socket.io app + express.js.
2021-09-12 17:23:51 +00:00
express.js is just used for serving the frontend built files (index.html, .js and .css etc.)
2021-07-31 16:29:30 +00:00
2021-10-03 08:04:16 +00:00
- model/ (Object model, auto mapping to the database table name)
- modules/ (Modified 3rd-party modules)
- notification-providers/ (indivdual notification logic)
- routers/ (Express Routers)
- scoket-handler (Socket.io Handlers)
- server.js (Server main logic)
2021-07-31 16:29:30 +00:00
2021-10-03 08:04:16 +00:00
# How to start the Frontend Dev Server
2021-07-31 16:29:30 +00:00
2021-10-03 08:04:16 +00:00
1. Set the env var `NODE_ENV` to "development".
1. Start the frontend dev server by the following command.
```bash
npm run dev
```
It binds to `0.0.0.0:3000` by default.
2021-07-31 16:29:30 +00:00
2021-09-12 17:23:51 +00:00
You can use Vue.js devtools Chrome extension for debugging.
2021-07-31 16:29:30 +00:00
## Build the frontend
```bash
npm run build
```
## Frontend Details
Uptime Kuma Frontend is a single page application (SPA). Most paths are handled by Vue Router.
2021-09-12 17:23:51 +00:00
The router is in `src/router.js`
2021-07-31 16:29:30 +00:00
As you can see, most data in frontend is stored in root level, even though you changed the current router to any other pages.
2021-09-12 17:23:51 +00:00
The data and socket logic are in `src/mixins/socket.js` .
2021-07-31 16:29:30 +00:00
2021-10-03 08:04:16 +00:00
2021-07-31 16:29:30 +00:00
# Database Migration
2021-10-03 08:04:16 +00:00
1. Create `patch-{name}.sql` in `./db/`
2. Add your patch filename in the `patchList` list in `./server/database.js`
2021-07-31 16:29:30 +00:00
# Unit Test
Yes, no unit test for now. I know it is very important, but at the same time my spare time is very limited. I want to implement my ideas first. I will go back to this in some points.
