2021-07-31 18:29:30 +02:00
# Project Info
2023-11-16 14:31:20 +02:00
First of all, I want to thank everyone who have made pull requests for Uptime Kuma. I never thought the GitHub community would be so nice! Because of this, I also never thought that other people would actually read and edit my code. It is not very well structured or commented, sorry about that.
2021-07-31 18:29:30 +02:00
2023-11-16 14:31:20 +02:00
The project was created with vite.js (vue3). Then I created a subdirectory called "server" for the server part. Both frontend and backend share the same `package.json` .
2021-07-31 18:29:30 +02:00
2023-08-24 18:01:47 +02:00
The frontend code builds into "dist" directory. The server (express.js) exposes the "dist" directory as the root of the endpoint. This is how production is working.
2021-10-03 10:04:16 +02:00
2021-10-13 02:01:34 +02:00
## Key Technical Skills
2021-10-03 10:04:16 +02:00
2023-11-16 14:31:20 +02:00
- Node.js (You should know about promises, async/await, arrow functions, etc.)
2021-10-03 10:04:16 +02:00
- Socket.io
- SCSS
- Vue.js
- Bootstrap
- SQLite
2021-10-13 02:01:34 +02:00
## Directories
2021-10-03 10:04:16 +02:00
2023-02-01 16:39:09 +02:00
- config (dev config files)
2021-10-03 10:04:16 +02:00
- data (App data)
2023-02-01 16:39:09 +02:00
- db (Base database and migration scripts)
2021-10-03 10:04:16 +02:00
- dist (Frontend build)
2023-02-01 16:39:09 +02:00
- docker (Dockerfiles)
2021-10-03 10:04:16 +02:00
- extra (Extra useful scripts)
- public (Frontend resources for dev only)
- server (Server source code)
- src (Frontend source code)
- test (unit test)
2021-07-31 18:29:30 +02:00
2021-10-13 02:01:34 +02:00
## Can I create a pull request for Uptime Kuma?
2021-08-24 08:42:35 +02:00
2023-08-24 18:01:47 +02:00
Yes or no, it depends on what you will try to do. Since I don't want to waste your time, be sure to **create an empty draft pull request or open an issue, so we can have a discussion first** . Especially for a large pull request or you don't know if it will be merged or not.
2022-06-01 08:08:10 +02:00
2022-09-19 13:56:30 +02:00
Here are some references:
2022-03-02 08:25:37 +02:00
2023-10-02 23:48:21 +02:00
### ✅ Usually accepted
2023-01-24 19:37:19 +02:00
- Bug fix
- Security fix
2022-03-02 08:25:37 +02:00
- Adding notification providers
2023-08-02 11:30:54 +02:00
- Adding new language files (see [these instructions ](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md ))
2023-01-24 19:37:19 +02:00
- Adding new language keys: `$t("...")`
2022-03-02 08:25:37 +02:00
2023-10-02 23:48:21 +02:00
### ⚠️ Discussion required
2022-03-02 08:25:37 +02:00
- Large pull requests
2022-04-29 07:39:30 +02:00
- New features
2021-10-25 06:06:01 +02:00
2023-10-02 23:48:21 +02:00
### ❌ Won't be merged
2023-08-24 18:01:47 +02:00
- A dedicated PR for translating existing languages (see [these instructions ](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md ))
- Do not pass the auto-test
2022-06-01 08:08:10 +02:00
- Any breaking changes
2023-06-18 17:45:50 +02:00
- Duplicated pull requests
2022-06-01 08:08:10 +02:00
- Buggy
2023-10-02 23:48:21 +02:00
- UI/UX is not close to Uptime Kuma
2023-06-18 17:45:50 +02:00
- Modifications or deletions of existing logic without a valid reason.
- Adding functions that is completely out of scope
- Converting existing code into other programming languages
- Unnecessarily large code changes that are hard to review and cause conflicts with other PRs.
2022-09-19 13:56:30 +02:00
2023-06-18 17:45:50 +02:00
The above cases may not cover all possible situations.
2023-01-07 18:32:13 +02:00
2023-11-16 14:31:20 +02:00
I ([@louislam](https://github.com/louislam)) have the final say. If your pull request does not meet my expectations, I will reject it, no matter how much time you spent on it. Therefore, it is essential to have a discussion beforehand.
2023-01-07 18:32:13 +02:00
2023-08-24 18:01:47 +02:00
I will assign your pull request to a [milestone ](https://github.com/louislam/uptime-kuma/milestones ), if I plan to review and merge it.
2022-09-19 13:56:30 +02:00
2023-08-24 18:01:47 +02:00
Also, please don't rush or ask for an ETA, because I have to understand the pull request, make sure it is no breaking changes and stick to my vision of this project, especially for large pull requests.
2022-06-01 08:08:10 +02:00
2021-10-25 06:06:01 +02:00
### Recommended Pull Request Guideline
2022-04-27 20:18:47 +02:00
Before deep into coding, discussion first is preferred. Creating an empty pull request for discussion would be recommended.
2022-04-12 07:53:52 +02:00
2021-10-25 06:06:01 +02:00
1. Fork the project
2023-11-16 14:31:20 +02:00
2. Clone your fork repo to local
3. Create a new branch
2023-12-03 20:32:11 +02:00
4. Create an empty commit: `git commit -m "<YOUR TASK NAME>" --allow-empty`
2023-11-16 14:31:20 +02:00
5. Push to your fork repo
2023-12-03 20:32:11 +02:00
6. Prepare a pull request: https://github.com/louislam/uptime-kuma/compare
7. Write a proper description. You can mention @louislam in it, so @louislam will get the notification.
8. Create your pull request as a Draft
9. Wait for the discussion
2021-08-24 08:42:35 +02:00
2021-10-13 02:01:34 +02:00
## Project Styles
2021-07-31 18:29:30 +02:00
2023-08-24 18:01:47 +02:00
I personally do not like something that requires so many configurations before you can finally start the app. I hope Uptime Kuma installation will be as easy as like installing a mobile app.
2021-07-31 18:29:30 +02:00
2023-08-24 18:01:47 +02:00
- Easy to install for non-Docker users, no native build dependency is needed (for x86_64/armv7/arm64), no extra config, and no extra effort required to get it running
2021-10-10 08:40:19 +02:00
- Single container for Docker users, no very complex docker-compose file. Just map the volume and expose the port, then good to go
2023-08-24 18:01:47 +02:00
- Settings should be configurable in the frontend. Environment variables are discouraged, unless it is related to startup such as `DATA_DIR`
2021-07-31 18:29:30 +02:00
- Easy to use
2023-02-01 16:39:09 +02:00
- The web UI styling should be consistent and nice
2021-07-31 18:29:30 +02:00
2021-10-13 02:01:34 +02:00
## Coding Styles
2021-08-24 08:06:23 +02:00
2021-10-03 10:04:16 +02:00
- 4 spaces indentation
2021-09-12 19:23:51 +02:00
- Follow `.editorconfig`
- Follow ESLint
2022-04-25 20:20:13 +02:00
- Methods and functions should be documented with JSDoc
2021-08-24 08:06:23 +02:00
2023-02-01 16:39:09 +02:00
## Name Conventions
2021-08-24 08:06:23 +02:00
- Javascript/Typescript: camelCaseType
2022-06-17 09:07:55 +02:00
- SQLite: snake_case (Underscore)
- CSS/SCSS: kebab-case (Dash)
2021-08-24 08:06:23 +02:00
2021-10-13 02:01:34 +02:00
## Tools
2021-09-12 19:23:51 +02:00
2023-08-02 11:30:54 +02:00
- [`Node.js` ](https://nodejs.org/ ) >= 14
- [`npm` ](https://www.npmjs.com/ ) >= 8.5
- [`git` ](https://git-scm.com/ )
- IDE that supports [`ESLint` ](https://eslint.org/ ) and EditorConfig (I am using [`IntelliJ IDEA` ](https://www.jetbrains.com/idea/ ))
2023-08-03 08:09:45 +02:00
- A SQLite GUI tool (f.ex. [`SQLite Expert Personal` ](https://www.sqliteexpert.com/download.html ) or [`DBeaver Community` ](https://dbeaver.io/download/ ))
2021-07-31 18:29:30 +02:00
2023-11-16 14:31:20 +02:00
### GitHub Codespaces
2023-09-21 11:41:46 +02:00
2023-11-16 14:31:20 +02:00
If you don't want to setup an local environment, you can now develop on GitHub Codespaces, read more:
2023-09-21 11:41:46 +02:00
https://github.com/louislam/uptime-kuma/tree/master/.devcontainer
2023-09-10 22:02:26 +02:00
## Git Branches
- `master` : 2.X.X development. If you want to add a new feature, your pull request should base on this.
- `1.23.X` : 1.23.X development. If you want to fix a bug for v1 and v2, your pull request should base on this.
- All other branches are unused, outdated or for dev.
2023-02-01 16:39:09 +02:00
## Install Dependencies for Development
2021-07-31 18:29:30 +02:00
```bash
2021-10-03 10:04:16 +02:00
npm ci
2021-08-31 14:36:17 +02:00
```
2022-04-25 20:20:13 +02:00
## Dev Server
2021-07-31 18:29:30 +02:00
2022-04-25 20:20:13 +02:00
(2022-04-26 Update)
We can start the frontend dev server and the backend dev server in one command.
Port `3000` and port `3001` will be used.
2021-07-31 18:29:30 +02:00
2021-09-23 16:48:19 +02:00
```bash
2022-04-25 20:20:13 +02:00
npm run dev
2021-07-31 18:29:30 +02:00
```
2023-08-24 18:01:47 +02:00
But sometimes, you would like to restart the server, but not the frontend, you can run these commands in two terminals:
2023-10-02 23:48:21 +02:00
```bash
2023-02-01 16:39:09 +02:00
npm run start-frontend-dev
npm run start-server-dev
```
2022-04-25 20:20:13 +02:00
## Backend Server
2021-07-31 18:29:30 +02:00
2022-04-29 05:35:03 +02:00
It binds to `0.0.0.0:3001` by default.
2021-07-31 18:29:30 +02:00
It is mainly a socket.io app + express.js.
2023-10-02 23:48:21 +02:00
express.js is used for:
2022-04-25 20:27:37 +02:00
- entry point such as redirecting to a status page or the dashboard
- serving the frontend built files (index.html, .js and .css etc.)
2023-08-24 18:01:47 +02:00
- serving internal APIs of the status page
2021-07-31 18:29:30 +02:00
2022-04-25 20:20:13 +02:00
### Structure in /server/
2023-02-01 16:39:09 +02:00
- jobs/ (Jobs that are running in another process)
2023-08-24 18:01:47 +02:00
- model/ (Object model, auto-mapping to the database table name)
2021-10-03 10:04:16 +02:00
- modules/ (Modified 3rd-party modules)
2023-02-01 16:39:09 +02:00
- monitor_types (Monitor Types)
2021-11-17 08:09:12 +02:00
- notification-providers/ (individual notification logic)
2021-10-03 10:04:16 +02:00
- routers/ (Express Routers)
2021-12-02 12:15:14 +02:00
- socket-handler (Socket.io Handlers)
2023-02-01 16:39:09 +02:00
- server.js (Server entry point)
- uptime-kuma-server.js (UptimeKumaServer class, main logic should be here, but some still in `server.js` )
2021-07-31 18:29:30 +02:00
2022-04-25 20:20:13 +02:00
## Frontend Dev Server
2021-10-13 02:01:34 +02:00
2023-10-02 23:48:21 +02:00
It binds to `0.0.0.0:3000` by default. The frontend dev server is used for development only.
2021-10-13 02:01:34 +02:00
2023-10-02 23:48:21 +02:00
For production, it is not used. It will be compiled to `dist` directory instead.
2021-07-31 18:29:30 +02:00
2021-09-12 19:23:51 +02:00
You can use Vue.js devtools Chrome extension for debugging.
2021-07-31 18:29:30 +02:00
2021-10-13 02:01:34 +02:00
### Build the frontend
2021-07-31 18:29:30 +02:00
```bash
npm run build
```
2021-10-13 02:01:34 +02:00
### Frontend Details
2021-07-31 18:29:30 +02:00
Uptime Kuma Frontend is a single page application (SPA). Most paths are handled by Vue Router.
2021-09-12 19:23:51 +02:00
The router is in `src/router.js`
2021-07-31 18:29:30 +02:00
2023-08-24 18:01:47 +02:00
As you can see, most data in the frontend is stored at the root level, even though you changed the current router to any other pages.
2021-07-31 18:29:30 +02:00
2021-09-12 19:23:51 +02:00
The data and socket logic are in `src/mixins/socket.js` .
2021-07-31 18:29:30 +02:00
2021-10-13 02:01:34 +02:00
## Database Migration
2021-07-31 18:29:30 +02:00
2023-09-21 11:41:46 +02:00
See: https://github.com/louislam/uptime-kuma/tree/master/db/knex_migrations
2021-07-31 18:29:30 +02:00
2021-10-13 02:01:34 +02:00
## Unit Test
2021-07-31 18:29:30 +02:00
2021-10-13 02:01:34 +02:00
```bash
2021-10-05 14:27:43 +02:00
npm run build
npm test
```
2022-09-19 13:39:30 +02:00
## Dependencies
2022-10-02 13:38:33 +02:00
Both frontend and backend share the same package.json. However, the frontend dependencies are eventually not used in the production environment, because it is usually also baked into dist files. So:
2022-09-19 13:39:30 +02:00
- Frontend dependencies = "devDependencies"
- Examples: vue, chart.js
- Backend dependencies = "dependencies"
- Examples: socket.io, sqlite3
- Development dependencies = "devDependencies"
- Examples: eslint, sass
### Update Dependencies
2021-10-05 12:17:54 +02:00
2023-08-24 18:01:47 +02:00
Since previously updating Vite 2.5.10 to 2.6.0 broke the application completely, from now on, it should update the patch release version only.
2021-10-05 12:17:54 +02:00
2021-10-13 02:01:34 +02:00
Patch release = the third digit ([Semantic Versioning](https://semver.org/))
2021-10-06 09:36:45 +02:00
2023-08-12 16:28:12 +02:00
If for security / bug / other reasons, a library must be updated, breaking changes need to be checked by the person proposing the change.
2023-02-01 16:39:09 +02:00
2021-10-13 02:01:34 +02:00
## Translations
2021-10-06 09:36:45 +02:00
2023-11-16 14:31:20 +02:00
Please add **all** the strings which are translatable to `src/lang/en.json` (if translation keys are omitted, they can not be translated.)
2023-08-02 11:30:54 +02:00
2023-11-16 14:31:20 +02:00
**Don't include any other languages in your initial pull request** (even if this is your mother tongue), to avoid merge-conflicts between weblate and `master` .
2023-08-24 18:01:47 +02:00
The translations can then (after merging a PR into `master` ) be translated by awesome people donating their language skills.
2023-08-02 11:30:54 +02:00
If you want to help by translating Uptime Kuma into your language, please visit the [instructions on how to translate using weblate ](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md ).
## Spelling & Grammar
Feel free to correct the grammar in the documentation or code.
2023-08-24 18:01:47 +02:00
My mother language is not English and my grammar is not that great.
2021-10-20 18:03:55 +02:00
2021-10-26 17:56:14 +02:00
## Wiki
2023-11-16 14:31:20 +02:00
Since there is no way to make a pull request to the wiki, I have set up another repo to do that.
2021-10-26 17:56:14 +02:00
2021-10-26 18:02:20 +02:00
https://github.com/louislam/uptime-kuma-wiki
2021-10-26 17:56:14 +02:00
2023-09-10 22:02:26 +02:00
## Docker
2023-10-02 23:48:21 +02:00
### Arch
2023-09-10 22:02:26 +02:00
- amd64
- arm64
- armv7
### Docker Tags
#### v2
- `2` , `latest-2` : v2 with full features such as Chromium and bundled MariaDB
- `2.x.x`
- `2-slim` : v2 with basic features
- `2.x.x-slim`
- `beta2` : Latest beta build
- `2.x.x-beta.x`
- `nightly2` : Dev build
- `base2` : Basic Debian setup without Uptime Kuma source code (Full features)
- `base2-slim` : Basic Debian setup without Uptime Kuma source code
- `pr-test2` : For testing pull request without setting up a local environment
#### v1
- `1` , `latest` , `1-debian` , `debian` : Latest version of v1
- `1.x.x` , `1.x.x-debian`
- `1.x.x-beta.x` : Beta build
- `beta` : Latest beta build
- `nightly` : Dev build
- `base-debian` : Basic Debian setup without Uptime Kuma source code
- `pr-test` : For testing pull request without setting up a local environment
- `base-alpine` : (Deprecated) Basic Alpine setup without Uptime Kuma source code
- `1-alpine` , `alpine` : (Deprecated)
- `1.x.x-alpine` : (Deprecated)
2021-12-02 12:15:14 +02:00
## Maintainer
2021-10-20 18:03:55 +02:00
2021-10-20 18:08:46 +02:00
Check the latest issues and pull requests:
2021-10-20 18:03:55 +02:00
https://github.com/louislam/uptime-kuma/issues?q=sort%3Aupdated-desc
### Release Procedures
2021-12-02 12:15:14 +02:00
2021-10-20 18:03:55 +02:00
1. Draft a release note
2022-03-22 10:45:07 +02:00
2. Make sure the repo is cleared
2023-02-21 09:45:18 +02:00
3. If the healthcheck is updated, remember to re-compile it: `npm run build-docker-builder-go`
2023-10-02 23:48:21 +02:00
4. `npm run release-final` with env vars: `VERSION` and `GITHUB_TOKEN`
5. Wait until the `Press any key to continue`
6. `git push`
7. Publish the release note as 1.X.X
8. Press any key to continue
9. Deploy to the demo server: `npm run deploy-demo-server`
2021-10-20 18:08:46 +02:00
Checking:
2021-12-02 12:15:14 +02:00
2021-10-20 18:08:46 +02:00
- Check all tags is fine on https://hub.docker.com/r/louislam/uptime-kuma/tags
- Try the Docker image with tag 1.X.X (Clean install / amd64 / arm64 / armv7)
2021-12-02 12:15:14 +02:00
- Try clean installation with Node.js
2021-10-26 17:56:14 +02:00
2022-03-20 05:08:33 +02:00
### Release Beta Procedures
1. Draft a release note, check "This is a pre-release"
2. Make sure the repo is cleared
3. `npm run release-beta` with env vars: `VERSION` and `GITHUB_TOKEN`
2022-03-22 10:45:07 +02:00
4. Wait until the `Press any key to continue`
2022-03-20 05:08:33 +02:00
5. Publish the release note as 1.X.X-beta.X
6. Press any key to continue
2021-10-26 17:56:14 +02:00
### Release Wiki
#### Setup Repo
2021-12-02 12:15:14 +02:00
```bash
2021-10-26 17:56:14 +02:00
git clone https://github.com/louislam/uptime-kuma-wiki.git
cd uptime-kuma-wiki
git remote add production https://github.com/louislam/uptime-kuma.wiki.git
```
#### Push to Production Wiki
2021-12-02 12:15:14 +02:00
```bash
2021-10-26 17:56:14 +02:00
git pull
git push production master
```
2023-09-07 10:35:15 +02:00
## Useful Commands
Change the base of a pull request such as `master` to `1.23.X`
2023-10-02 23:48:21 +02:00
```bash
2023-09-07 10:35:15 +02:00
git rebase --onto < new parent > < old parent >
```