diff --git a/docs/index.rst b/docs/index.rst index 9ee004bd..397f844a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -62,8 +62,8 @@ for information on migrating applications to the new API. :maxdepth: 2 :caption: Sysadmin's Guide - installation - + installation/01-freeipa-server.rst + installation/02-freeipa-client.rst .. Contributor's Guide diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 76de225f..00000000 --- a/docs/installation.rst +++ /dev/null @@ -1,132 +0,0 @@ -============ -Installation -============ - - -Installing and setting up IPA -============================= - -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 - -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:: - - ipa privilege-add "Stage User Managers" --desc "Manage registering users in Noggin" - ipa privilege-add-permission "Stage User Managers" --permissions "System: Read Stage Users" --permissions "System: Modify Stage User" --permissions "System: Remove Stage User" - -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:: - - 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/docs/installation/01-freeipa-server.rst b/docs/installation/01-freeipa-server.rst new file mode 100644 index 00000000..6bfeabe0 --- /dev/null +++ b/docs/installation/01-freeipa-server.rst @@ -0,0 +1,456 @@ +============================= +Setting up the FreeIPA server +============================= + +Preparation +=========== + +In order to run a FreeIPA server in a virtual machine, we need to set up the +following four files in the same directory. + +.. code-block:: yaml + + . + ├── Fedora-Cloud-Base-XX-A.B.x86_64.raw + ├── head.cfg + ├── head.sh + └── head.yml + + 1 directory, 4 files + + +Sourcing Image +-------------- + +Download the most recent release of +`Fedora Linux Cloud Edition `_ +in the RAW extension. + + +Network Configuration +--------------------- + +After replacing the variables mentioned below, the ``head.cfg`` file should +look like the following. + +- IPv4 gateway - ```` +- IPv4 address - ```` +- IPv4 DNS servers - ```` +- DHCP on IPv4 - ``Disabled`` +- DHCP on IPv6 - ``Disabled`` + +.. code-block:: yaml + + #cloud-config + + network: + version: 2 + renderer: "NetworkManager" + ethernets: + eth0: + dhcp4: false + dhcp6: false + gateway4: "" + addresses: + - "" + nameservers: + addresses: + - "" + + +Machine Configuration +--------------------- + +After replacing the variables mentioned below, the ``head.yml`` file should +look like the following. + +- Hostname - ```` +- FQDN - ```` +- Name for administrator user - ``root`` +- GECOS for administrator user - ```` +- Password for administrator user - ```` +- Disable administrator user account? - ``False`` +- Name for default user - ```` +- GECOS for default user - ```` +- Password for default user - ```` +- Disable default user account? - ``False`` +- Sudo mode for default user - ``ALL=(ALL) NOPASSWD:ALL`` +- Public SSH key for default user - ```` +- Groups for default user - ``wheel`` + +.. code-block:: yaml + + #cloud-config + + preserve_hostname: false + hostname: "" + fqdn: "" + + system_info: + default_user: + name: "root" + gecos: "" + plain_text_passwd: "" + lock_passwd: false + + final_message: | + Operating system has been initialized + Version: $version + Timestamp: $timestamp + Datasource: $datasource + Uptime: $uptime + + users: + - name: "" + gecos: "" + plain_text_passwd: "" + lock_passwd: false + sudo: "ALL=(ALL) NOPASSWD:ALL" + ssh_authorized_keys: + - "" + groups: + - "wheel" + + growpart: + mode: auto + devices: + - "/" + ignore_growroot_disabled: false + + +Configuration Script +-------------------- + +After replacing the variables mentioned below, the ``head.sh`` file should +look like the following. + +- Specific hostname - ``nogginvirt`` +- Environment name - ``head`` +- Memory size (in MB, should be minimum 2048) - ``4096`` +- CPU count (should be minimum 2) - ``4`` +- Network configuration file location - ```` +- Machine configuration file location - ```` +- Disk size (in GB, should be minimum 16) - ``24G`` +- Cloud image file location (in RAW) - ```` +- Output image file location (in RAW) - ```` +- Network interface binding name - ```` +- VNC port number - ```` +- Operating system variant - ``fedora-unknown`` + +.. code-block:: shell + + #!/bin/sh + + SPECNAME="nogginvirt" + EVMTNAME="head" + MEMCOUNT="4096" + CPUCOUNT="4" + NTWKFILE="" + CINTFILE="" + DISKSIZE="24G" + SRCEIMEJ="" + DESTIMEJ="" + NTWKNAME="" + VNCPORTN="" + + GRINCOLR="\033[42m" + RESETCOL="\033[0m" + + sudo qemu-img info $DESTIMEJ + + sudo qemu-img resize $DESTIMEJ -f raw $DISKSIZE + + sudo qemu-img info $DESTIMEJ + + sudo \ + virt-install \ + --virt-type kvm \ + --os-variant fedora-unknown \ + --arch x86_64 \ + --name $SPECNAME-$EVMTNAME \ + --memory $MEMCOUNT \ + --cpu host-passthrough \ + --vcpus $CPUCOUNT \ + --disk $DESTIMEJ,device=disk,bus=virtio,format=raw,sparse=false \ + --graphics vnc,listen=0.0.0.0,port=$VNCPORTN \ + --network model=virtio,bridge=$BRDGNAME \ + --cloud-init user-data=$INITFILE,network-config=$NTWKFILE \ + --import \ + --noautoconsole + + +Installation +============ + +Setting up the virtual machine +------------------------------ + +1. Ensure that the most recent release of Fedora Linux Cloud Edition is kept + in a certain directory + +2. Ensure that the variables are suitably replaced in the configuration files + kept in the same directory. + +3. Execute the configuration script start setting up the virtual machine. + + .. code-block:: shell + + sh head.sh + + .. code-block:: shell + + image: head.img + file format: raw + virtual size: 2 GiB (2147483648 bytes) + disk size: 622 MiB + Child node '/file': + filename: head.img + protocol type: file + file length: 2 GiB (2147483648 bytes) + disk size: 622 MiB + + image: head.img + file format: raw + virtual size: 24 GiB (25769803776 bytes) + disk size: 622 MiB + Child node '/file': + filename: head.img + protocol type: file + file length: 24 GiB (25769803776 bytes) + disk size: 622 MiB + + Starting install... + Creating domain... + Domain creation completed. + +4. Monitor the instantiation of the cloud installation using the following + command. + + .. code-block:: shell + + virsh console nogginvirt-head + +5. Connect to the instantiated cloud installation using the following command. + + .. code-block:: shell + + ssh -i @ + + +Setting up a FreeIPA installation +--------------------------------- + +1. Edit the hosts file of the cloud installation to reflect the following. + + .. code-block:: shell + + + + For example + + .. code-block:: shell + + 192.168.0.131 nogginvirt-head.apexaltruism.net nogginvirt-head + +2. Open ports in the firewall to allow for ports used by the FreeIPA server. + + .. code-block:: shell + + sudo firewall-cmd --add-service=freeipa-ldap --add-service=freeipa-ldaps --permanent + +3. Reload the firewall daemon to ensure that the changes thus made take effect. + + .. code-block:: shell + + sudo firewall-cmd --reload + +4. Install the FreeIPA server package without the optionally provided + dependencies. + + .. code-block:: shell + + sudo dnf install freeipa-server --setopt=install_weak_deps=False + +5. Set up a DNS server depending on the deployment environment preferences. + + Either set up DNS entries on an already used DNS service in the + infrastructure + + Or elect to use the integrated DNS server for FreeIPA. + + .. code-block:: shell + + sudo dnf install freeipa-server-dns --setopt=install_weak_deps=False + +6. Install the Fedora Account System plugin for IPA + + By either executing the following command + + .. code-block:: shell + + sudo dnf install freeipa-fas --setopt=install_weak_deps=False + + Or by running ``install.sh`` after checking out the codebase from the + `freeipa-fas `_ repository. + +7. Configure the installed FreeIPA server using the following command. + + .. code-block:: shell + + sudo ipa-server-install + +8. Answer the questions mentioned in the prompts of the installation script. + + Sticking to the values used before is mandatory in order for the server to + work properly. + + .. code-block:: + + The log file for this installation can be found in /var/log/ipaserver-install.log + ============================================================================== + This program will set up the IPA Server. + Version 4.11.0 + + This includes: + * Configure a stand-alone CA (dogtag) for certificate management + * Configure the NTP client (chronyd) + * Create and configure an instance of Directory Server + * Create and configure a Kerberos Key Distribution Center (KDC) + * Configure Apache (httpd) + * Configure SID generation + * Configure the KDC to enable PKINIT + + To accept the default shown in brackets, press the Enter key. + + Do you want to configure integrated DNS (BIND)? [no]: no + + Enter the fully qualified domain name of the computer + on which you're setting up server software. Using the form + . + Example: master.example.com + + + Server host name []: + + The domain name has been determined based on the host name. + + Please confirm the domain name []: + + The kerberos protocol requires a Realm name to be defined. + This is typically the domain name converted to uppercase. + + Please provide a realm name []: + Certain directory server operations require an administrative user. + This user is referred to as the Directory Manager and has full access + to the Directory for system management tasks and will be added to the + instance of directory server created for IPA. + The password must be at least 8 characters long. + + Directory Manager password: + Password (confirm): + + The IPA server requires an administrative user, named 'admin'. + This user is a regular system account used for IPA server administration. + + IPA admin password: + Password (confirm): + + Trust is configured but no NetBIOS domain name found, setting it now. + Enter the NetBIOS name for the IPA domain. + Only up to 15 uppercase ASCII letters, digits and dashes are allowed. + Example: EXAMPLE. + + NetBIOS domain name []: + + Do you want to configure chrony with NTP server or pool address? [no]: no + + The IPA Master Server will be configured with: + Hostname: + IP address(es): + Domain name: + Realm name: + + The CA will be configured with: + Subject DN: CN=Certificate Authority,O= + Subject base: O= + Chaining: self-signed + + Continue to configure the system with these values? [no]: yes + + The following operations may take some minutes to complete. + Please wait until the prompt is returned. + + Disabled p11-kit-proxy + Synchronizing time + No SRV records of NTP servers found and no NTP server or pool address was provided. + Using default chrony configuration. + + +9. Make note of the newly added values to the installation script prompts. + + These values would be used later while setting up the FreeIPA client in + the Noggin server. + + +Setting up users after authentication +------------------------------------- + +1. Login as the service administrator user using the password mentioned before. + + .. code-block:: shell + + kinit admin + Password for admin@: + +2. Add your first user to the FreeIPA server using the following command. + + .. code-block:: shell + + ipa user-add + + +Configuring FreeIPA server for registration +------------------------------------------- + +To allow for the management of registering users, the corresponding roles and +privileges need to be set up in the FreeIPA server. + +1. Create a privilege containing the permissions needed to manage stage users + by executing the following commands. + + .. code-block:: shell + + ipa privilege-add "Stage User Managers" --desc "Manage registering users in Noggin" + + .. code-block:: shell + + ipa privilege-add-permission "Stage User Managers" --permissions "System: Read Stage Users" --permissions "System: Modify Stage User" --permissions "System: Remove Stage User" + +2. Create a role associated with this privilege by executing the following + command. + + .. code-block:: shell + + ipa role-add "Stage User Managers" --desc "Manage registering users in Noggin" + + .. code-block:: shell + + ipa role-add-privilege "Stage User Managers" --privileges "Stage User Managers" + +3. For an administrators group called ``sysadmin``, allow people in the + ``sysadmin`` group the role to manage registering users. + + .. code-block:: shell + + ipa role-add-member "Stage User Managers" --groups sysadmin + + +Discretion +========== + +As there can be multiple ways of installing and configuring a FreeIPA server, +please refer to the basic quick start guide provided on the +`FreeIPA website `_ and the +comprehensive setup documentation on the +`Red Hat website `_ +if the aforementioned guide does not work. diff --git a/docs/installation/02-freeipa-client.rst b/docs/installation/02-freeipa-client.rst new file mode 100644 index 00000000..5217c6f2 --- /dev/null +++ b/docs/installation/02-freeipa-client.rst @@ -0,0 +1,443 @@ +============================ +Setting up the Noggin server +============================ + +Preparation +=========== + +In order to run a Noggin server in a virtual machine, we need to set up the +following four files in the same directory. + +.. code-block:: yaml + + . + ├── Fedora-Cloud-Base-XX-A.B.x86_64.raw + ├── main.cfg + ├── main.sh + └── main.yml + + 1 directory, 4 files + + +Sourcing Image +-------------- + +Download the most recent release of +`Fedora Linux Cloud Edition `_ +in the RAW extension. + + +Network Configuration +--------------------- + +After replacing the variables mentioned below, the ``main.cfg`` file should +look like the following. + +- IPv4 gateway - ```` +- IPv4 address - ```` +- IPv4 DNS servers - ```` +- DHCP on IPv4 - ``Disabled`` +- DHCP on IPv6 - ``Disabled`` + +Ensure that the ```` of the virtual machine running the FreeIPA +server is accessible from the chosen network configuration here. + +It is strongly recommended to have the virtual machine for the Noggin server +set up in the same subnet as that of the virtual machine running the FreeIPA +server to minimize latencies and possible performance inconsistencies. + +.. code-block:: yaml + + #cloud-config + + network: + version: 2 + renderer: "NetworkManager" + ethernets: + eth0: + dhcp4: false + dhcp6: false + gateway4: "" + addresses: + - "" + nameservers: + addresses: + - "" + + +Machine Configuration +--------------------- + +After replacing the variables mentioned below, the ``main.yml`` file should +look like the following. + +- Hostname - ```` +- FQDN - ```` +- Name for administrator user - ``root`` +- GECOS for administrator user - ```` +- Password for administrator user - ```` +- Disable administrator user account? - ``False`` +- Name for default user - ```` +- GECOS for default user - ```` +- Password for default user - ```` +- Disable default user account? - ``False`` +- Sudo mode for default user - ``ALL=(ALL) NOPASSWD:ALL`` +- Public SSH key for default user - ```` +- Groups for default user - ``wheel`` + +.. code-block:: yaml + + #cloud-config + + preserve_hostname: false + hostname: "" + fqdn: "" + + system_info: + default_user: + name: "root" + gecos: "" + plain_text_passwd: "" + lock_passwd: false + + final_message: | + Operating system has been initialized + Version: $version + Timestamp: $timestamp + Datasource: $datasource + Uptime: $uptime + + users: + - name: "" + gecos: "" + plain_text_passwd: "" + lock_passwd: false + sudo: "ALL=(ALL) NOPASSWD:ALL" + ssh_authorized_keys: + - "" + groups: + - "wheel" + + growpart: + mode: auto + devices: + - "/" + ignore_growroot_disabled: false + + +Configuration Script +-------------------- + +After replacing the variables mentioned below, the ``main.sh`` file should +look like the following. + +- Specific hostname - ``nogginvirt`` +- Environment name - ``main`` +- Memory size (in MB, should be minimum 2048) - ``4096`` +- CPU count (should be minimum 2) - ``4`` +- Network configuration file location - ```` +- Machine configuration file location - ```` +- Disk size (in GB, should be minimum 16) - ``24G`` +- Cloud image file location (in RAW) - ```` +- Output image file location (in RAW) - ```` +- Network interface binding name - ```` +- VNC port number - ```` +- Operating system variant - ``fedora-unknown`` + +.. code-block:: shell + + #!/bin/sh + + SPECNAME="nogginvirt" + EVMTNAME="main" + MEMCOUNT="4096" + CPUCOUNT="4" + NTWKFILE="" + CINTFILE="" + DISKSIZE="24G" + SRCEIMEJ="" + DESTIMEJ="" + NTWKNAME="" + VNCPORTN="" + + GRINCOLR="\033[42m" + RESETCOL="\033[0m" + + sudo qemu-img info $DESTIMEJ + + sudo qemu-img resize $DESTIMEJ -f raw $DISKSIZE + + sudo qemu-img info $DESTIMEJ + + sudo \ + virt-install \ + --virt-type kvm \ + --os-variant fedora-unknown \ + --arch x86_64 \ + --name $SPECNAME-$EVMTNAME \ + --memory $MEMCOUNT \ + --cpu host-passthrough \ + --vcpus $CPUCOUNT \ + --disk $DESTIMEJ,device=disk,bus=virtio,format=raw,sparse=false \ + --graphics vnc,listen=0.0.0.0,port=$VNCPORTN \ + --network model=virtio,bridge=$BRDGNAME \ + --cloud-init user-data=$INITFILE,network-config=$NTWKFILE \ + --import \ + --noautoconsole + + +Installation +============ + +Setting up the virtual machine +------------------------------ + +1. Ensure that the most recent release of Fedora Linux Cloud Edition is kept + in a certain directory + +2. Ensure that the variables are suitably replaced in the configuration files + kept in the same directory. + +3. Execute the configuration script start setting up the virtual machine. + + .. code-block:: shell + + sh main.sh + + .. code-block:: shell + + image: main.img + file format: raw + virtual size: 2 GiB (2147483648 bytes) + disk size: 622 MiB + Child node '/file': + filename: main.img + protocol type: file + file length: 2 GiB (2147483648 bytes) + disk size: 622 MiB + + image: main.img + file format: raw + virtual size: 24 GiB (25769803776 bytes) + disk size: 622 MiB + Child node '/file': + filename: main.img + protocol type: file + file length: 24 GiB (25769803776 bytes) + disk size: 622 MiB + + Starting install... + Creating domain... + Domain creation completed. + +4. Monitor the instantiation of the cloud installation using the following + command. + + .. code-block:: shell + + virsh console nogginvirt-main + +5. Connect to the instantiated cloud installation using the following command. + + .. code-block:: shell + + ssh -i @ + + +Installing and configuring a web server +--------------------------------------- + +1. Choose a web serer compatible with the deployment environment preferences. + + Either configure an already used web server in the infrastructure + + Or elect to use Nginx which is the default for this documentation. + + .. code-block:: shell + + sudo dnf install nginx --setopt=install_weak_deps=False + + +Setting up a Noggin installation +-------------------------------- + +Noggin server can be installed on the cloud installation using one of the +following three methods. + +- Installing from PyPI + +- Installing from Fedora Linux repositories + +- Installing from source + + +Installing from PyPI +```````````````````` + +1. Execute the following command to install Noggin and Noggin Messages project + from PyPI. + + .. code-block:: shell + + pip3 install noggin noggin-messages + +2. Download the ``noggin.cfg.example`` file from + `here `__ + and copy it to the ``/etc/noggin`` directory as ``noggin.cfg`` file. Edit + the variables (eg. the ``FREEIPA_*`` items to point to the FreeIPA server + deployment. + +3. Download the ``nginx.conf`` file from + `here `__ + and copy it to the ``/etc/nginx/conf.d`` directory as ``nginx.conf``. Make + adjustments according to the deployment requirements (eg. HTTPS or not, + certificates, domains etc.) + +4. Download the ``noggin.service`` file from + `here `__ + and copy it to the ``/etc/systemd/system`` directory as ``noggin.service``. + + Adjust the ``ExecStart`` section to account for the installation + environment, WSGI changes, IP address and port numbers. + + If Noggin was installed as the ``root`` user, change ``gunicorn`` location + to ``/usr/local/bin/gunicorn`` in the unit file. + + If Noggin was installed as a normal user, change ``gunicorn`` location to + ``/home//.local/bin/gunicorn`` in the unit file. + +5. Download the ``noggin.sysconfig`` file from + `here `__ + and copy it to the ``/etc/sysconfig`` directory as ``noggin``. + + +Installing from Fedora Linux repositories +````````````````````````````````````````` + +1. Execute the following command to install Noggin package from the Fedora + Linux repositories. + + .. code-block:: shell + + sudo dnf install noggin + +2. Edit the configuration file for Noggin located in the + ``/etc/noggin/noggin.cfg`` directory with the variables used for setting + up the FreeIPA server (eg. the ``FREEIPA_*`` items) to point to the + FreeIPA server deployment. + +3. Edit the web server configuration file named ``nginx.conf`` located in the + ``/etc/nginx/conf.d`` directory and make adjustments according to the + deployment requirements (eg. HTTPS or not, certificates, domains etc.) + +4. Edit the service unit file named ``noggin.service`` located in the + ``/etc/systemd/system`` directory and make changes in the ``ExecStart`` + section to account for the installation environment, WSGI changes, IP + address and port numbers. + +5. Copy the ``noggin.sysconfig`` file from the ``deployment`` directory to the + ``/etc/sysconfig`` directory as ``noggin``. + + +Installing from source +`````````````````````` + +1. Download and extract the most recent tarball from the primary branch of + the repository. + + .. code-block:: shell + + wget https://github.com/fedora-infra/noggin/releases/download/v1.9.0/noggin_aaa-1.9.0.tar.gz + + .. code-block:: shell + + tar -xvzf noggin_aaa-1.9.0.tar.gz + +2. Install ``poetry`` and ``virtualenv`` using the following command if not + already installed. + + .. code-block:: shell + + sudo dnf install poetry virtualenv --setopt=install_weak_deps=False + +3. Create and activate a virtual environment in the project directory. + + .. code-block:: shell + + cd noggin_aaa + + .. code-block:: shell + + virtualenv venv + + .. code-block:: shell + + source venv/bin/activate + +4. Install the project assets and its dependencies using the following command. + + .. code-block:: shell + + (venv) poetry install --without-dev --extras deploy + +5. Copy the ``noggin.cfg.example`` file from the ``deployment`` directory to + the ``/etc/noggin`` directory as ``noggin.cfg`` and add the variables used + for setting up the FreeIPA server (eg. the ``FREEIPA_*`` items) to point to + the FreeIPA server deployment. + +6. Copy the ``nginx.conf`` file from the ``deployment`` directory to the + ``/etc/nginx/conf.d`` directory as ``nginx.conf`` and make adjustments + according to the deployment requirements (eg. HTTPS or not, certificates, + domains etc.) + +7. Copy the ``noggin.service`` file from the ``deployment`` directory to the + ``/etc/systemd/system`` directory as ``noggin.service`` and adjust the + ``ExecStart`` section to account for the installation environment, WSGI + changes, IP address and port numbers. Change ``gunicorn`` location to + ``//bin/gunicorn`` in the unit file. + +8. Copy the ``noggin.sysconfig`` file from the ``deployment`` directory to the + ``/etc/sysconfig`` directory as ``noggin``. + + +Allowing ports through the firewall +----------------------------------- + +1. Execute the following commands to allow the required ports through the + firewall. + + .. code-block:: shell + + sudo firewall-cmd --add-service=http --permanent + + .. code-block:: shell + + sudo firewall-cmd --add-service=https --permanent + +2. Reload the firewall daemon to ensure that the changes thus made take effect. + + .. code-block:: shell + + sudo firewall-cmd --reload + + +Starting the services +--------------------- + +1. Execute the following command to enable and start the Nginx and Noggin + services. + + .. code-block:: shell + + sudo systemctl enable --now noggin.service + + .. code-block:: shell + + sudo systemctl enable --now nginx.service + + +Discretion +========== + +For more information, take a look at the +`official Noggin documentation `_. diff --git a/news/1363.bug b/news/1363.bug new file mode 100644 index 00000000..d4ff60f6 --- /dev/null +++ b/news/1363.bug @@ -0,0 +1 @@ +Revisited and rewrote the installation steps in greater detail