diff --git a/deployment/nginx.conf b/deployment/nginx.conf new file mode 100644 index 000000000..cfc4a321c --- /dev/null +++ b/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; + #} + +#} diff --git a/noggin.cfg.example b/deployment/noggin.cfg.example similarity index 100% rename from noggin.cfg.example rename to deployment/noggin.cfg.example diff --git a/deployment/noggin.service b/deployment/noggin.service new file mode 100644 index 000000000..91f0b1c55 --- /dev/null +++ b/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 diff --git a/deployment/noggin.sysconfig b/deployment/noggin.sysconfig new file mode 100644 index 000000000..2cff12c72 --- /dev/null +++ b/deployment/noggin.sysconfig @@ -0,0 +1,3 @@ +GUNICORN_OPTS="" +GUNICORN_WORKERS="3" + diff --git a/docs/installation.rst b/docs/installation.rst index f0a3cfab9..76de225f3 100644 --- a/docs/installation.rst +++ b/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/ diff --git a/pyproject.toml b/pyproject.toml index e00841b9b..d3578beea 100644 --- a/pyproject.toml +++ b/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" },