|
Elektra
0.8.23
|
This tutorial explains how to install, configure and run everything that is required for the Snippet Sharing service and website. As operating system we expect Debian Jessie to be used, although most parts should also be applicable to other systems.
The Snippet Sharing service consists of two parts, a backend (the REST server) and a frontend (an AngularJS application executed in the browser), which also includes the Elektra website. The service itself can be used to share configuration snippets, i.e. configuration files of arbitrary applications.
As first step we need to install some dependencies required by the applications.
The backend requires the most dependencies and unfortunately some of them need to be installed manually because no APT packages are available.
The required dependencies with their own dependencies are:
You'll also need CMake and a modern C/C++ compiler, so in case you don't have them installed already, use apt-get install build-essential cmake to do so.
To install all required APT packages at once, simply run: apt-get install libboost-all-dev libpcre3-dev zlib1g-dev libgcrypt11-dev libicu-dev python libssl-dev
To install CppCMS, there are two options available:
To install CppCMS manually without dependency manager:
tar -xjf cppcms-1.x.x.tar.bz2 && cd cppcms-1.x.x (replace 1.x.x with your version)mkdir build && cd build && cmake ..make && make test && make installFurther build and installation information can be found on their website. It contains also a guide explaining the installation through a dependency manager. Unfortunately, no repository is available for Debian Jessie yet.
The Jansson library supports working with JSON data in C. To install it, use the following steps:
bunzip2 -c jansson-2.x.tar.bz2 | tar xf - && cd jansson-2.x (replace 2.x with your version)mkdir build && cd build && cmake ..make && make check && make installNow we can also install LibJWT:
tar -xjf v1.x.x && cd libjwt-1.x.x (replace 1.x.x with your version)autoreconf -i && ./configuremake all && make checkIf you are using Ubuntu, LibJWT can also be installed through a pre-built APT package:
add-apt-repository ppa:ben-collins/libjwtapt-get update && apt-get install libjwtThe frontend does only require the package manager npm (>= v3). It is preferred to install it along with nodeJS, for example via provided packages. The version that comes via Debian Jessie (v1.4) is insufficient. The installation was tested with npm version 3.10.8-9, but it should also work with other versions of 3+.
After installing the dependencies, we are ready to build the applications. To do so, we can follow the steps explained in the build guide. Make sure to include the two tools rest-backend and rest-frontend, e.g. by using the arguments -DTOOLS="ALL;rest-backend;rest-frontend".
After building Elektra and the applications, we can use make install to install them. Further information and troubleshooting can be found in the install guide.
The applications configure themselves as much as possible during build, but some settings have to be set manually afterwards.
After the installation, the configuration specification of the backend has to be mounted with the command kdb mount-rest-backend-config. You can check if the mounting was successful by issuing kdb mount. There should be an entry in the list with a path like spec/sw/elektra/restbackend/#0 and a similar one without the leading spec. If you do not see this mountpoints, have a look at the mount script in the tool_exec (which is defined during installation of Elektra). You can also run the commands manually.
To complete the mounting, you also need to ensure that the spec plugin is used as global plugin. If you have not changed anything about the global plugins yet, you can simply use kdb global-mount to ensure that the spec plugin is added as global plugin. If not, you need to add all currently mounted global plugins to the command as they will be deleted otherwise.
After that you need to set an additional configuration parameter that has no default value. It is recommended to set it for the system namespace if you will use a tool like systemctl to manage the services.
To generate a secure key, you can also use pwgen (install via apt-get install pwgen). Use
to generate and set a strong random encryption secret.
The option -N system for kdb set defines the used namespace (in this case it is system). In order for the configuration specification to work (e.g. validation), we have to use cascading key names. This is why we have to define the namespace by using this option instead of passing it as part of the key name.
If you want to know the default values, you can get a list of used keys with kdb ls /sw/elektra/restbackend/#0. You can then retrieve the configuration value for each key with kdb get <key>, e.g., kdb get /sw/elektra/restbackend/#0/current/backend/jwt/encryption/secret
Additionally to the settings above, CppCMS needs some configuration. All configuration options are listed on their website. A stand-alone installation of the service (without proxy server) requires following configuration:
Note: here we have not used the option -N system because the CppCMS configuration is not part of the specification. That means it does not get validated.
The frontend does only require small mandatory changes in its configuration. Before they can be made, the configuration file has to be mounted though. This can be achieved by issuing kdb mount-rest-frontend-config. The configuration should then be available at system/sw/elektra/restfrontend/#0/current. To get a list of possible configuration parameters, use kdb ls system/sw/elektra/restfrontend/#0/current.
Note that the frontend is not elektrified, only changes within system/sw/elektra/restfrontend/#0/current will work.
The parameters that need to be changed in order for the frontend to work correctly, are:
system/sw/elektra/restfrontend/#0/current/backend/root: set it to the URL where the backend will be reachable, e.g. http://restapi.libelektra.org/ (with trailing slash!)system/sw/elektra/restfrontend/#0/current/website/url: set it to the URL where the frontend will be reachable, e.g. https://libelektra.org/ (with trailing slash!)As last step we need to run the applications:
kdb run-rest-backend. To ensure the backend is accessible, you can use curl http://localhost:8080/version (change port to your setting), which should show you some version information in JSON format.kdb build-rest-frontend to do so.kdb run-rest-frontend. It should now be reachable at the configured port.If everything went smooth, both applications should now be online and reachable.
Both applications can be stopped with a simple command:
kdb stop-rest-backendkdb stop-rest-frontendFor the backend a detailed description in the API blueprint format is available. To compile the blueprint we need the apiary-client to be installed, which in return is installed as Ruby gem:
apt-get install rubygem install apiaryioapiary preview --path=snippet-sharing.apib --output=snippet-sharing-api.html in the blueprints directory to generate the pretty version of the API description. This file can then be placed wherever it is accessible or needed.In case you change the API description (and the backend), you may want to ensure that your API blueprint is still syntax conform. To do so, you can use the tool Drafter. After installing it, you can use drafter <filename> (e.g. drafter snippet-sharing.apib) to run the check.
Of course it is possible to use another webserver instead of the built-in one. To do so, simply run kdb build-rest-frontend and copy the content of the /usr/local/share/elektra/tool_data/rest-frontend/public directory to your desired target location.
It is required that you set a rewrite rule that serves the index.html for every request that does not access a static file (js, css, png, md, etc.). If you omit this step, it will not be possible to use direct links to access resources of the frontend; accessing the frontend from the index.html will still work though.
The following is a description of the setup we used for the Elektra website reachable at https://www.libelektra.org.
We assume that Elektra is now installed to the default path on Debian Jessie, which is /usr/local.
As web server we use Debian Jessie’s Apache2. Several domains are used for different tasks, whereas only two are relevant for the here described service:
restapi.libelektra.org for the API provided by the rest-backendwww.libelektra.org for the website and frontend provided by the rest-frontendThe server redirects requests on port 80 (non-SSL) to 443 using a very simple configuration like
for the www.libelektra.org domain (similar for restapi.libelektra.org).
The secured variant of the configuration looks like
Important is the Directory configuration because the rest-frontend requires the FallbackResource option to function correctly.
For the restapi.libelektra.org domain we use an SCGI setup:
The rest-backend itself is configured normally as described in the configuration section above, but with CppCMS using SCGI instead of HTTP as API variant. This requires setting the keys
Additionally we are using a worker process, which ensures that in case of a crash the backend restarts automatically (= basically supervisor + worker). Config:
Configuration snippets and users are stored at system/configs and system/users:
Because of the Apache server using the rest-frontend installation directory as document root, there is no further configuration necessary other than already explained in the configuration section above.
During the build, the frontend will be recompiled. It is not taken offline for this though and everything that is necessary to accomplish a clean deployment is taken care of by the compile script as well.
The build script basically builds the applications, runs tests, installs everything and restarts the backend. Finally, it can run the configuration script for the frontend, which updates the website content.
The current build script can be found here.
1.8.13