From 7797d7027d4a0b209c2f7f0a2d4c5511f45f75d3 Mon Sep 17 00:00:00 2001 From: Amy Parker Date: Mon, 7 Aug 2023 12:58:01 -0700 Subject: [PATCH] create documentation basics This patch creates the basics for documentation. Signed-off-by: Amy Parker --- .gitignore | 5 ++- docs/Makefile | 20 +++++++++ docs/_images/fork.png | Bin 0 -> 2017 bytes docs/conf.py | 28 ++++++++++++ docs/configuration.rst | 42 ++++++++++++++++++ docs/contributing.rst | 98 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 28 ++++++++++++ docs/installing.rst | 73 ++++++++++++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++ install.sh | 10 ++--- requirements.txt | 4 +- 11 files changed, 336 insertions(+), 7 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/_images/fork.png create mode 100644 docs/conf.py create mode 100644 docs/configuration.rst create mode 100644 docs/contributing.rst create mode 100644 docs/index.rst create mode 100644 docs/installing.rst create mode 100644 docs/make.bat 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 0000000000000000000000000000000000000000..a4dbcd2d86ac6ecba04b70b21d20614301342858 GIT binary patch literal 2017 zcmV<72Oju|P)XlAXVytqJVtS|*cR6xR@5>ZWNic^3=#Xt~U0S1-mk}`t~D#n253NWZdmy{V~P%#EXSAan! zx}?k?gNiXAx&nfrl1L;N^v)2t4|*5fd-N22Fw9{4R^Z`34{)L249=g;S36Lxp|Y^B zfZx<$)YjCXtn3Qz-@Dts6?nx*H(_!B4rJ{y=q!8nwub9KcXTo_K~}~t)Ya7}?O$uC zfT7H8`0*pi$saL_v7w@_(EV)>rK^=>;fnQ*-zLVXoo7_^YJ>Z4 zF@!gi4Qbb|u(7d+S?A6gyL?(-kE*H)$RFtkm$9Lu6QyI=9JjXBoF&WGCNwJhqIpdQ zm1}-*_?|W=YOll$If~a|z zGQ|&-cPg>uixp&NS*EklhHj`UQ2aRc0jonpb@1SRNUf}JuAl(JWZqaCvmV*mzi_(x z`hJ4dtCr(W75R!lg^XACeHL=q}Ixbw{=1{CLy|OdLNJU&U_1welNk>*}&v zb!e!lnyZM58%Zn>>T>2Jf<==?S!B}e>nDWfIW#L*L|I!5h{B8ap(3eK|}8FP&IdRih(!{qie<}IwQA<$GaNI+Lb%nitn4b{Hzc5>tS!dv|aX#2j-16t&vns;t)VU8&i$KlZ7BiI-hqZL#%k5yiF zS;*A6?YyCnX%q)&)Rcmvn^PQ|qFdBfT~$y~P}9EKj-)NAICU}~{{E97lYM{*6aDez z$rBEs%Bs6aPtV{$D=sc+g38L$5^L71MC6?LO%N)M$IabC;}E-$oK;FvyjD8FBa&Mr^kJ_kEQ6VT;vSHrbPSDr)Q%;-g>?4p@S0jf6@``Rz<5MFQ zC{$y{jK=fl&$;T)o;`!NYy@V_3gsXQ2$;@&Zfa_Z-+w#8xz|6A9^(K?+LD5djD1br z(9h!HHzIO&IM#d_gPaq2Du?iYg^Esy-*GpeoGzgUZEtj_nolAnxb5 zYJ>g0&i#q|vrs#9AuClaIl?I?hxI~=E-Mvpzd2aC0@bddvLZXZ)Z|2Nei4!LNp7lI zh?Xtts&aqRg90&flnP1DxB+aoCXGy*)Hg<#3v1yZ15CRoTDd>y< zFnF*BQiUMu#UY?jcH-f}+wzzh+oWx5B9K^J!gNi0U-P~NU zZEG^3$+1yh-k(Zm>@vU=re>-SkhO)X;b}ceFALAB>Er(Nc!VvQwu_aD&q?tQ*Tuy} zY3@p_Nw=jPc1+Wb0(I)kX_lQ9>d*Oez_tXSt!%RcW%lYzo3N!TSo*x7Kqu0!-5+~N zPk+{^E3~z>R~uvTz0eq{vho#wNsqlwtUpw|1qzo`+Lh$G%viB=aMyku~EqaRMOix1)vsHY`kLnZsr2gR4pE5G<) zDeXZL(JziU)D?R9p_07*T2gdTQ&sl80TeJMRP^qjjh&s+RfwACvWzvR*1`e$I zf8R5JbgTbUa$3jaha67-jkIs!evs9K>pgh2f6m%on3qHXvjZ&_yC3E+Pkv5 ze$BPedZp@U00S1-mk}`t~D#n25 z3NWZdmy{V~P%#EXSAan!x}?k?gNiXAx&r?K!P)~|mh8-B00000NkvXXu0mjf={4NA literal 0 HcmV?d00001 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