Skip to content

Commit

Permalink
Updated the Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
beaini committed Jul 23, 2023
1 parent 248c2a9 commit 9782002
Showing 1 changed file with 31 additions and 16 deletions.
47 changes: 31 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,42 @@
# MullvadServerAlert
MullvadServerAlert
==================

MullvadServerAlert is a tool that uses GitHub Actions to monitor the status of Mullvad VPN servers and sends alerts to a specified Discord channel when a server is detected as down. It uses the OpenAPI endpoint to fetch the status of each server and verifies their status.
MullvadServerAlert is a tool that uses GitHub Actions to monitor the status of Mullvad VPN servers. It sends alerts via multiple notification services when a server is detected as down. The tool uses the Mullvad API to fetch the status of each server, verifies their status, and sends notifications using [Apprise](https://github.com/caronc/apprise), a universal notification service.

## Setup
Features
--------

1. **Clone this repository:** Use the "Use this template" button to create a new repository from this template.
- Monitors the status of Mullvad VPN servers at specified intervals
- Sends notifications via multiple services (Discord, Slack, etc.) when a server is detected as down
- Uses GitHub Actions for scheduling and running the checks
- Configurable list of servers to monitor
- Configurable list of Apprise URLs for notifications

2. **Modify the config file:** Edit the `config.json` file in your new repository to include the hostnames of the Mullvad servers you want to monitor.
Setup
-----

3. **Set up the Discord webhook:**
- In your Discord server, create a new webhook (Server Settings > Integrations > New Webhook).
- Copy the webhook URL.
1. Click on the "Use this template" button to create a new repository from this template.

4. **Add the Discord Webhook URL as a GitHub Secret:**
- In your cloned GitHub repository, go to Settings > Secrets > New repository secret.
- Create a new secret named `DISCORD_WEBHOOK` and paste the webhook URL as the value.
2. Navigate to the 'Settings' tab of your new repository and click on 'Secrets' in the left sidebar.

5. **Monitor your Mullvad servers:** The GitHub Action is scheduled to run once an hour and will send a message to your Discord server if any of the specified Mullvad servers are detected as down.
3. Click on the 'New repository secret' button.

## License
4. Create two new secrets:

MullvadServerAlert is released under the MIT License. See the LICENSE file for more details.
- `HOSTNAMES`: A JSON-formatted string of the hostnames you want to monitor. For example: `["server1","server2","server3"]`.
- `APPRISE_URLS`: A JSON-formatted string of the Apprise URLs for the services where you want to receive notifications. For example: `["url1","url2","url3"]`.
5. Save the secrets. GitHub Actions will now have access to these secrets and will use them when running the workflow.

## Contributions
6. The GitHub Actions workflow is already set up in the `.github/workflows` directory in the file `hostname_check.yml`. By default, the workflow is scheduled to run every 5 minutes. If you want to change this, open `hostname_check.yml` and modify the `cron` line under `schedule`. The syntax for this line is the same as for cron jobs.

Contributions are welcome! Please feel free to submit a pull request.
Usage
-----

After setting up, the GitHub Actions workflow will automatically run at the specified intervals. If a server is detected as down, the tool will send notifications to the configured services.

You can also run the tool locally by running `python main.py`. Make sure to set the `HOSTNAMES` and `APPRISE_URLS` environment variables if you are not using the `config.json` file.

Contributing
------------

Contributions are welcome! Please open an issue if you encounter any problems or have suggestions for improvements.

0 comments on commit 9782002

Please sign in to comment.