diff --git a/docs/diagrams/Bluewave Uptime Auth Flow.pdf b/docs/diagrams/Bluewave Uptime Auth Flow.pdf new file mode 100644 index 000000000..d7c7b45ca Binary files /dev/null and b/docs/diagrams/Bluewave Uptime Auth Flow.pdf differ diff --git a/docs/diagrams/Bluewave Uptime Auth Flow.png b/docs/diagrams/Bluewave Uptime Auth Flow.png new file mode 100644 index 000000000..32498b3b4 Binary files /dev/null and b/docs/diagrams/Bluewave Uptime Auth Flow.png differ diff --git a/docs/diagrams/Bluewave Uptime High Level Overview.pdf b/docs/diagrams/Bluewave Uptime High Level Overview.pdf new file mode 100644 index 000000000..1409d10fb Binary files /dev/null and b/docs/diagrams/Bluewave Uptime High Level Overview.pdf differ diff --git a/docs/diagrams/Bluewave Uptime High Level Overview.png b/docs/diagrams/Bluewave Uptime High Level Overview.png new file mode 100644 index 000000000..65a2866b7 Binary files /dev/null and b/docs/diagrams/Bluewave Uptime High Level Overview.png differ diff --git a/docs/diagrams/Bluewave Uptime JobQueue Flow.pdf b/docs/diagrams/Bluewave Uptime JobQueue Flow.pdf new file mode 100644 index 000000000..e39825f43 Binary files /dev/null and b/docs/diagrams/Bluewave Uptime JobQueue Flow.pdf differ diff --git a/docs/diagrams/Bluewave Uptime JobQueue Flow.png b/docs/diagrams/Bluewave Uptime JobQueue Flow.png new file mode 100644 index 000000000..8794017f0 Binary files /dev/null and b/docs/diagrams/Bluewave Uptime JobQueue Flow.png differ diff --git a/docs/diagrams/Bluewave Uptime Monitor Flow.pdf b/docs/diagrams/Bluewave Uptime Monitor Flow.pdf new file mode 100644 index 000000000..97d56d781 Binary files /dev/null and b/docs/diagrams/Bluewave Uptime Monitor Flow.pdf differ diff --git a/docs/diagrams/Bluewave Uptime Monitor Flow.png b/docs/diagrams/Bluewave Uptime Monitor Flow.png new file mode 100644 index 000000000..5cfc8bca8 Binary files /dev/null and b/docs/diagrams/Bluewave Uptime Monitor Flow.png differ diff --git a/docs/guides/placeholder.md b/docs/guides/placeholder.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 000000000..225f4fdb5 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,181 @@ +--- +icon: sign-posts-wrench +--- + +# Installing Uptime Manager + +## Quickstart for users (quick method) + +1. Download our [Docker compose file](https://github.com/bluewave-labs/bluewave-uptime/blob/develop/Docker/dist/docker-compose.yaml) +2. Run `docker compose up` to start the application +3. Now the application is running at `http://localhost` + +--- + +## Quickstart for developers + +{% hint style="info" %} +Make sure you change the directory to the specified directories, as paths in commands are relative. +{% endhint %} + +### Cloning and initial setup + +1. Clone this repository. +2. Checkout the `develop` branch `git checkout develop` + +### Setting up Docker images + +3. Change directory to the `Docker/dev` directory +4. Build the docker images by running the `build_images.sh` script +5. Run `docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis` +6. Run `docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo` + +### Server setup + +6. CD to `Server` directory, and run `npm install` +7. While in `Server` directory, create a `.env` file with the [required environmental variables](#env-vars-server) +8. While in the `Server` directory, run `npm run dev` + +### Client setup + +9. CD to `Client` directory `run npm install` +10. While in the `Client` directory, create a `.env` file with the [required environmental variables](#env-vars-client) +11. While in the `Client` directory run `npm run dev` + +### Access the application + +12. Client is now running at `localhost:5173` +13. Server is now running at `localhost:5000` + +--- + +## Manual installation + +### Client installation + +1. Change directory to the `Client` directory +2. Install all dependencies by running `npm install` +3. Add a `.env` file to the `Client` directory with the following options: + +#### Environment variables + +| ENV Variable Name | Required/Optional | Type | Description | Accepted Values | +| --------------------- | ----------------- | --------- | ------------------ | ---------------------------------- | +| VITE_APP_API_BASE_URL | Required | `string` | Base URL of server | {host}/api/v1 | +| VITE_APP_LOG_LEVEL | Optional | `string` | Log level | `"none"`\|`"error"` \| `"warn"` \| | +| VITE_APP_DEMO | Optional | `boolean` | Demo server or not | `true`\|`false` \| | + +#### Starting the Client development server + +1. Run `npm run dev` to start the development server. + +### Server Installation + +1. Change the directory to the `Server` directory +2. Install all dependencies by running `npm install` +3. Add a `.env` file to the `Server` directory with the following options: + +#### Environment variables + +Configure the server with the following environmental variables: + +
ENV Variable NameRequired/OptionalTypeDescriptionAccepted Values
CLIENT_HOSTRequiredstringFrontend Host
JWT_SECRETRequiredstringJWT secret
DB_TYPEOptionalstringSpecify DB to useMongoDB | FakeDB
DB_CONNECTION_STRINGRequiredstringSpecifies URL for MongoDB Database
PORTOptionalintegerSpecifies Port for Server
LOGIN_PAGE_URLRequiredstringLogin url to be used in emailing service
REDIS_HOSTRequiredstringHost address for Redis database
REDIS_PORTRequiredintegerPort for Redis database
TOKEN_TTLOptionalstringTime for token to liveIn vercel/ms format https://github.com/vercel/ms
PAGESPEED_API_KEYOptionalstringAPI Key for PageSpeed requests
SYSTEM_EMAIL_HOSTRequiredstringHost to send System Emails From
SYSTEM_EMAIL_PORTRequirednumberPort for System Email Host
SYSTEM_EMAIL_ADDRESSRequiredstringSystem Email Address
SYSTEM_EMAIL_PASSWORDRequiredstringSystem Email Password
+ +--- + +#### Databases + +This project requires two databases: + +1. **Main application database:** The project uses MongoDB for its primary database, with a MongoDB Docker image provided for easy setup. +2. **Redis for queue management:** A Redis database is used for the PingService’s queue system, and a Redis Docker image is included for deployment. + +You may use the included Dockerfiles to spin up databases quickly if you wish. + +**(Optional) Dockerised databases** + +Dockerfiles for the server and databases are located in the `Docker` directory + +
+ +MongoDB Image + +Location: `Docker/mongoDB.Dockerfile` + +The `Docker/mongo/data` directory should be mounted to the MongoDB container in order to persist data. + +From the `Docker` directory run + +1. Build the image: `docker build -f mongoDB.Dockerfile -t uptime_database_mongo .` +2. Run the docker image: `docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo` + +
+ +
+ +Redis Image + +Location `Docker/redis.Dockerfile` + +the `Docker/redis/data` directory should be mounted to the Redis container in order to persist data. + +From the `Docker` directory run + +1. Build the image: `docker build -f redis.Dockerfile -t uptime_redis .` +2. Run the image: `docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis` + +
+ +--- + +#### Starting the development derver + +- run `npm run dev` to start the development server + +or, + +- run `node index.js` to start server + +--- + +### API documentation + +Our API is documented in accordance with the [OpenAPI spec](https://www.openapis.org/). + +You can see the documentation on your local development server at http://localhost:{port}/api-docs + +You can also view the documentation on our demo server at [https://uptime-demo.bluewavelabs.ca/api-docs](https://uptime-demo.bluewavelabs.ca/api-docs) + +### Error handling + +Errors are returned in a standard format: + +`{"success": false, "msg": "No token provided"}` + +Errors are handled by error handling middleware and should be thrown with the following parameters + +| Name | Type | Default | Notes | +| ------- | --------- | ---------------------- | ------------------------------------ | +| status | `integer` | 500 | Standard HTTP codes | +| message | `string` | "Something went wrong" | An error message | +| service | `string` | "Unknown Service" | Name of service that threw the error | + +Example: + +``` +const myRoute = async(req, res, next) => { + try{ + const result = myRiskyOperationHere(); + } + catch(error){ + error.status = 404 + error.message = "Resource not found" + error.service = service name + next(error) + return; + } +} + +``` + +Errors should not be handled at the controller level and should be left to the middleware to handle. diff --git a/docs/users-guide/quickstart.md b/docs/users-guide/quickstart.md new file mode 100644 index 000000000..225f4fdb5 --- /dev/null +++ b/docs/users-guide/quickstart.md @@ -0,0 +1,181 @@ +--- +icon: sign-posts-wrench +--- + +# Installing Uptime Manager + +## Quickstart for users (quick method) + +1. Download our [Docker compose file](https://github.com/bluewave-labs/bluewave-uptime/blob/develop/Docker/dist/docker-compose.yaml) +2. Run `docker compose up` to start the application +3. Now the application is running at `http://localhost` + +--- + +## Quickstart for developers + +{% hint style="info" %} +Make sure you change the directory to the specified directories, as paths in commands are relative. +{% endhint %} + +### Cloning and initial setup + +1. Clone this repository. +2. Checkout the `develop` branch `git checkout develop` + +### Setting up Docker images + +3. Change directory to the `Docker/dev` directory +4. Build the docker images by running the `build_images.sh` script +5. Run `docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis` +6. Run `docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo` + +### Server setup + +6. CD to `Server` directory, and run `npm install` +7. While in `Server` directory, create a `.env` file with the [required environmental variables](#env-vars-server) +8. While in the `Server` directory, run `npm run dev` + +### Client setup + +9. CD to `Client` directory `run npm install` +10. While in the `Client` directory, create a `.env` file with the [required environmental variables](#env-vars-client) +11. While in the `Client` directory run `npm run dev` + +### Access the application + +12. Client is now running at `localhost:5173` +13. Server is now running at `localhost:5000` + +--- + +## Manual installation + +### Client installation + +1. Change directory to the `Client` directory +2. Install all dependencies by running `npm install` +3. Add a `.env` file to the `Client` directory with the following options: + +#### Environment variables + +| ENV Variable Name | Required/Optional | Type | Description | Accepted Values | +| --------------------- | ----------------- | --------- | ------------------ | ---------------------------------- | +| VITE_APP_API_BASE_URL | Required | `string` | Base URL of server | {host}/api/v1 | +| VITE_APP_LOG_LEVEL | Optional | `string` | Log level | `"none"`\|`"error"` \| `"warn"` \| | +| VITE_APP_DEMO | Optional | `boolean` | Demo server or not | `true`\|`false` \| | + +#### Starting the Client development server + +1. Run `npm run dev` to start the development server. + +### Server Installation + +1. Change the directory to the `Server` directory +2. Install all dependencies by running `npm install` +3. Add a `.env` file to the `Server` directory with the following options: + +#### Environment variables + +Configure the server with the following environmental variables: + +
ENV Variable NameRequired/OptionalTypeDescriptionAccepted Values
CLIENT_HOSTRequiredstringFrontend Host
JWT_SECRETRequiredstringJWT secret
DB_TYPEOptionalstringSpecify DB to useMongoDB | FakeDB
DB_CONNECTION_STRINGRequiredstringSpecifies URL for MongoDB Database
PORTOptionalintegerSpecifies Port for Server
LOGIN_PAGE_URLRequiredstringLogin url to be used in emailing service
REDIS_HOSTRequiredstringHost address for Redis database
REDIS_PORTRequiredintegerPort for Redis database
TOKEN_TTLOptionalstringTime for token to liveIn vercel/ms format https://github.com/vercel/ms
PAGESPEED_API_KEYOptionalstringAPI Key for PageSpeed requests
SYSTEM_EMAIL_HOSTRequiredstringHost to send System Emails From
SYSTEM_EMAIL_PORTRequirednumberPort for System Email Host
SYSTEM_EMAIL_ADDRESSRequiredstringSystem Email Address
SYSTEM_EMAIL_PASSWORDRequiredstringSystem Email Password
+ +--- + +#### Databases + +This project requires two databases: + +1. **Main application database:** The project uses MongoDB for its primary database, with a MongoDB Docker image provided for easy setup. +2. **Redis for queue management:** A Redis database is used for the PingService’s queue system, and a Redis Docker image is included for deployment. + +You may use the included Dockerfiles to spin up databases quickly if you wish. + +**(Optional) Dockerised databases** + +Dockerfiles for the server and databases are located in the `Docker` directory + +
+ +MongoDB Image + +Location: `Docker/mongoDB.Dockerfile` + +The `Docker/mongo/data` directory should be mounted to the MongoDB container in order to persist data. + +From the `Docker` directory run + +1. Build the image: `docker build -f mongoDB.Dockerfile -t uptime_database_mongo .` +2. Run the docker image: `docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo` + +
+ +
+ +Redis Image + +Location `Docker/redis.Dockerfile` + +the `Docker/redis/data` directory should be mounted to the Redis container in order to persist data. + +From the `Docker` directory run + +1. Build the image: `docker build -f redis.Dockerfile -t uptime_redis .` +2. Run the image: `docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis` + +
+ +--- + +#### Starting the development derver + +- run `npm run dev` to start the development server + +or, + +- run `node index.js` to start server + +--- + +### API documentation + +Our API is documented in accordance with the [OpenAPI spec](https://www.openapis.org/). + +You can see the documentation on your local development server at http://localhost:{port}/api-docs + +You can also view the documentation on our demo server at [https://uptime-demo.bluewavelabs.ca/api-docs](https://uptime-demo.bluewavelabs.ca/api-docs) + +### Error handling + +Errors are returned in a standard format: + +`{"success": false, "msg": "No token provided"}` + +Errors are handled by error handling middleware and should be thrown with the following parameters + +| Name | Type | Default | Notes | +| ------- | --------- | ---------------------- | ------------------------------------ | +| status | `integer` | 500 | Standard HTTP codes | +| message | `string` | "Something went wrong" | An error message | +| service | `string` | "Unknown Service" | Name of service that threw the error | + +Example: + +``` +const myRoute = async(req, res, next) => { + try{ + const result = myRiskyOperationHere(); + } + catch(error){ + error.status = 404 + error.message = "Resource not found" + error.service = service name + next(error) + return; + } +} + +``` + +Errors should not be handled at the controller level and should be left to the middleware to handle. diff --git a/guides/.gitbook/assets/Group 3763.png b/guides/.gitbook/assets/Group 3763.png new file mode 100644 index 000000000..69315f901 Binary files /dev/null and b/guides/.gitbook/assets/Group 3763.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-03 at 10.56.43 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-03 at 10.56.43 PM.png new file mode 100644 index 000000000..8122daeff Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-03 at 10.56.43 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-03 at 10.57.45 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-03 at 10.57.45 PM.png new file mode 100644 index 000000000..adba3441c Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-03 at 10.57.45 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.37.47 PM (1).png b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.37.47 PM (1).png new file mode 100644 index 000000000..9e1a89220 Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.37.47 PM (1).png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.37.47 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.37.47 PM.png new file mode 100644 index 000000000..9e1a89220 Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.37.47 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.41.55 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.41.55 PM.png new file mode 100644 index 000000000..67e393e65 Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.41.55 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.47.41 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.47.41 PM.png new file mode 100644 index 000000000..c6b753997 Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.47.41 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.54.31 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.54.31 PM.png new file mode 100644 index 000000000..2876829c2 Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-03 at 11.54.31 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.13.55 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.13.55 PM.png new file mode 100644 index 000000000..3aa75364f Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.13.55 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.14.45 AM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.14.45 AM.png new file mode 100644 index 000000000..ab870889f Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.14.45 AM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.16.53 AM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.16.53 AM.png new file mode 100644 index 000000000..92db7ba1a Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.16.53 AM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.17.44 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.17.44 PM.png new file mode 100644 index 000000000..195582c2c Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.17.44 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.17.57 AM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.17.57 AM.png new file mode 100644 index 000000000..ecc25d6cc Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.17.57 AM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.20.52 PM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.20.52 PM.png new file mode 100644 index 000000000..46cd17854 Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 12.20.52 PM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 9.28.27 AM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 9.28.27 AM.png new file mode 100644 index 000000000..97a73e3a8 Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 9.28.27 AM.png differ diff --git a/guides/.gitbook/assets/Screenshot 2024-10-04 at 9.30.30 AM.png b/guides/.gitbook/assets/Screenshot 2024-10-04 at 9.30.30 AM.png new file mode 100644 index 000000000..94e872cdb Binary files /dev/null and b/guides/.gitbook/assets/Screenshot 2024-10-04 at 9.30.30 AM.png differ diff --git a/guides/README.md b/guides/README.md new file mode 100644 index 000000000..3de3c7e59 --- /dev/null +++ b/guides/README.md @@ -0,0 +1,63 @@ +--- +icon: hand-wave +cover: .gitbook/assets/Group 3763.png +coverY: 0 +layout: + cover: + visible: true + size: full + title: + visible: true + description: + visible: false + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true +--- + +# Welcome to Uptime Manager + +BlueWave Uptime Manager is an open-source server monitoring application used to track the operational status and performance of servers and websites. + +It regularly checks whether a server/website is accessible and performs optimally, providing real-time alerts and reports on the monitored services' availability, downtime, and response time. + +## Demo + +We have a [demo](https://uptime-demo.bluewavelabs.ca/) where you can test how the Uptime Manager works. The username is [uptimedemo@demo.com](mailto:uptimedemo@demo.com) and the password is Demouser1! + +## Questions & ideas + +If you have a question, head over to GitHub's [discussions](https://github.com/bluewave-labs/bluewave-uptime/discussions) page. + +## Features + +* [x] Completely open source, deployable on your servers +* [x] Website monitoring +* [x] Port monitoring +* [x] Ping monitoring +* [x] Incidents at a glance +* [x] Page speed monitoring +* [x] E-mail notifications +* [ ] Scheduled maintenance (in the works) + +## **Roadmap (short term)** + +* [ ] Memory, disk and CPU monitoring +* [ ] 3rd party integrations +* [ ] DNS monitoring +* [ ] SSL monitoring + +## **Roadmap (long term)** + +* [ ] Status pages + +## Tech stack + +* [ReactJs](https://react.dev/) +* [MUI (React framework)](https://mui.com/) +* [Node.js](https://nodejs.org/en) +* [MongoDB](https://mongodb.com) + diff --git a/guides/SUMMARY.md b/guides/SUMMARY.md new file mode 100644 index 000000000..beed0694d --- /dev/null +++ b/guides/SUMMARY.md @@ -0,0 +1,19 @@ +# Table of contents + +* [Welcome to Uptime Manager](README.md) + +## USER'S GUIDE + +* [Installing Uptime Manager](users-guide/quickstart.md) +* [Using Uptime Manager](users-guide/using-uptime-manager.md) +* [Creating a new monitor](users-guide/creating-a-new-monitor.md) +* [Pagespeed monitoring](users-guide/pagespeed-monitoring.md) +* [Incidents page](users-guide/incidents-page.md) +* [Server settings](users-guide/server-settings.md) +* [User settings](users-guide/user-settings.md) + +## DEVELOPER'S GUIDE + +* [Contributing to the code](developers-guide/contributing-to-the-code.md) +* [General project structure](developers-guide/general-project-structure.md) +* [High level overview](developers-guide/high-level-overview.md) diff --git a/guides/developers-guide/contributing-to-the-code.md b/guides/developers-guide/contributing-to-the-code.md new file mode 100644 index 000000000..483d5c85c --- /dev/null +++ b/guides/developers-guide/contributing-to-the-code.md @@ -0,0 +1,18 @@ +--- +icon: list-check +--- + +# Contributing to the code + +We generally follow the [gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) workflow model. If you’re not familiar with it, the general steps are + +1. Create a feature branch in your local depository and make your changes. +2. Push your branch to the remote repository on Github. +3. Open a pull request. +4. The rest of the team will review the pull request and either approve or request changes. +5. If changes are requested, make changes and push. +6. Project maintainer will merge the branch, closing the pull request and deleting the remote branch. + +### Git + +If you are inexperienced with Git or need a refresher please visit our [Git Quick Start Guide](https://github.com/ajhollid/bluewave\_collaborative\_git) to help get up to speed. If you’d like to go further in depth, this [Git for Professionals](https://youtu.be/Uszj\_k0DGsg?si=6rOWEQOMxmwhnb-K) is a good resource.\ diff --git a/guides/developers-guide/general-project-structure.md b/guides/developers-guide/general-project-structure.md new file mode 100644 index 000000000..da274f0f7 --- /dev/null +++ b/guides/developers-guide/general-project-structure.md @@ -0,0 +1,48 @@ +--- +icon: diagram-project +--- + +# General project structure + +The Uptime Manager product uses the MERN stack, which is to say that the project uses: + +* React on the Front End via Vite +* Express on the Back End via NodeJS +* MongoDB for data with Mongoose for data access + +### Front end + +The project uses the [Material UI Components](https://mui.com/material-ui/all-components/) (MUI) which allows us to build with a minimum of fuss. The library is highly customisable and the project makes heavy use of the Theme concept and follows MUI’s paradigm to avoid writing excessive CSS.\ +\ +The overriding goal on the Front Eed is to write maintainable and scalable code. If you find yourself writing lots of CSS to customize a component or are having to set a value often like font size or color you probably should be using the theme.\ +\ +When making changes to the Front end please always keep future developers in mind. Will they know how to make changes to your code? Is your code modular? If a dev makes changes elsewhere in the app will your component be affected? If the team makes a theme change like font size or primary color will your component be updated as well? + +### Back end + +The back end of this project is not especially complex and is built around Express. The back end is a RESTful API and the [documentation can be found here](https://uptime-demo.bluewavelabs.ca/api-docs). + +The application consists of several main conceptual models: + +1. User +2. Monitor +3. Check +4. Notification + +There are several supporting models as well. + +1. AppSettings +2. InviteToken +3. Team + +All requests are based around these models and manipulation of their data.\ +\ +In general the models interact in this fashion: + +* A `User` has many `Monitors` +* A `Monitor` has many `Checks` +* A `Monitor` has many `Notifications` + +A `User` can create a `Monitor`. `Monitors` are enqueued in the `JobQueue`, and their target URLs are queried when they are dequeued. When the query is complete, a `Check` is created that records information about the request.\ +\ +A `User` may attach a `Notification` to their `Monitor`, if the `Monitor`’s status changes then the user will be notified by the method specified in the `Notification` diff --git a/guides/developers-guide/high-level-overview.md b/guides/developers-guide/high-level-overview.md new file mode 100644 index 000000000..409d9621d --- /dev/null +++ b/guides/developers-guide/high-level-overview.md @@ -0,0 +1,57 @@ +--- +icon: dove +--- + +# High level overview + + + +The figure below shows a high level architecture of the Uptime Manager. + +
+ +### Typical auth request overview + +The following diagram describes a typical request to the /auth endpoints. + +
+ +### Typical monitor request overview + +The following diagram describes a typical request to the `/monitors` endpoints. + +
+ +### JobQueue + +The heart of this application is a `JobQueue` class that wraps a BullMQ `Queue`. \ +\ +A `Monitor` is considered a job, when one is created it is enqueued in the `JobQueue`.\ +\ +Jobs are handled by a pool of workers in the `JobQueue` and their tasks are executed in the order in which they are enqueued.\ +\ +Workers are scaled up and down based on the jobs/worker ratio as jobs are enqueued and dequeued. + +#### **High level overview of the JobQueue** + +
+ +### SSL + +SSL is handled by LetsEncrypt and Certbot. This works by Nginx and Certbot sharing the same volume where the certificates are held. The following snippet from the docker-compose.yaml file shows how this works.\ + + +
+ +Please see [this guide](https://phoenixnap.com/kb/letsencrypt-docker) for more information on this setup. + +\ +\ +\ + + +\ +\ + + +\ diff --git a/guides/users-guide/creating-a-new-monitor.md b/guides/users-guide/creating-a-new-monitor.md new file mode 100644 index 000000000..5784d1f41 --- /dev/null +++ b/guides/users-guide/creating-a-new-monitor.md @@ -0,0 +1,31 @@ +--- +icon: plus +--- + +# Creating a new monitor + +Creating a new monitor involves a few steps, mentioned below. + +### General settings + +* **URL to monitor:** Enter the full URL of the website or service you want to monitor. +* **Display name:** Optionally, provide a custom name for your monitor. This helps identify it easily in your dashboard. + +### Checks to perform + +* **Website monitoring:** This option uses HTTP(s) to monitor your website or API endpoint. You can choose between HTTPS and HTTP protocols. +* **Ping monitoring:** Checks whether your server is available. This option is currently unselected. + +### Incident notifications + +When there's a new incident, you can choose how to be notified: + +* Notify via SMS (coming soon) +* Notify via email (to the email address you logged in with) +* Notify via email to multiple addresses (coming soon) + +### Advanced settings + +* **Check frequency:** Set how often the system should check your monitor. The current setting is 1 minute. + +After configuring all settings, click the "Create monitor" button at the bottom right to set up your new monitor. diff --git a/guides/users-guide/incidents-page.md b/guides/users-guide/incidents-page.md new file mode 100644 index 000000000..988290d37 --- /dev/null +++ b/guides/users-guide/incidents-page.md @@ -0,0 +1,13 @@ +--- +icon: brake-warning +--- + +# Incidents page + +This page shows a list of incidents of all the servers you monitor. + +
+ +Page includes a table where Monitor name, Status (down or cannot resolve), date and time of the incident, status code and corresponding message is shown. + +By default, the page shows all incidents from all servers. There is also a dropdown button above the table where you can select a server name. diff --git a/guides/users-guide/pagespeed-monitoring.md b/guides/users-guide/pagespeed-monitoring.md new file mode 100644 index 000000000..260e1c30c --- /dev/null +++ b/guides/users-guide/pagespeed-monitoring.md @@ -0,0 +1,89 @@ +--- +icon: gauge-min +--- + +# Pagespeed monitoring + +Under Dashboard > Pagespeed, you can see an overview of pagespeed monitors for different websites. This dashboard helps you view optimal website performance by providing clear, actionable insights into various aspects of your site's speed and user experience. + +
+ +When you add a new page speed monitor, it is added here. Click on the "Create new" button to add a new page speed. + +Here, both monitors are shown as "Live (Collecting Data)" with a green dot, indicating they are actively monitoring. Each monitor has a small graph, representing recent pagespeed performance over time. + +### Details of a pagespeed monitor + +
+ +When you click on a pagespeed card, you'll see an overview of data collected using Google's PageSpeed Monitor API. + +### Score history graph + +Shows performance trends over the past 24 hours. Four colored lines represent different metrics: + +* Accessibility (blue) +* Best Practices (orange) +* Performance (green) +* Search Engine Optimization (purple) + +You can toggle these metrics on/off using the checkboxes on the right + +### Performance report + +You'll see an overall score of your server's pagespeed. + +### Performance metrics + +* **Cumulative Layout Shift:** Measures visual stability +* **Speed Index:** How quickly content is visually displayed +* **First Contentful Paint:** Time until the first content is rendered +* **Largest Contentful Paint:** Time until the largest content element is rendered +* **Total Blocking Time:** Sum of all time periods between FCP and Time to Interactive + +### Creating a new pagespeed + +When you are on a pagespeed screen, click on the "Create pagespeed" button. You'll see a screen similar to this: + +
+ +This page allows you to set up a new pagespeed monitor for your website. Follow these steps to configure your monitor: + +#### General settings + +* **URL to monitor:** Enter the full URL of the website you want to monitor (e.g., [https://google.com](https://google.com)). +* **Display name (optional):** Enter a custom name for your monitor to easily identify it in your dashboard. + +#### Checks to perform + +Here, you can choose between HTTPS (recommended for secure sites) or HTTP protocols. + +#### Incident notifications + +Select how you want to be notified when there's a new incident: + +* Notify via SMS (coming soon) +* Notify via email (to your email address) +* Also notify via email to multiple addresses (coming soon) + +#### Advanced settings + +**Check frequency:** Choose how often you want the system to check your website's pagespeed. The default is set to 3 minutes. + +After configuring all settings, click the "Create monitor" button at the bottom right of the page. + +#### Tips + +* Ensure the URL you enter is correct and accessible. +* Choose a descriptive display name if you're monitoring multiple sites. +* Consider the trade-off between check frequency and resource usage. More frequent checks provide more data but may use more resources. +* Remember to enable your preferred notification methods to stay informed about incidents. + +After creating the monitor, you'll be able to view its performance data in your dashboard. This will help you track your website's pagespeed and optimize its performance over time. + + + + + + + diff --git a/guides/users-guide/quickstart.md b/guides/users-guide/quickstart.md new file mode 100644 index 000000000..225f4fdb5 --- /dev/null +++ b/guides/users-guide/quickstart.md @@ -0,0 +1,181 @@ +--- +icon: sign-posts-wrench +--- + +# Installing Uptime Manager + +## Quickstart for users (quick method) + +1. Download our [Docker compose file](https://github.com/bluewave-labs/bluewave-uptime/blob/develop/Docker/dist/docker-compose.yaml) +2. Run `docker compose up` to start the application +3. Now the application is running at `http://localhost` + +--- + +## Quickstart for developers + +{% hint style="info" %} +Make sure you change the directory to the specified directories, as paths in commands are relative. +{% endhint %} + +### Cloning and initial setup + +1. Clone this repository. +2. Checkout the `develop` branch `git checkout develop` + +### Setting up Docker images + +3. Change directory to the `Docker/dev` directory +4. Build the docker images by running the `build_images.sh` script +5. Run `docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis` +6. Run `docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo` + +### Server setup + +6. CD to `Server` directory, and run `npm install` +7. While in `Server` directory, create a `.env` file with the [required environmental variables](#env-vars-server) +8. While in the `Server` directory, run `npm run dev` + +### Client setup + +9. CD to `Client` directory `run npm install` +10. While in the `Client` directory, create a `.env` file with the [required environmental variables](#env-vars-client) +11. While in the `Client` directory run `npm run dev` + +### Access the application + +12. Client is now running at `localhost:5173` +13. Server is now running at `localhost:5000` + +--- + +## Manual installation + +### Client installation + +1. Change directory to the `Client` directory +2. Install all dependencies by running `npm install` +3. Add a `.env` file to the `Client` directory with the following options: + +#### Environment variables + +| ENV Variable Name | Required/Optional | Type | Description | Accepted Values | +| --------------------- | ----------------- | --------- | ------------------ | ---------------------------------- | +| VITE_APP_API_BASE_URL | Required | `string` | Base URL of server | {host}/api/v1 | +| VITE_APP_LOG_LEVEL | Optional | `string` | Log level | `"none"`\|`"error"` \| `"warn"` \| | +| VITE_APP_DEMO | Optional | `boolean` | Demo server or not | `true`\|`false` \| | + +#### Starting the Client development server + +1. Run `npm run dev` to start the development server. + +### Server Installation + +1. Change the directory to the `Server` directory +2. Install all dependencies by running `npm install` +3. Add a `.env` file to the `Server` directory with the following options: + +#### Environment variables + +Configure the server with the following environmental variables: + +
ENV Variable NameRequired/OptionalTypeDescriptionAccepted Values
CLIENT_HOSTRequiredstringFrontend Host
JWT_SECRETRequiredstringJWT secret
DB_TYPEOptionalstringSpecify DB to useMongoDB | FakeDB
DB_CONNECTION_STRINGRequiredstringSpecifies URL for MongoDB Database
PORTOptionalintegerSpecifies Port for Server
LOGIN_PAGE_URLRequiredstringLogin url to be used in emailing service
REDIS_HOSTRequiredstringHost address for Redis database
REDIS_PORTRequiredintegerPort for Redis database
TOKEN_TTLOptionalstringTime for token to liveIn vercel/ms format https://github.com/vercel/ms
PAGESPEED_API_KEYOptionalstringAPI Key for PageSpeed requests
SYSTEM_EMAIL_HOSTRequiredstringHost to send System Emails From
SYSTEM_EMAIL_PORTRequirednumberPort for System Email Host
SYSTEM_EMAIL_ADDRESSRequiredstringSystem Email Address
SYSTEM_EMAIL_PASSWORDRequiredstringSystem Email Password
+ +--- + +#### Databases + +This project requires two databases: + +1. **Main application database:** The project uses MongoDB for its primary database, with a MongoDB Docker image provided for easy setup. +2. **Redis for queue management:** A Redis database is used for the PingService’s queue system, and a Redis Docker image is included for deployment. + +You may use the included Dockerfiles to spin up databases quickly if you wish. + +**(Optional) Dockerised databases** + +Dockerfiles for the server and databases are located in the `Docker` directory + +
+ +MongoDB Image + +Location: `Docker/mongoDB.Dockerfile` + +The `Docker/mongo/data` directory should be mounted to the MongoDB container in order to persist data. + +From the `Docker` directory run + +1. Build the image: `docker build -f mongoDB.Dockerfile -t uptime_database_mongo .` +2. Run the docker image: `docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo` + +
+ +
+ +Redis Image + +Location `Docker/redis.Dockerfile` + +the `Docker/redis/data` directory should be mounted to the Redis container in order to persist data. + +From the `Docker` directory run + +1. Build the image: `docker build -f redis.Dockerfile -t uptime_redis .` +2. Run the image: `docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis` + +
+ +--- + +#### Starting the development derver + +- run `npm run dev` to start the development server + +or, + +- run `node index.js` to start server + +--- + +### API documentation + +Our API is documented in accordance with the [OpenAPI spec](https://www.openapis.org/). + +You can see the documentation on your local development server at http://localhost:{port}/api-docs + +You can also view the documentation on our demo server at [https://uptime-demo.bluewavelabs.ca/api-docs](https://uptime-demo.bluewavelabs.ca/api-docs) + +### Error handling + +Errors are returned in a standard format: + +`{"success": false, "msg": "No token provided"}` + +Errors are handled by error handling middleware and should be thrown with the following parameters + +| Name | Type | Default | Notes | +| ------- | --------- | ---------------------- | ------------------------------------ | +| status | `integer` | 500 | Standard HTTP codes | +| message | `string` | "Something went wrong" | An error message | +| service | `string` | "Unknown Service" | Name of service that threw the error | + +Example: + +``` +const myRoute = async(req, res, next) => { + try{ + const result = myRiskyOperationHere(); + } + catch(error){ + error.status = 404 + error.message = "Resource not found" + error.service = service name + next(error) + return; + } +} + +``` + +Errors should not be handled at the controller level and should be left to the middleware to handle. diff --git a/guides/users-guide/server-settings.md b/guides/users-guide/server-settings.md new file mode 100644 index 000000000..6276f3c42 --- /dev/null +++ b/guides/users-guide/server-settings.md @@ -0,0 +1,35 @@ +--- +icon: screwdriver-wrench +--- + +# Server settings + +Under the Settings page, you can configure the server's behaviour. + +### General settings + +Display timezone: The timezone of the dashboard you publicly display. + +### History and monitoring + +Define here for how long you want to keep the data. You can also remove all past data. You can also clear all stats. This is irreversible. + +### Demo monitors + +Here you can add and remove demo monitors. It will load roughly 300 demo monitors at the same time so you can test your server. + +### Advanced settings + +Here you can setup the following: + +**Client settings:** The URL of the APIs and debug level. The more verbose the debug level, the more log is written on the server. + +**Email settings:** Set your host email settings here. These settings are used for sending system emails. + +Server settings: Several server settings can be done here. Alternatively, you can add a pagespeed API key to bypass Google's limitations (albeit they are generous about it) + + + + + +\ diff --git a/guides/users-guide/user-settings.md b/guides/users-guide/user-settings.md new file mode 100644 index 000000000..f6ebc7a9e --- /dev/null +++ b/guides/users-guide/user-settings.md @@ -0,0 +1,45 @@ +--- +icon: user-pen +--- + +# User settings + +This screen allows you to manage your personal information and account settings within the application. + +### Profile section + +
+ +Enter your first name, last name and email here. You can also upload or delete a profile photo. If you want to delete an account, this can also be done here. Note that that this is irreversible and cannot be undone. + +### Password section + +This screen allows you to update your password for your account. + +
+ +In order to change your password, you need to enter your password, and the new password twice. The new password must meet the specified criteria (e.g., minimum length, uppercase letter, number, symbol). + +**Additional notes:** + +* Your new password will take effect immediately. +* For security reasons, it is recommended to choose a strong password that is difficult to guess. + +### Team section + +This screen allows you to manage your team members within the application. + +
+ +Here you can see a list of all users in your system. A user can be either admin or a member, where an admin can create or delete a monitor, and a user can only view them. + +To invite a team member, + +* Click the "Invite a team member" button. +* Enter the email address of the person you want to invite. +* Select their desired role (Administrator or Member). +* Click "Invite" to send the invitation. + +The invited team member will receive an email invitation to join your team. + +Admin also has the option to edit or remove existing team members. diff --git a/guides/users-guide/using-uptime-manager.md b/guides/users-guide/using-uptime-manager.md new file mode 100644 index 000000000..0b0071bae --- /dev/null +++ b/guides/users-guide/using-uptime-manager.md @@ -0,0 +1,80 @@ +--- +icon: computer-mouse +description: >- + This user guide helps new users navigate and understand the Uptime Manager + dashboard layout and functionality. +--- + +# Using Uptime Manager + +## **General Overview** + +The Uptime Manager is an open-source server monitoring tool designed to track the uptime, downtime, and performance of servers, websites, or web applications. + +It provides real-time alerts, status updates, and detailed response time metrics. + +### **Sidebar menu** + +The sidebar on the left contains the following sections: + +* **Dashboard**: The main section that shows an overview of your monitored services, including their status and performance. It includes "Monitors" and "Pagespeed" +* **Incidents**: A section where alerts and incidents regarding the monitored services are logged. This helps users investigate issues and track downtime history. +* **Account**: User-related settings and account information are accessible here. +* **Support**: Links to customer support or documentation to help troubleshoot or ask for assistance. +* **Settings**: Provides customization options for the application’s behavior, monitoring frequency, and notification preferences. + +**User info section** + +At the bottom of the sidebar, you’ll see the current logged-in user alongside with the role. + +### **Dashboard content** + +The main section of the dashboard displays an overview of the monitored services, including their current status and key performance indicators. + +The dashboard offers a summary of your uptime monitors: + +* **Up**: The number of monitored services that are currently operational. +* **Down**: The number of monitored services that are currently experiencing issues. +* **Paused**: The number of services that have their monitoring paused. + +**Actively monitoring table** + +This section lists all the services being monitored, showing key details for each service: + +
+ +* **Host**: The name and URL of the service being monitored. +* **Status**: The current status of the service, indicated by color-coded icons: + * Green: **Up** (operational) + * Red: **Down** (non-operational) + * Yellow: **Paused** (monitoring paused for this service) +* **Response time**: A visual graph showing the performance trends of the service over time. Each bar represents the response time of the service at a given interval. Green bars indicate a healthy response time, while red bars indicate slower or problematic performance. +* **Type**: Indicates the type of service being monitored (either Ping or HTTP). +* **Actions**: This column has settings icons that allow the user to configure the monitoring details of the specific service. + +At the top-right corner of the dashboard, there’s a button labeled **Create monitor**. This allows users to add a new server or website to monitor. + +A search bar is available above the list of monitored services, enabling users to quickly locate specific services by name or URL. + +**Status indicators** + +* **Green**: Indicates the service is currently up and operational. +* **Red**: Indicates the service is down or experiencing problems. +* **Yellow**: Indicates that monitoring for this service is paused. + +Each service has a graph in the **Response Time** column that displays its performance history over time. This allows you to easily visualize any spikes or drops in performance. + +The gear icon next to each monitored service allows for quick access to configuration settings or additional monitoring options. + +### Table actions + +
+ +When you click on the gear icon, you'll see a few options that correspond to that host: + +1. **Open site**: Opens the monitored website or server in a new browser tab. +2. **Details**: Displays historical uptime and performance metrics for the service. +3. **Incidents**: Shows a log of all incidents related to the service, including downtime and performance issues. +4. **Configure**: Allows modification of monitoring parameters like check frequency and alert preferences. +5. **Clone**: Duplicates the current service’s monitoring settings for a new service. +6. **Remove**: Removes the service from the monitored list and stops all monitoring activities.