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.

Installation steps

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:

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:

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:

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.).