Chapter 2. Installation & Update

2.1. Obtain Latest Stable Release

LogicBlox releases new versions about once a month. LogicBlox releases are available from download.logicblox.com

Accompanying release notes highlight which aspects of the platform have improved. The platform is generally back-wards compatible, that is applications written for older versions are expected to also work with newer versions of the platform. For the rare cases that special handling is required for applications while updating the platform, these will also be detailed on the release site.

Even though, application code (eg, LogiQL) should be able to run on new versions unmodified, actual workspaces are (generally) not binary compatible between version upgrades. That means a workspace created by an older version can in general not be opened by a newer version, requiring export and import of EDB data. Having binary-compatibility for workspaces is part of LogicBlox's road-map.

2.2. Binary Installation via tar.gz (64-bit Linux)

If you run a 64-bit flavor of Linux, you can install LogicBlox natively on your machine. The easiest way is to use the binary distribution available as a tar.gz.

System requirements

  • A 64-bit flavor of Linux. Verify that you're running 64-bit Linux by running: uname -m which should return x86_64.

  • At least 8GB of available memory.

  • Python 2.7 or newer (but not Python 3.x). On Ubuntu systems, install via

    $ sudo apt-get install python2.7

    To verify the correct version of python is installed issue python --version.

  • Java version 8 or newer. Available from Oracle's Java website It is also possible to use OpenJDK. To install the required Java on Ubuntu systems, use:

    $ sudo apt-get install openjdk-8-jre

    To verify the correct version of Java is installed check that java -version reports a version starting with 1.8.

Installation steps

  • Download the latest LogicBlox tarball from the LogicBlox release page.

  • Extract the tarball into a directory of your choice. A good location is /opt/logicblox. It is also good habit to create a symbolic link to the active version. Assuming the version you downloaded is 4.1.4:

    $ sudo mkdir /opt/logicblox
    $ cd /opt/logicblox
    $ sudo tar -xzf logicblox-4.1.4.tar.gz
    $ sudo ln -s /opt/logicblox/logicblox /opt/logicblox/logicblox-4.1.4

    Tip

    Simply extracting the contents of the tarball "installs" LogicBlox with default configurations. Custom configurations are performed in a separate location to ease the updating procedure. It is possible to unpack the software to a place that is subsequently mounted read-only to prevent tempering.

  • The archive contains a script to setup all the environment variables required to run LogicBlox. You can source this script to set these up automatically. With bash as shell, do:

    $ source /opt/logicblox/logicblox/etc/profile.d/logicblox.sh

    Tip

    For convenience, you may want to add this line to your shell's startup script, e.g. in ~/.bash_profile or ~/.bashrc.

    To verify the steps so far issue lb status, which should report that the lb-server is currently not running:

    $ lb status
    lb server is OFF

2.3. Managing LogicBlox Services

LogicBloxRequires three daemon processes to be running to be operational. Ideally, these are started, monitored and shut down by the operating system rather than the user.

We detail two methods for managing the daemons. The first method is using the lb services command, which is a simple, portable shell script for managing daemons. This should only be used for development and testing purposes, because this method lacks proper daemon management features that tools for specific Linux distributions provide (systemd, upstart). The second, preferred method explains how to use systemd to manage the LogicBlox daemons.

2.3.1. Manually Starting Services

If daemons are managed by systemd then systemctl should be used to stop and start daemons. The following applies if daemons are managed ad-hoc via lb services.

After performing the installation steps, LogicBlox services need to be started before the LogicBlox server can be used. This is done via:

$ lb services start

An overview of the currently running services should now look like:

$ lb services status
lb-compiler              : OK
lb-server                : OK
lb-web-server            : OK

2.3.2. Manually Stopping Services

If daemons are managed by systemd then the appropriate systemctl commands should be used to stop and start daemons. The following applies if daemons are managed ad-hoc via lb services.

The command lb services stop shuts down all LogicBlox daemons. To list currently running daemons, use lb services print.

Daemons can also be terminated and restarted individually. To terminate individual daemons, use the command stop as shown in the list below; to start use the command start:

lb-server

$ lb server start

$ lb server stop

lb-compiler

$ lb compiler-server start

$ lb compiler-server stop

lb-web

$ lb web-server start

$ lb web-server stop

In rare cases, deamons might hang and not respond to stop requests by lb services. It is then safe (in the sense that the database will not be corrupted) to use OS-level kill instructions to shut down daemons. The PID of the respective processes can be obtained from lb services processes. If processes do not react to kill <pid>, then it is also safe to kill via SIGKILL. If any of the daemons are killed currently running transactions can be aborted. Transactions that have been committed via softcommit mode might not have been written to disk yet and can thus be lost. Any transaction that was committed via diskcommit mode is durable on disk. In any case, killing processes (even with -9 / SIGKILL) does not corrupt LogicBlox workspaces.

2.3.3. Managing Services with Systemd

