diff --git a/.gitignore b/.gitignore index 40f1f82..c08c15e 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,7 @@ ssvp-config*.json *.js *.db target/ -*.pem \ No newline at end of file +*.pem +_build/ +_static/ +_templates/ \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_images/fork.png b/docs/_images/fork.png new file mode 100644 index 0000000..a4dbcd2 Binary files /dev/null and b/docs/_images/fork.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..37f7085 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'SSVP' +copyright = '2023, Amy Parker' +author = 'Amy Parker' +release = 'v0.2.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx_rtd_theme"] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..d38966e --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,42 @@ +Configuration +============= + +Here's all of the configuration options: + +- :code:`enable_host_ipv6`: Determines whether to enable IPv6 support. On non-Linux OSes, having this option enabled may disable IPv4 support. (optional) + - Allowed values: :code:`true`, :code:`false` +- :code:`ssl`: Determines SSL support, and configuration settings. + - Allowed values: + - :code:`null`: disables SSL + - :code:`["/path/to/cert.pem", "/path/to/key.pem"]`: uses existing certificates/keyfiles + - :code:`"adhoc"`: Uses self-signed/ad-hoc certificates +- :code:`port`: Port number for the SSVP server (optional) + - Allowed values: any integer from 1 to 65535 (note: 1-1024 require root/sudo) +- :code:`instance_name`: Name put in the navbar brand for the instance + - Allowed values: any string +- :code:`splash`: Splash text for the main page (optional) + - Allowed values: any string +- :code:`servers`: List of servers, set as an object + - Allowed values: must fit the following schema: + .. code-block:: json + + "name_of_server": { + "ip": "ip address (url for http)", + "module": "testing module name", + "args": "list of module arguments" + } + +- :code:`services`: List of services, set as an object + - Allowed values: must fit the servers schema +- :code:`database`: Database information + - Note: the only options required on sqlite3 are :code:`host`, :code:`type`, and :code:`prefix` + - :code:`type`: database type + - Either :code:`mysql`, :code:`postgres`, :code:`sqlite3` + - :code:`host`: database host IP/sqlite3 file path + - Valid IPv4 or IPv6 address + - :code:`port`: database port + - Valid TCP port (unix sockets are not supported) + - :code:`username`: database username + - :code:`password`: database password + - :code:`database`: name of database in the DB system + - :code:`prefix`: prefix for tables \ No newline at end of file diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..9a5710f --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,98 @@ +Contributing +============ + +Thanks for wanting to help with the development of SSVP! Here's how you can contribute. + +Ways to Contribute +------------------ + +- **Submit bug reports**: when you find a problem in SSVP, report it `here `_. +- **Write code**: See below on how to write code and submit it to SSVP. +- **Contribute to documentation**: Similar procedures to writing code, but work is done in the :code:`docs/` folder. +- **Translation**: We don't have internationalization set up yet, but if you'd like to assist, `let us know `_. + +Getting Started +--------------- + +The first thing you need to do is to create a fork of the project. You need a GitHub account for this; if you don't want to make one, reach out to us. + +To create a fork, go to the `SSVP project page `_, and click the Fork button: + +.. image:: _images/fork.png + +You then need to download your fork to your local machine (make sure you have git installed): + +.. code-block:: bash + + git clone --depth=1 https://github.com/yourGitHubUsername/ssvp + +You then want to run the `installation process `_. This will help you get all your dependencies installed. +If you're just doing development work, you probably won't have a database already set up yet. As a result, we recommend using a local `sqlite3` installation +when setting up the database functionality. When choosing an installation directory, keep it as the default option. Don't set an "autorunner" or "server reboot launch method". + +Creating a Patch +---------------- + +Now that you're all set up, it's time to create a patch. + +First, you need to establish a branch for your patch. It should be given a relevant name; for instance, if you're implementing Windows support for the interval module, a possible branch name could be `interval-windows-support`. + +Once you've chosen the name, create and switch to the branch: + +.. code-block:: bash + + git checkout -b your-branch-name + +You can now freely modify files, building your patch. When you're ready to save an interval of your progress, run: + +.. code-block:: bash + + git add -A + git commit + +Saving an interval doesn't automatically push all the changes. All of the "commits" will be sent when you propose the changes. + +Running the commit command opens up a dialog asking you to put a message for the commit. This should be of the form: + +.. code-block:: + + active subject line + + This patch (say what the patch does). (Justify why it should be added). + + Signed-off-by: Your Name + +The subject line should be stated as an action; instead of "changes x to y", it should be "change x to y". + +If your commit is resolving a bug, add another line, where XX is the issue number: + +.. code-block:: + + Fixes: #XX + +When you're done creating commits, run the following command: + +.. code-block:: + + git push --set-upstream origin (name of your branch) + +Then, go to your fork on GitHub. As long as you do this step shortly after you push, it should say something about your branch having "recent changes". Click the button to submit a pull request. +If there is no button there, go to pull requests, and open one manually. + +The source branch should be set as your new branch. The target branch should be set as amyipdev/main. You can then write a title and description for your PR. It should +follow the same format as the commit message format, with the subject line becoming the title. + +When you're ready, you can click the "create pull request" button. This will send it off. + +Reviewing +--------- + +Someone will come along to review your patch. They may have suggestions and/or comments on it; these should be addressed when you are able. +You may need to add additional comments to fix issues presented by reviewers. + +When ready, the PR will be accepted. That means your code has made it into SSVP. + +Resetting Your Fork +------------------- + +When you make your next patch, before branching, you should sync your fork. This can be done with the "Sync" button on GitHub when you're viewing your main branch. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b86cdbb --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,28 @@ +.. SSVP documentation master file, created by + sphinx-quickstart on Mon Aug 7 09:58:30 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +SSVP: The Server Statistics Viewer Project +========================================== + +SSVP is a utility for viewing statistics and information about your servers, services, and more. It's designed to be a public front page for uptime information, +helping your users know whether issues are coming from your side or theirs. + +If you're looking to help build the future of SSVP, go to the `contributor's guide `_. +If you're just trying to get SSVP set up, go to the `installation guide `_. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + contributing + installing + configuration + + + +Utilities +--------- +- Index: :ref:`genindex` +- Search: :ref:`search` diff --git a/docs/installing.rst b/docs/installing.rst new file mode 100644 index 0000000..e500fa2 --- /dev/null +++ b/docs/installing.rst @@ -0,0 +1,73 @@ +Installation +============ + +Installation of SSVP is usually simple, thanks to the easy installer (:code:`./install.sh`). + +Supported Operating Systems +--------------------------- + +Right now, we're currently focusing on just supporting Linux. \*BSD and macOS support may come in the future; Windows support is unlikely. + +Theoretically, any Linux distribution should work. We currently only officially support **Debian 12** and **Fedora 38**. + +Our dependency installer currently has support for most **apt**-based and **dnf/yum**-based distributions. Support for other package managers is a `planned feature `_. +The dependency verifier works on all systems, **but cannot check the presence of libpq and its headers**. + +If you have to install dependencies manually, be aware that you need all of the packages list `here `_. + +Downloading SSVP +---------------- + +You need Git in order to download SSVP. + +Once Git is installed, run: + +.. code-block:: bash + + git clone --depth=1 https://github.com/amyipdev/ssvp + +Running the Installation Script +------------------------------- + +To run the installation script, from the SSVP download directory, run: + +.. code-block:: bash + + ./install.sh + +Installation Components +----------------------- + +The installer will prompt you on whether to run several of its modules. Defaults are always in brackets, such as :code:`not default/[default]`. + +The first option is to autoinstall system dependencies. You should only respond yes if you are on a **Fedora** or **Debian** derivative system. This includes: + +- `Red Hat Enterprise Linux `_ +- `Fedora Linux `_ +- `Debian Linux `_ +- `Ubuntu Linux `_ (and its derivatives, such as `Kubuntu `_ and `Linux Mint `_) +- `CentOS Linux `_, `Rocky Linux `_, and `Alma Linux `_ + +If you decline the option, you'll be given the choice to verify your system dependencies. This just checks that they're all available in the PATH, and works on any system. + +If you don't have a virtual environment already, you'll be asked if you want one created. This is highly recommended, and on many systems, it is extremely difficult not to use one. +If one exists or you opted to create one, you'll be asked if you want to source the venv. This is mandatory for it to work properly. + +You'll then be asked about installing other types of dependencies. The PyPI option installs dependencies from :code:`requirements.txt`. If you have no intention of using or testing postgres, +you may be able to get away with not installing `psycopg2`; it takes a while to compile on lower-powered systems and takes up a decent amount of space, so skipping it may be of interest. +All of the node dependencies are required for building SSVP; as such, you should generally opt to autoinstall the NPM dependencies. The last option is site dependencies; this just runs +:code:`make` prior to setting everything else up. If you're planning on running `make` for some purpose later anyways, this is unnecessary. + +You'll then be asked to work with the database and with the SSVP configuration. You can always configure things later, but the config file script greatly helps with initial setup. +The database step presumes you have an existing database, or that you're going to be using `sqlite3`. You'll need database credentials on hand when running the initialization. +If you use the defaults for databases, you should use the defaults in the config file database section. Initializing cached statistics is also highly recommended, as SSVP will +fail to run without the entries. + +The full installation is meant for server installs, when you want to segregate the installations and have automation set up for you automatically. If you're a developer, +this often is not necessary. Cron is currently the only supported mode for autoinstallation; please note your cron setup needs to be able to support `@reboot` (most do, but some old editions don't). +Systemd (and OpenRC) support will be added eventually. + +You're now done with the installation. You can run the server by running `srv/tmux.sh`. It should print :code:`no current client` when done. You can check on the server by running `tmux attach`, +and disconnect from it by pressing `CTRL-b d`. + +If you need to change settings in your configuration file, please see the `configuration guide `_. \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/install.sh b/install.sh index b006539..5b2bea8 100755 --- a/install.sh +++ b/install.sh @@ -112,12 +112,12 @@ fi echo -n "Installation directory [current directory]: " read INSDIR -if [ "$INSDIR" == "" ]; then - INSDIR=$(pwd) +if [ "$INSDIR" != "" ]; then + $PREROOT make install INSTALLDIR=$INSDIR +else + INSDIR="$(pwd)" fi -$PREROOT make install INSTALLDIR=$INSDIR - echo -n "Choose an autorunner method (cron/[none]): " read ATRMTH if [ "$ATRMTH" == "cron" ]; then @@ -131,7 +131,7 @@ if [ "$RBTLNC" == "cron" ]; then (crontab -l; echo "@reboot $INSDIR/srv/tmux.sh") | crontab - fi -echo "Installation finished. Remember to set up a cron job for srv/interval.py to run every 5 minutes (this will be automated in the future)" +echo "Installation finished." # next todo: cron (also implement systemd timers) # next todo: systemd service for web server? \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 168f78d..9bb7408 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,4 +4,6 @@ ping3 requests psycopg2 pyopenssl -gunicorn \ No newline at end of file +gunicorn +sphinx +sphinx_rtd_theme \ No newline at end of file