BlueWave Uptime

An open source server monitoring application

(yes, we have a light theme as well, but this looks better on readme.md)

BlueWave Uptime 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

See BlueWave Uptime in action. The username is [email protected] and the password is Demouser1!

Features

• Completely open source, deployable on your servers
• Website monitoring
• Port monitoring
• Ping monitoring
• Incidents at a glance
• Page speed monitoring
• 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
• MUI (React framework)
• Node.js
• MongoDB

Contributing

We love contributors. Here's how you can contribute:

• Check Contributor's guideline.
• Have a look at our Figma designs here. We encourage you to copy to your own Figma page, then work on it as it is read-only.
• Open an issue if you believe you've encountered a bug
• Make a pull request to add new features/make quality-of-life improvements/fix bugs.

Made with contrib.rocks.

Also check other developer and contributor-friendly projects of BlueWave:

• BlueWave HRM
• BlueWave Onboarding
• BlueWave DataRoom
• VerifyWise

Getting Started

• Clone this repository to your local machine

1. Quickstart for Users
2. Quickstart for Developers
3. Docker Compose
4. Installation (Client)
5. Configuration(Client)
   • Environment
6. Getting Started (Server)
   • Install Server
   • Environment
   • Database
     • (Optional) Dockerised Databases
   • Start Server
7. API Documentation
8. Error Handling
9. Contributors

---

Quickstart for Users

1. Download our Docker Compose File
2. Download our Quickstart script
3. Place these files in a directory of your choice
4. Run quickstart.sh and generate config files
5. Run docker compose up to start the application
6. Application is running at http://localhost

Quickstart for Developers

MAKE SURE YOU CD TO THE SPECIFIED DIRECTORIES AS PATHS IN COMMANDS ARE RELATIVE

Cloning and Initial Setup

1. Clone this repository
2. Checkout the develop branch git checkout develop

Docker Images Setup

3. CD to the Docker directory
4. Run docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis
5. 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, run npm install
7. While in Server directory, create a .env file with the required environmental variables
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
11. While in the Client cirectory run npm run dev

Access Application

12. Client is running at localhost:5173
13. Server is running at localhost:5000

---

Docker Compose

The fastest way to start the application is to use our Dockerfiles and Docker Compose.

To get the application up and running you need to:

1. In the Docker directory run the build script build_images.sh to build docker images for the client, server, Redis database, and MongoDB database.

2. In the Dokcer directory create a mongo.env file with a username and password:

USERNAME_ENV_VAR=user
PASSWORD_ENV_VAR=password

3. In the Docker directory, create a server.env file with the requried environmental variables for the server. Sample file:

CLIENT_HOST="http://localhost:5173"
JWT_SECRET=<jwt_secret>
DB_TYPE="MongoDB"
DB_CONNECTION_STRING="mongodb://<username>:<password>@mongodb:27017/uptime_db"
REDIS_HOST="redis"
REDIS_PORT=6379
TOKEN_TTL="99d"
PAGESPEED_API_KEY=<api_key>
SYSTEM_EMAIL_HOST="smtp.gmail.com"
SYSTEM_EMAIL_PORT=465
SYSTEM_EMAIL_ADDRESS=<system_email>
SYSTEM_EMAIL_PASSWORD=<system_email_password>

4. In the Client directory, create a client.env file with the required environmental variables for the client. Sample file:

VITE_APP_API_BASE_URL="http://localhost:5000/api/v1"
VITE_APP_API_LOG_LEVEL="debug"

5. In the Docker directory run docker compose up to run the docker-compose.yaml file and start all four images.

That's it, the application is ready to use on port 80.

Client

Installation

1. Change directory to the Client directory
2. Install all dependencies by running npm install

Configuration

Environmental 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 Development Server

1. Run npm run dev to start the development server.

---

Getting Started (Server)

Manual Install

Install Server

1. Change directory to the Server directory
2. Install all dependencies by running npm install

Environmental Variables

Configure the server with the following environmental variables:

ENV Variable Name	Required/Optional	Type	Description	Accepted Values
CLIENT_HOST	Required	string	Frontend Host
JWT_SECRET	Required	string	JWT secret
DB_TYPE	Optional	string	Specify DB to use	MongoDB | FakeDB
DB_CONNECTION_STRING	Required	string	Specifies URL for MongoDB Database
PORT	Optional	integer	Specifies Port for Server
LOGIN_PAGE_URL	Required	string	Login url to be used in emailing service
REDIS_HOST	Required	string	Host address for Redis database
REDIS_PORT	Required	integer	Port for Redis database
TOKEN_TTL	Optional	string	Time for token to live	In vercel/ms format https://github.com/vercel/ms
PAGESPEED_API_KEY	Optional	string	API Key for PageSpeed requests
SYSTEM_EMAIL_HOST	Required	string	Host to send System Emails From
SYSTEM_EMAIL_PORT	Required	number	Port for System Email Host
SYSTEM_EMAIL_ADDRESS	Required	string	System Email Address
SYSTEM_EMAIL_PASSWORD	Required	string	System 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 Server

• 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.

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

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.