Add installation docs from the Fedora package

Source: https://src.fedoraproject.org/rpms/noggin/tree/main

Thanks to Neal on this one.

Fixes: #1289 #332

Signed-off-by: Aurélien Bompard <aurelien@bompard.org>

deployment/nginx.conf

@@ -0,0 +1,30 @@
+#server {
+    #listen 80;
+    #server_name localhost.localdomain;
+    #return 301 https://localhost.localdomain$request_uri;
+#}
+
+#server {
+    #listen 443 ssl;
+
+    #server_name localhost.localdomain;
+
+    #access_log  /var/log/nginx/noggin.access.log;
+    #error_log  /var/log/nginx/noggin.error.log;
+
+    #ssl_certificate /etc/pki/tls/....crt
+    #ssl_certificate_key /etc/pki/tls/....key
+
+    #location @noggin {
+        #proxy_set_header Host $http_host;
+        #proxy_set_header X-Real-IP $remote_addr;
+        #proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        #proxy_set_header X-Forwarded-Proto $scheme;
+        #proxy_pass http://127.0.0.1:8000;
+    #}
+
+    #location / {
+        #try_files $uri @noggin;
+    #}
+
+#}

deployment/noggin.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=Noggin Accounts Management Portal
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+EnvironmentFile=/etc/sysconfig/noggin
+ExecStart=sh -c "gunicorn-3 ${GUNICORN_OPTS} -w ${GUNICORN_WORKERS} --env NOGGIN_CONFIG_PATH=/etc/noggin/noggin.cfg --access-logfile /var/log/noggin/access.log --error-logfile /var/log/noggin/error.log --bind tcp://127.0.0.1:8000 'noggin.app:create_app()'"
+
+[Install]
+WantedBy=multi-user.target

deployment/noggin.sysconfig

@@ -0,0 +1,3 @@
+GUNICORN_OPTS=""
+GUNICORN_WORKERS="3"
+

docs/installation.rst

@@ -2,13 +2,31 @@
 Installation
 ============
 
-.. note:: **TODO**: Cover end-user installation here.
 
+Installing and setting up IPA
+=============================
 
-IPA settings
-============
+Installing IPA
+--------------
+There is a `basic quick start guide`_ for setting up FreeIPA.
+More comprehensive setup documentation is `available from Red Hat`_.
+
+.. _basic quick start guide: https://www.freeipa.org/page/Quick_Start_Guide
+.. _available from Red Hat: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/installing_identity_management/index
+
+Install the IPA FAS plugin
+--------------------------
+If you're on Fedora, run::
+
+    sudo dnf install freeipa-fas
 
-If you want to be able to manage registering users, you need to setup the corresponding role and privilege in IPA.
+Otherwise you can checkout the code from
+https://github.com/fedora-infra/freeipa-fas/ and run ``install.sh``.
+
+Setting up IPA
+--------------
+If you want to be able to manage registering users, you need to setup the
+corresponding role and privilege in IPA.
 
 First, create a privilege containing the permissions needed to manage stage users::
 
@@ -20,6 +38,95 @@ Then, create a role associated with this privilege::
     ipa role-add "Stage User Managers" --desc "Manage registering users in Noggin"
     ipa role-add-privilege "Stage User Managers" --privileges "Stage User Managers"
 
-Finally, if your administrators group is called ``sysadmin``, give people in the ``sysadmin`` group the role to manage registering users::
+Finally, if your administrators group is called ``sysadmin``, give people in
+the ``sysadmin`` group the role to manage registering users::
 
     ipa role-add-member "Stage User Managers" --groups sysadmin
+
+
+Installing and setting up Noggin
+================================
+
+Install Noggin
+--------------
+
+If you're on Fedora, you can install the ``noggin`` package with::
+
+    sudo dnf install noggin
+
+Otherwise, you can install Noggin from PyPI with::
+
+    pip install noggin noggin-messages
+
+You can also download the tarball or clone the repository, and run::
+
+    poetry install --without dev --extras deploy
+
+You'll find ``poetry`` in your distribution's packages, on Fedora it's named
+``poetry``. You will also need to install ``noggin-messages``, with ``pip`` or
+with ``dnf``.
+
+Configure Noggin
+----------------
+The tarball and the repository contain a file named ``deployment/noggin.cfg.example``.
+Copy it in ``/etc/noggin/noggin.cfg``. The ``noggin`` package in Fedora already
+installs this file.
+
+Edit ``/etc/noggin/noggin.cfg`` to set up Noggin settings as appropriate. As we
+set up a IPA system earlier, update the FREEIPA_* items to point to your
+server.
+
+Take a moment to review all the settings in the file and update them as needed.
+Most settings in there should have comments documenting what they're for, or
+are otherwise obvious for what needs to be set and why.
+
+Install and configure a web server
+----------------------------------
+This document will use Nginx as the webserver, but any proxying webserver would
+do.
+
+First, install nginx::
+
+    sudo dnf install nginx
+
+Copy the file named ``deployment/nginx.conf`` in the tarball or the repo to
+``/etc/nginx/conf.d``, and adjust as appropriate to your webserver setup (HTTPS
+or not, certificates, domain(s), etc). If you are using the Fedora package,
+this file is already installed.
+
+Open ports in the firewall
+--------------------------
+On Fedora, this can be done with::
+
+    sudo firewall-cmd --add-service=http
+    sudo firewall-cmd --add-service=https
+    sudo firewall-cmd --runtime-to-permanent
+
+Setup the Noggin service
+------------------------
+The Fedora package already installs the service definition file. If you are not
+on Fedora or are not using the RPM, you can use the files named
+``deployment/noggin.service`` and ``deployment/noggin.sysconfig`` in the
+tarball or the repo. Copy the ``.service`` file to
+``/etc/systemd/system/noggin.service`` and the ``.sysconfig`` file to
+``/etc/sysconfig/noggin``.
+
+Adjust the ``ExecStart`` in ``/etc/systemd/system/noggin.service`` to account
+for the environment where you installed Noggin.
+
+- If you installed Noggin with ``pip`` as ``root``, ``gunicorn`` will be at
+  ``/usr/local/bin/gunicorn``
+- If you installed Noggin with ``pip`` as a normal user, ``gunicorn`` will be
+  at ``/home/username/.local/bin/gunicorn``
+- If you installed Noggin in a virtualenv, ``gunicorn`` will be at
+  ``/path/to/virtualenv/bin/gunicorn``
+- If you installed Noggin with Poetry, ``gunicorn`` will be at
+  ``/home/username/.cache/pypoetry/virtualenvs/noggin-aaa-*/bin/gunicorn``
+
+Enable and start Nginx and Noggin services::
+
+    sudo systemctl enable --now noggin.service nginx.service
+
+For more information, take a look at `the official Noggin documentation`_.
+
+.. _the official Noggin documentation: https://noggin-aaa.readthedocs.io/

pyproject.toml

@@ -22,7 +22,6 @@ packages = [
 
 include = [
     { path = "tox.ini", format = "sdist" },
-    { path = "noggin.cfg.example", format = "sdist" },
     { path = "babel.cfg", format = "sdist" },
     { path = "deployment/*", format = "sdist" },
     { path = "docs/*", format = "sdist" },