It is highly recommend to use a system service manager for the management of the database daemons. For recent Linux distributions, this is usually systemd. For older Linux distributions, this could still be upstart. The system service manager of the operating system typically implements robust features to track the process id of the daemons, restart daemons on failures, and properly manage the logs produced by the daemons. For systemd, the services are managed using the systemctl command. Systemd works with journald to manage LogicBlox logfiles that can then be read via journalctl. See the Systemd chapter in this manual for details on using LogicBlox services with systemd.

2.4. Testing Installation

The following hello-world-sequence of commands verifies that lb-server and lb-compiler are working as expected:

$ lb create testworkspace
created workspace 'testworkspace'
$ lb addblock --name firstblock testworkspace 'x(i) -> int(i). double(2*i) <- x(i).'
added block 'firstblock'
$ lb exec testworkspace '+x(21).'
$ lb print testworkspace double 
42
$ lb delete testworkspace 
deleted workspace 'testworkspace'

Tip

The command line tool lb comes with extensive tab-completion capabilities. It completes top-level commands such as addblock or create, workspace names, command options, and even predicate names.

To confirm lb-web is running properly, list available services:

$ lb web-server list --services
--------------- ------------- -------------- ----------------- ----------------- ------- -----------
     Prefix      HTTP Method    Workspace          Groups       Disabled Status   Realm   Endpoints
--------------- ------------- -------------- ----------------- ----------------- ------- -----------
 /lb-web/admin   POST          no workspace   lb:web:internal   enabled                   internal
 /login          POST          login                            enabled

2.5. Update Procedure

To update the installation of LogicBlox, stop running services as described in Section 2.3, “Managing LogicBlox Services”. Then follow the steps for a fresh installation. Here, removing the contents of the old version from /opt/logicblox is safe. All configuration data and workspace data is stored elsewhere. While application code should generally continue to work well on future releases of the LogicBlox platform, actual workspace data stored on disk can generally not be read by different versions of the platform. It is thus necessary to re-deploy and to export and import all data. It is on the future LogicBlox roadmap to address this issue, that is to allow newer versions of the platform to open workspaces created with an older version.

2.6. Trouble Shooting

LogicBlox daemon processes have associated log-files that usually explain the cause of potential errors or problems. For lb services, the logfiles are located under $LB_DEPLOYMENT_HOME/logs/current/. If LB_DEPLOYMENT_HOME is not set, then it defaults to $HOME/lb_deployment. For systemd, consult journalctl.

Lb-web daemon does not start

The logfile for lb-web is lb-web-server.log. A common reason for lb-web not starting is if there are workspaces created with an older version of LogicBlox that are not workspace-binary compatible. If this is the case, removing these workspaces via lb delete <workspacename> would address the problem.

Lb-server does not stop

Stopping the lb-server can sometimes take time as all workspaces will be closed and durably written to disk. Even though transactions are constantly written to disk during normal operation, closing workspaces can sometimes take longer.

However, in rare circumstances lb-server might appear to be idle (no CPU nor I/O performed for a while) and still fail to shut down. These situations are likely caused by software bugs and the LogicBlox team will be thankful for any information that is required to investigate the issue. Information includes stack-traces, log-files and other details about workloads and operations. It is best to contact LogicBlox in these cases. To quickly get operational again, it is OK to use system-level mechanisms to kill lb-server. Besides using SIGTERM, that is kill PID, it is also safe to kill lb-server with the signal SIGKILL, that is kill -9 PID. In both cases, the following will happen:

  • Transactions that are currently in queues will be lost, connections to clients are aborted.

  • Transactions that have not finished committing to disk will likely be lost.

  • The workspace on disk will not be corrupted. In particular, when opened by a fresh lb-server the workspace will be in a state in which all transactions up to a transactions x are committed, whereas transactions that were to be committed after x will not be visible. In particular, for any transaction, either it is fully committed meaning all of its changes have been written to disk, or it never happened meaning none of its changes is visible.

Transaction processing and writing to disk is decoupled meaning that transactions are continuously processed and when no integrity violations appear are continuously applied to the memory-representation of the workspace. In parallel, a committer-component writes the changes to the memory representation to disk, essentially group-committing potentially batched up transactions. The LogicBlox technology ensures that the process of writing changes to disk will always atomically write either all or none of the new transaction data to disk -- even if interrupted at any time.

Transactions can be configured in two modes diskcommit or softcommit. From the engine's point-of-view, they are processed exactly the same way as described above. The only difference is that for diskcommit, the client is notified of the committed transaction when it has been written to disk. Thus, once the client has been notified, even a kill -9 on the server won't prevent the transaction to be applied. If transactions are configured as softcommit then the client is notified as soon as the transaction has been applied to the memory-version of the workspace. It will thus soon after be written to disk. However, sudden failures might prevent this.

In general, both diskcommit and softcommit achieve the same transaction throughput, however transaction latency is generally better with softcommit. We suggest using diskcommit as default and only resorting to softcommit if transactions require very low latencies and it is acceptable that softcommitted transactions are not persisted in the event of failures (power outages, kill -9, etc.).