CITKat - A Web Catalog for CITK

Installation

$ ./setup.py install --user

will install CITKat into your home folder and adds citkat to your $PATH environment.

If your shell still cannot find the citkat command, you might have to adjust your $PATH like this:

$ export PATH=$HOME/.local/bin:$PATH

Be sure to add the above line to your shell's config file as well in that case.

Dependencies

Besides the pip-dependencies (which will be resolved automatically for you) you'll have to install npm. The best way is to use your distribution's package manager to install npm

Usage

navigate to your local working directory (containing the XML files, generated by the build-generator) using a terminal and shell of your choice, then execute citkat:

$ cd your/working/dir
$ citkat

CITKat will fire up an internal web server; you can now preview your catalog data using your favorite browser.

CITKat XML Schema Documentation

You may generate the schema documentation by using the following command:

$ git submodule init; git submodule update  # get xs3p from submodule
$ xsltproc -o schema/CITKat.xsd.html xs3p/xs3p.xsl schema/CITKat.xsd

Production Server Setup for Debian Stretch

wget --quiet -O - https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add -
export VERSION=node_9.x
export DISTRO="$(lsb_release -s -c)"
echo "deb https://deb.nodesource.com/$VERSION $DISTRO main" | sudo tee /etc/apt/sources.list.d/nodesource.list
echo "deb-src https://deb.nodesource.com/$VERSION $DISTRO main" | sudo tee -a /etc/apt/sources.list.d/nodesource.list

Production Server Setup for Ubuntu 16.04

TODO: include emperor setup

Apache with mod_uwsgi

TODO

Nginx with uWSGI

Install packages:

apt install --no-install-recommends libxml2-dev libxslt1-dev nginx uwsgi uwsgi-plugin-python python2.7-minimal python-virtualenv python-dev built-essential libz-dev git npm

Create /etc/nginx/sites-available/citkat.conf:

server {
    listen 80;
    listen [::]:80;
#    server_name <YOUR_HOST_NAME>;
    location / { try_files $uri @citkat; }
    location @citkat {
        include uwsgi_params;
        uwsgi_pass unix:/var/run/uwsgi/citkat.socket;
    }
}

TODO: create

Create /var/www/citkat and the python-virtualenv, then install CITKat:

mkdir /var/www/citkat; cd /var/www/citkat
python2 -m virtualenv .env
source .env/bin/activate
git clone --branch <DESIRED_VERSION_TAG> https://opensource.cit-ec.de/git/citk.citkat.git
cd citk.citkat
./setup.py install

Then create /etc/uwsgi/apps-available/citkat.ini:

[uwsgi]
uid = www-data
gid = www-data
env = CONTENT_PATH=/path/to/markdown/content  # CHANGE THIS
env = CATALOG_PATH=/path/to/catalog/xml  # CHANGE THIS

plugin = systemd_logger
logger = systemd

appname = citkat
plugin = python2
base = /var/www/%(appname)
chdir = %(base)
vacuum = true
die-on-term = true
virtualenv = %(base)/.env
module = %(appname)
callable = %(appname)

Now create /etc/systemd/system/uwsgi@.service:

[Unit]
Description=%i uWSGI app
After=syslog.target

[Service]
ExecStart=/usr/bin/uwsgi \
        --ini /etc/uwsgi/apps-available/%i.ini \
        --socket /var/run/%i.socket
User=www-%i
Group=www-data
Restart=on-failure
KillSignal=SIGQUIT
Type=notify
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

and /etc/systemd/system/uwsgi@.socket:

[Unit]
Description=Socket for uWSGI app %i

[Socket]
ListenStream=/var/run/%i.socket
SocketUser=www-%i
SocketGroup=www-data
SocketMode=0660

[Install]
WantedBy=sockets.target

Add the citkat user:

adduser www-citkat --disabled-login --disabled-password \
  --ingroup www-data --home /var/www/citkat --shell /bin/false

Enable und start uWSGI:

systemctl daemon-reload
systemctl enable uwsgi@citkat.socket
systemctl enable uwsgi@citkat.service
systemctl start uwsgi@citkat.socket
systemctl start uwsgi@citkat.service

Updating CITKat on a Production Server

systemctl stop uwsgi@citkat
source /var/www/.env/bin/activate
pip uninstall citkat
cd $HOME
rm -rf $HOME/citk.citkat
git clone --branch <DESIRED_VERSION_TAG> https://github.com/RDTK/CITKat.git
./setup.py install
systemctl start uwsgi@citkat