Installation

Server Install

Create user

Must be run as root.

# Create user and group on Ubuntu
useradd --system -c 'Karma Server' -d /srv/karma -m karma -s /bin/sh -U

# Create user and group on SuSE
groupadd karma
useradd --system -c 'Karma Server' -d /srv/karma -m karma -s /bin/sh -g karma

# Lock the user account
passwd -l karma

# Switch to user
su - karma

Copy app to server

First copy karma-server-vX.X.X-linux-x64.run to server.

Extract app

Should be run as karma. As root use su - karma to switch to that user!

# Switch to user
su - karma

chmod a+x ./karma-server-vX.X.X-linux-x64.run

# Extract in a directory
./karma-vX.X.X-linux-x64.run --bashpack-noexec --bashpack-target ~/server

Create Config Directory

cp -r ~/server/config ~/config
cp ~/server/config/local.yaml.sample ~/config/local.yaml

Adjust Config

vi ~/config/local.yaml

See Configuration for detailed informations.

Test Server

~/server/bin/karma

Initiate request in another terminal window:

curl -i -H "Accept: application/json" http://localhost:9999/api/me

Response should be like:

HTTP/1.1 401 Unauthorized
Connection: close
Link: </api/token>; rel="oauth2-token"; grant-types="client_credentials"; token-types="bearer"
WWW-Authenticate: Bearer realm="Karma"
Content-Type: application/json
Content-Length: 123
Expires: Mon, 23 Aug 1982 12:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Content-MD5: parfRP0VOJNslRsmTdw0Dw==
Date: Tue, 13 May 2014 13:25:30 GMT
Server: karma-server
Api-Version: 0.1.0
Request-Id: 0df90eb0-daa2-11e3-b857-b139b981d03a
Response-Time: 10

{"code":"UnauthorizedError","message":"Authentication via bearer token required. Follow the oauth2-token link to get one!"}

System Config & Scripts

These must be executed by root user.

service config /etc/default/karma.conf

This is an optional step.

Example can be found in /srv/karma/server/deploy/service.conf

cp /srv/karma/server/deploy/service.conf /etc/default/karma.conf

init.d script /etc/init.d/karma

cp /srv/karma/server/deploy/init.d.sh /etc/init.d/karma
update-rc.d karma defaults
/etc/init.d/karma start
/etc/init.d/karma info

upstart script /etc/init/karma.conf

cp /srv/karma/server/deploy/upstart.conf /etc/init/karma.conf
start karma
status karma

systemd script /usr/lib/systemd/system/karma.service

cp /srv/karma/server/deploy/karma.service /usr/lib/systemd/system/karma.service

systemctl enable karma
systemctl start karma
systemctl status karma

Logrotate script /etc/logrotate.d/karma

ln -s /srv/karma/server/deploy/logrotate.conf /etc/logrotate.d/karma

Client Update / Install

Copy new files

su - karma
mv ~/htdocs ~/htdocs.$(date +"%Y-%m-%d_%H-%M")
unzip karma-ui-vX.X.X.zip -d ~/htdocs

Adjust Base URL

When the server is accessed through a proxy via a context like /karma you must add just the base in ~/htdocs/index.html (line 8):

<base href="/karma/">

And update gzip file

gzip -9 -c ~/htdocs/index.html > ~/htdocs/index.html.gz

Server Update

Copy app to server

First copy karma-server-vX.X.X-linux-x64.run to server.

Stop running instance

These must be executed by root user.

  • init.d: /etc/init.d/karma stop
  • upstart: stop karma
  • systemd: systemctl stop karma

Backup

# Switch to user
su - karma

mv ~/server ~/server.$(date +"%Y-%m-%d_%H-%M")

Extract app

Should be run as karma. As root use su - karma to switch to that user!

chmod a+x ./karma-server-vX.X.X-linux-x64.run

# Extract in a directory
./karma-server-vX.X.X-linux-x64.run --bashpack-noexec --bashpack-target ~/server

Test Server

~/server/bin/karma

Initiate request in another terminal window:

curl -i -H "Accept: application/json" http://localhost:9999/api/me

Response should be like:

