Getting Started

This section is for administrators who don’t already have Karaage installed and wish to get started for the first time.

If you do have an older version of Karaage already installed, please see the Upgrading section.


Assumptions made by this documentation. Other configurations are possible, however you will have to adapt from this documentation.

  • You have a cluster running Slurm or PBS that is already up and running.

  • You want to OpenLDAP with ppolicy support, on the same server.

  • You have a Debian Jessie server already setup for Karaage.

  • You will be installing all components on a single system.

  • You are upgrading to Karaage 3.1.

  • The visible hostname is This will have to be changed as required.

  • Note these instructions install the shibboleth support, which may not be required. Simplifications can be made to some steps if shibboleth not required.

MySQL configuration

  1. Run the following commands:

    apt-get install mysql-server

    This should ask for a password for the root mysql user. Make sure this is a secure password. You can use makepasswd if you want. For the purpose of this documentation, we will assume you used XXXXXXXX. Do not use XXXXXXXX for your password on a production system.

  2. (optional) Create a /root/.my.cnf file containing:

    user            = root
    password        = XXXXXXXX
  3. Create a /etc/mysql/conf.d/karaage.cnf file containing:

    default-storage-engine = innodb
    sql_mode = STRICT_ALL_TABLES
    default-character-set = utf8

    Note: these settings may affect other applications that use this database.

  4. Restart mysql server to load config, and connect to it:

    service mysql restart
  5. Create a user and database for karaage:

    mysql> create database karaage;
    mysql> CREATE USER 'karaage'@'localhost' IDENTIFIED BY 'YYYYYYYY';
    mysql> GRANT ALL PRIVILEGES ON karaage.* TO 'karaage'@'localhost';

    You will use the values you set, later, in the karaage settings. Do not use YYYYYYYY on a production system.


  1. If you require a proxy server for out going connections, set it up now.

    export http_proxy=
  2. Create /etc/systemd/system/karaage.service file:

    ExecStartPre=-/usr/bin/docker kill karaage
    ExecStartPre=-/usr/bin/docker rm karaage
    ExecStartPre=/usr/bin/docker pull brianmay/karaage:slurm17.02-apache
    ExecStart=/usr/bin/docker run --name karaage \
      --net="host" \
      -e MUNGE_KEY_FILE="/mnt/munge/munge.key" \
      -v /opt/karaage/etc/munge:/mnt/munge \
      -v /opt/karaage/log:/var/log \
      -v /opt/karaage/lib/munge:/var/lib/munge \
      -v /opt/karaage/etc/slurm:/etc/slurm \
      -v /opt/karaage/etc/shibboleth:/etc/shibboleth \
      -v /opt/karaage/etc/karaage3:/etc/karaage3 \
      -v /opt/karaage/lib/karaage3:/var/lib/karaage3 \
    ExecStop=/usr/bin/docker stop karaage
  3. Create required users in /etc/passwd:

    • munge: required for munge, for slurm.

    • _shibd: required for shibbioleth.

    • www-data: required by web process.

  4. Create required directories and configuration files:

    • /opt/karaage/etc/munge: contains munge.key, and must be owned and only readable by munge user.

    • /opt/karaage/log/munge: should be writable by munge user.

    • /opt/karaage/lib/munge: should be writable by munge user.

    • /opt/karaage/etc/slurm: should contain slurm.conf.

    • /opt/karaage/etc/shibboleth: should contain all shibboleth config.

    • /opt/karaage/etc/karaage3: should contain

    • /opt/karaage/log/apache2: Should be writable by www-data.

    • /opt/karaage/log/karaage3: Should be writable by www-data.

    • /opt/karaage/lib/karaage3: Should be writable by www-data.

    • /opt/karaage/cache/karaage3: Should be writable by www-data.

  5. Copy /etc/karaage3/ from initial sample file.

  6. Edit the DATABASES setting in /etc/karaage3/

         'default': {
               'ENGINE': 'django.db.backends.mysql',
               'NAME': 'karaage',
               'USER': 'karaage',
               'PASSWORD': 'YYYYYYYY',
               'HOST': 'localhost',
               'PORT': '',
               'ATOMIC_REQUESTS': True,
               'OPTIONS': {
                   'sql_mode': 'STRICT_ALL_TABLES'
  7. Add the HTTP_HOST setting in /etc/karaage3/

    HTTP_HOST = ""

    Replace with the visible hostname of your server.

  8. Update other settings in /etc/karaage3/ as required. See comments in this file and Karaage Settings.

  9. Restart Karaage after changing /etc/karaage3/

    systemctl restart karaage
  10. Create a karaage superuser using kgcreatesuperuser:

    kg-manage kgcreatesuperuser
  11. Start karaage.

    systemctl daemon-reload
    systemctl start karaage
  12. Monitor progress of Karaage starting.

    journalctl -u karaage -f
  13. Check that Karaage is running and listening on http://localhost:443/.

SSL certificate

You should create a signed SSL certificate for Apache and LDAP.

  1. Generate a SSL private key, a CSR.

    cd /etc/ssl/private
    openssl genrsa -out www_privatekey.pem 2048
    chmod 640 www_privatekey.pem
    openssl req -new -key www_privatekey.pem -out www_csr.pem -sha256
  2. Submit www_csr.pem to a CA, and get it signed. Copy resultant certificate into www_cert.pem. Check this file is sha256:

    openssl x509 -text -noout -in www_cert.pem

    You should see the following text:

    Signature Algorithm: sha256WithRSAEncryption.

    You may need an intermediate certificate too. Copy this into www_intermediate.pem.

  3. Join certificate with intermediate (required for some versions of slapd):

    cd /etc/ssl/private
    cat www_cert.pem www_intermediate.pem > www_combined.pem
  4. Setup the permissions:

    apt-get install ssl-cert
    cd /etc/ssl/private
    chown root:ssl-cert www_*.pem

Apache Configuration

Karaage, by default, requires a https connection. While this default can be changed, this is not advisable on a production system.

In the following steps, replace with the visible hostname of your server.

  1. Install apache2.

    apt-get install apache2
  2. Setup Apache to support secure https connections. Changes should be made to /etc/apache2/sites-available/default-ssl:

    SSLCertificateFile /etc/ssl/private/www_cert.pem
    SSLCertificateKeyFile /etc/ssl/private/www_privatekey.pem
    SSLCertificateChainFile /etc/ssl/private/www_intermediate.pem

    For more details on what changes are required, see the Apache howto.

  3. Connections to http should be redirected to https. Please replace the /etc/apache2/sites-available/default file entirely with the following:

    <VirtualHost *:80>
        Redirect permanent /

    For more information on this step, see the Apache wiki.

  4. (recommended) It is recommended that you change the following settings in /etc/apache2/mods-available/ssl.conf to make SSL more secure by disabling insecure protocols and ciphers:

    SSLProtocol all -SSLv2 -SSLv3

    Note however that the SSLProtocol will break IE6, and the SSLCipherSuite setting will break IE on XP. For more information on securing Apache, see the Mozilla website.

  5. Enable default-ssl with the following commands:

    a2enmod ssl
    a2ensite default-ssl.
    service apache2 restart
  6. Test by loading both and in your browser.

  7. (recommended) Enable HSTS support with the following commands:

    echo 'Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"' > /etc/apache2/conf-available/hsts.conf
    a2enmod  headers
    a2enconf hsts
    service apache2 restart
  8. Test by loading both and in your browser.

  9. Test website with SSL Test.

  10. Enable proxy with the following commands:

    a2enmod proxy proxy_http
    service apache2 restart
  11. Add following to /etc/apache2/sites-available/000-default.conf:

    Alias /kgstatic "/var/lib/karaage3/static"
    <Location "/kgstatic">
        SetHandler None
        Require all granted
    <Location "/karaage/">
        ProxyPreserveHost On
        ProxyPass "http://localhost:443/karaage/"
        ProxyPassReverse "http://localhost:443/karaage/"

Data stores

So far you have not configured any external datastores. Karaage will work, however probably won’t do anything useful. See the next section to configure datastores (Data Stores).


For information on configuring additional plugins, see Plugins.

Cluster tools

If installing Karaage on a cluster, you may want to install the cluster tools, see Cluster tools.