From df36e4d1f667bcb64227e0caf4f5216791304380 Mon Sep 17 00:00:00 2001 From: Alex Holliday Date: Thu, 14 Nov 2024 11:32:51 +0800 Subject: [PATCH 1/2] Update docs for docker monitors --- docs/guides/placeholder.md | 0 docs/quickstart.md | 181 --------------------------------- docs/users-guide/quickstart.md | 181 --------------------------------- 3 files changed, 362 deletions(-) delete mode 100644 docs/guides/placeholder.md delete mode 100644 docs/quickstart.md delete mode 100644 docs/users-guide/quickstart.md diff --git a/docs/guides/placeholder.md b/docs/guides/placeholder.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/quickstart.md b/docs/quickstart.md deleted file mode 100644 index 6d2ec2242..000000000 --- a/docs/quickstart.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -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 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](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 deleted file mode 100644 index 6d2ec2242..000000000 --- a/docs/users-guide/quickstart.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -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 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](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. From f2243634cd29860900cefc439466ef2bc76cc780 Mon Sep 17 00:00:00 2001 From: Alex Holliday Date: Thu, 14 Nov 2024 11:33:55 +0800 Subject: [PATCH 2/2] Update docs and docker-compose --- Docker/dist/docker-compose.yaml | 2 ++ guides/users-guide/creating-a-new-monitor.md | 17 ++++++++------- guides/users-guide/quickstart.md | 22 ++++++++++++++++++++ 3 files changed, 33 insertions(+), 8 deletions(-) diff --git a/Docker/dist/docker-compose.yaml b/Docker/dist/docker-compose.yaml index c62fb2ea6..6d3faaf7f 100644 --- a/Docker/dist/docker-compose.yaml +++ b/Docker/dist/docker-compose.yaml @@ -18,6 +18,8 @@ services: environment: - DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db - REDIS_HOST=redis + # volumes: + # - /var/run/docker.sock:/var/run/docker.sock:ro redis: image: bluewaveuptime/uptime_redis:latest ports: diff --git a/guides/users-guide/creating-a-new-monitor.md b/guides/users-guide/creating-a-new-monitor.md index 5784d1f41..0135c0b81 100644 --- a/guides/users-guide/creating-a-new-monitor.md +++ b/guides/users-guide/creating-a-new-monitor.md @@ -8,24 +8,25 @@ 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. +- **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. +- **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. +- **Docker monitoring:** Checks whether a Docker container is running ### 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) +- 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. +- **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/quickstart.md b/guides/users-guide/quickstart.md index 55e23f286..665062bf3 100644 --- a/guides/users-guide/quickstart.md +++ b/guides/users-guide/quickstart.md @@ -10,6 +10,17 @@ icon: sign-posts-wrench 2. Run `docker compose up` to start the application 3. Now the application is running at `http://localhost` +##### Optional Config: + +- If you want to monitor Docker containers, uncomment this line in `docker-compose.yaml`: + +``` + # volumes: + # - /var/run/docker.sock:/var/run/docker.sock:ro +``` + +This gives the app access to your docker daemon via unix socket, please be aware of what you are doing. + --- ## Quickstart for users (remote server) @@ -19,6 +30,17 @@ icon: sign-posts-wrench 3. Run `docker compose up` to start the application 4. Now the application is running at `http://` +##### Optional Config: + +- If you want to monitor Docker containers, uncomment this line in `docker-compose.yaml`: + +``` + # volumes: + # - /var/run/docker.sock:/var/run/docker.sock:ro +``` + +This gives the app access to your docker daemon via unix socket, please be aware of what you are doing. + --- ## Quickstart for developers