HTTP/1.1 401 Unauthorized
Connection: close
Link: </api/token>; rel="oauth2-token"; grant-types="client_credentials"; token-types="bearer"
WWW-Authenticate: Bearer realm="Karma"
Content-Type: application/json
Content-Length: 123
Expires: Mon, 23 Aug 1982 12:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Content-MD5: parfRP0VOJNslRsmTdw0Dw==
Date: Tue, 13 May 2014 13:25:30 GMT
Server: karma-server
Api-Version: 0.1.0
Request-Id: 0df90eb0-daa2-11e3-b857-b139b981d03a
Response-Time: 10

{"code":"UnauthorizedError","message":"Authentication via bearer token required. Follow the oauth2-token link to get one!"}

Update System Config & Scripts

Same as in System Config & Scripts

Restart Service

These must be executed by root user.

  • init.d: /etc/init.d/karma start
  • upstart: start karma
  • systemd: systemctl start karma

HTTP-Proxy

nginx

location /karma {
  rewrite /karma(.*) $1 break;

  proxy_redirect          off;
  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 https;
  proxy_set_header        X-Forwarded-Ssl   on;
  client_max_body_size    10m;
  client_body_buffer_size 128k;
  proxy_connect_timeout   60s;
  proxy_send_timeout      90s;
  proxy_read_timeout      90s;
  proxy_buffers           32 4k;

  proxy_pass_request_headers on;
  proxy_no_cache $cookie_nocache  $arg_nocache$arg_comment;
  proxy_no_cache $http_pragma     $http_authorization;
  proxy_cache_bypass $cookie_nocache $arg_nocache $arg_comment;
  proxy_cache_bypass $http_pragma $http_authorization;

  proxy_pass_header       Authorization;
  proxy_pass_header       Request-Id;
  proxy_pass_header       Api-Version;
  proxy_pass_header       Response-Time;

  proxy_pass http://127.0.0.1:9999;
}

Apache

Deploy karma under document root /

ProxyPass / http://127.0.0.1:9999/ retry=0
ProxyPassReverse / http://127.0.0.1:9999/

# Support large URLs
# Description:  Determine size of internal data throughput buffer
# Syntax:   ProxyIOBufferSize bytes
# Default:  ProxyIOBufferSize 8192
# Context:  server config, virtual host
# Status:   Extension
# Module:   mod_proxy
ProxyIOBufferSize 65536

Deploy karma under a path, e.g. /karma

ProxyPass /karma/ http://127.0.0.1:9999/ retry=0
ProxyPassReverse /karma/ http://127.0.0.1:9999/

# Support large URLs
# Description:  Determine size of internal data throughput buffer
# Syntax:   ProxyIOBufferSize bytes
# Default:  ProxyIOBufferSize 8192
# Context:  server config, virtual host
# Status:   Extension
# Module:   mod_proxy
ProxyIOBufferSize 65536

Be sure to adjust the base URL in the Karma client as explained in section Client Update / Install

Note from the Apache Mod Proxy documentation: If the first argument ends with a trailing /, the second argument should also end with a trailing /, and vice versa. Otherwise, the resulting requests to the backend may miss some needed slashes and do not deliver the expected results.

Service Actions

init.d

/etc/init.d/karma <action>
  • start - start the service, no-op when already running
  • stop - stop the service
  • stop-graceful - stop the service gracefully
  • restart - stop and start if running, otherwise start the service
  • restart-graceful - stop gracefully and start if running, otherwise start the service
  • try-restart - restart the service if the service is already running
  • reload - restart all worker gracefully at once, or start if not running
  • force-reload - restart all worker gracefully at once, or start if not running
  • graceful - restart all worker gracefully one after the other, or start if not running
  • status - print the current status of the service
  • info - print configuration and the current status of the service

For example after you changed only the configuration use reload to load the new configuration without shutting the server down.

upstart

<action> karma
  • start - start the service, no-op when already running
  • stop - stop the service
  • restart - stop and start if running, otherwise start the service
  • reload - restart all worker gracefully at once, or start if not running
  • status - print the current status of the service
← RequirementsLDAP →