-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This patch adds the new base for the README design. Signed-off-by: Amy Parker <[email protected]>
- Loading branch information
Showing
1 changed file
with
41 additions
and
33 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,51 +1,59 @@ | ||
| # ssvp: server statistics viewer project | ||
| <div align="center"> | ||
| <h1>ssvp: the server statistics viewer project</h1> | ||
| </div> | ||
| <div align="center"> | ||
|
|
||
| This project is in a very early development stage. It is usable, | ||
| and you can view an example invocation [for my homelab](https://status.amyip.net), | ||
| but it is nowhere near production-ready yet. | ||
|   | ||
|
|
||
| There is not currently an organized installer. If you want to try | ||
| it out, make sure you have the following dependencies installed for | ||
| your system (package names dependent on distribution): | ||
| </div> | ||
|
|
||
| - sass | ||
| - python3 with pip and venv | ||
| - nodejs and npm | ||
| SSVP is a lean, efficient status dashboard and uptime tracker for servers and services. It provides: | ||
| - A clean, easy-to-understand interface for your users to understand uptime metrics. | ||
| - A lightweight data collection platform supporting your existing back-end stack. | ||
| - An easy-to-interact-with API for more advanced data analysis. | ||
| - Support for tracking through a wide variety of methods, getting around any hurdles your stack creates. | ||
| - (WIP) Alerts for developers and users to stay on top of your platform. | ||
|
|
||
| You also must have: | ||
| You can view a live version run by the project owner at https://status.amyip.net. | ||
|
|
||
| - A working MySQL or MariaDB server | ||
| The main thing that differs SSVP from other status pages is that it's designed for users first. It's AGPLv3-licensed and will always be free-as-in-freedom software, unlike many alternatives. It's also designed to be run externally, open to users; you don't have to expose any data you don't have to, which can help prevent side-channeling attacks. | ||
|
|
||
| And, we recommend (while SSVP is still in development): | ||
| ## Installation | ||
|
|
||
| - tmux | ||
| > These installation instructions will be better developed in the future. For now, they are meant for advanced users only. | ||
| Step 1: Copy srv/ssvp-config.json.example to srv/ssvp-config.json | ||
| A more streamlined way to install SSVP is currently in development. Until then, you can: | ||
| 1. Install the npm and Python dependencies (in a venv). | ||
| 2. Copy `srv/ssvp-config.json.example` to `srv/ssvp-config.json`, and configure it. | ||
| 3. Run `make` to compile the Sass and Typescript. | ||
| 4. Add a runner for `srv/interval.py` to run on intervals (ideally every 1-5 minutes) in your crontab. | ||
| 5. Launch `srv/app.py` in a persistent environment (such as tmux). | ||
|
|
||
| Step 2: Configure that file with your relevant information | ||
| (the only currently supported test module is ping) | ||
| ## Contributing | ||
|
|
||
| Step 3: Make a venv (`python3 -m venv venv`), activate it | ||
| (`source venv/bin/activate`), and install | ||
| Python dependencies (`pip3 install -r requirements.txt`) | ||
| There are two main ways you can help contribute to SSVP: | ||
| 1. Use SSVP, and report any bugs you find in Issues. | ||
| 2. Fix bugs and implement new features via PRs. | ||
|
|
||
| Step 4: Set up a cron job to run srv/interval.py | ||
| (recommended is 5 minutes, but any interval works) | ||
| More detailed contribution instructions will be available at a later time. | ||
|
|
||
| Step 5: Install node dependencies (`npm i`) | ||
| ## Limitations and Future Features | ||
|
|
||
| Step 6: Compile sass and typescript (`make`) | ||
| A list of planned features is available [here](https://github.com/amyipdev/ssvp/issues/1); if there's something you want included that isn't yet available, feel free to develop it and submit a PR! | ||
|
|
||
| Step 7: Launch the web server (`flask --app srv/app.py --host :: --port 80`) | ||
| ## Licensing | ||
|
|
||
| > You may want to do this in tmux. | ||
| This project was made by Amy Parker/amyipdev. | ||
|
|
||
| Please note that only Linux is fully supported. Other OSes may | ||
| not work or may require special workarounds, such as having to use | ||
| a single network stack (IPv4-only or IPv6-only) or requiring | ||
| interval.py to be run with superuser/administrator permissions. | ||
| Copyright 2023 Amy Parker, [email protected]. | ||
|
|
||
| Currently, support is highest-level for Debian 12 and Fedora 38. | ||
| SSVP is licensed under the AGPLv3. You can view the license in the LICENSE file. | ||
|
|
||
| ## Inspiration | ||
|
|
||
| The project draws heavy inspiration from the design and setup of https://discordstatus.com, which runs on [Atlassian Statuspage](https://www.atlassian.com/software/statuspage). | ||
|
|
||
| It also draws inspiration from [Uptime Kuma](https://github.com/louislam/uptime-kuma). Uptime Kuma is great as an internal status page, and I would highly recommend it if the main intention of your status page is to be used internally instead of externally. | ||
|
|
||
| I wanted to work on a project which would give me a chance to do some web design, something I generally hate, and learn frameworks like Bootstrap and TypeScript. | ||
|
|
||
| HTTPS will be available in the future. Until then, you can run | ||
| it through a reverse proxy like nginx. |