Information Systems:IBM i OSS (open-source) guide for system administrators

From uniWIKI
Jump to navigation Jump to search

uniPHARM is no longer using IBM i OSS. Much of the stuff discussed below remains on the i (within PASE), but none of it is being actively used anymore.

Overview

This page is a collection of information catering to the system administration aspect of open-source development on IBM i. It will attempt to be as comprehensive in this regard as possible, while simplifying other details e.g. related to software development and code.

If it's not obvious already, IBM i OSS, for all intents and purposes, pretty much refers to Python development on the i.

Other useful pages

To keep this page small, information may be broken out into other pages, and their links will be kept here.

Installing/managing software

Background:  Open-source software on IBM i used to be implemented through PTFs (specifically, packages like Python, Ruby, and nginx were installable options under the 5733-OPS licensed program). In 2018, IBM implemented the yum package manager, which some Linux distributions use and is a much more elegant way of installing/removing software/utilities.

The Open Source Package Management tool, located under the Tools menu in IBM i Access Client Solutions, can be used to manage (install/uninstall) open-source packages on bart.

Packages present in both 5733-OPS and yum forms do not overlap with each other as they are installed into different locations:

  • 5733-OPS packages are installed in /QOpenSys/usr/bin
  • yum packages are installed in /QOpen/pkgs/bin

Lastly, there was a third and unofficial way of installing open-source utilities by porting AIX-based .rpm packages from a community-maintained repository called perzl. These packages install to /opt/freeware.

The executables in /usr/bin mostly symlink to 5733-OPS and perzl packages, so these currently take precedence. An effort will be made to gradually uninstall all 5733-OPS and perzl packages and migrate to yum packages.

Location of project source code

Python source code can be found in /uwdsrc on the IFS. There are currently two projects (and therefore two folders) in active development:

  • inx/ - InfoNext, which is a Python Django project to extend Infonet.
  • The static files for InfoNext is located in /webroot/static. These are javascript and CSS files used to support the front-end of the website.
  • The docs for InfoNext is an HTML site created by using a documentation tool, and the code can be found in inx/docs/.
  • uwdutils/ - Collection of Python scripts/utilities/tools for various tasks. Examples - ECU cleanup script, Gilead sales report script.

Git/version control

git is used for version control and Bitbucket is used as a git repository server.

  • inx and uwdutils are repositories in Bitbucket. Code changes are sync'ed to the IFS via FTP and to Bitbucket via git.
  • unipharmdevs is the name of the team/group account that owns these repositories. The Bitbucket user accounts of Norwin, Jeremy and Aaron Bartell of Krengeltech are members of this group.
  • Since team-owned repositories have to belong to Bitbucket projects, inx and uwdutils can be found in the Infonet and uwdutils projects, respecively.
  • The Infonet project also has other repositories that are being experimented with to house WebSmart code. A Web Orders project was also created for the same reason.

Accessing IFS/PASE using SSH and bash

SSH is the preferred method for doing anything in IFS/PASE. This is especially true for running Python programs. Using the IBM i CLI (STRQSH/QP2TERM) is a poor experience due to EBCDIC.

bash is the preferred shell program. Connecting via SSH uses another shell program by default (zsh? ksh?). Invoke bash by typing in bash in the command line.

Executing Python programs from IBM i CL

For situations where bash through SSH cannot be used to execute Python e.g. calling a Python program through the job scheduler, QP2SHELL should be used:

CALL PGM(QP2SHELL) PARM('/QOpenSys/usr/bin/sh' '-c' '/venvs/uwdutils/bin/python /uwdsrc/uwdutils/purolator_invoice_download.py &> /dev/null')

This example command starts up a shell and calls the python program through the shell, directing any program output to /dev/null a.k.a black hole.

Using Python virtual environments

Python is installed at the system level, which is what you get when you type python/python3 on the command-line. However, it is a best practice to use a separate instance of Python, or a Python virtual environment, for each project. This way, you can install project-specific dependencies (e.g. Python modules) without affecting the dependencies and version requirements of other projects.

Virtual environments are basically clones of base/system Python (a separate /bin folder containing the python3 executable is created for each virtual environment). The virtual environments are found in /venvs. There is currently one for inx, and one for uwdutils.

To use a specific virtual environment, it must first be activated:

source /path/to/venv/bin/activate

For uwdutils:

source /venvs/uwdutils/bin/activate

The command line prompt will change as follows, indicating that you are now in a virtual environment. 

norwinu@BART$ source /venvs/uwdutils/bin/activate
(uwdutils) norwinu@BART$

Now, typing in python will invoke the project's copy of Python, and running pip (Python extensions manager) will install/manage this particular venv's Python extensions.

Project and software documentation

This is a work-in-progress as we determine the best ways/tools to document projects, ideas, and reference/user guides.

  • Trello is used for tasks and project notes during development. It's a wallboard of sticky notes and "cards" to jot stuff in.
  • infonet.unipharm.com/docs is technical and user documentation for InfoNext in HTML format. The site is generated using Sphinx (a Python extension) which is a document generator. It generates documentation from a markup language in text files (found in /inx/docs/source), and transforms them into PDF, Word, or in this case, HTML (/inx/docs/build). The HTML is served directly by Apache.
  • uwdutils is too small to have a docs site. Rather, documentation is via README.md files (so they get rendered in Bitbucket), and in some cases, command-line help e.g. python program.py -h.
  • Google Docs is being experimented for project documentation e.g. design requirements.
  • Lucidchart is being used for diagramming, with the diagrams being embedded in Google Docs.
  • Confluence project management software is being considered.
  • An effort will be made to keep technical documentation out of this wiki. Pages may exist to 'represent' programs and scripts, but technical discussion beyond basic usage instruction should be deferred to READMEs or the docs site (Sphinx docs).
Retrieved from "https://owl.unipharm.com/mediawiki/index.php?title=Information_Systems:IBM_i_OSS_(open-source)_guide_for_system_administrators&oldid=13535"