> The Qabel Desktop Client

This project provides a Desktop Client for currently targeting Windows. It is a small part of the qabel platform.

Introduction | Getting Started | Usage | Structure | Contribution

Introduction

For a comprehensive documentation of the whole Qabel Platform use https://qabel.de as the main source of information. http://qabel.github.io/docs/ may provide additional technical information.

Qabel consists of multiple Projects:

• Qabel Android Client
• Qabel Core is a library that includes the common code between both clients to keep them consistent
• Qabel Drop Server is the target server for drop messages according to the Qabel Drop Protocol
• Qabel Accounting Server manages Qabel-Accounts that authorize Qabel Box usage according to the Qabel Box Protocol
• Qabel Block Server serves as the storage backend according to the Qabel Box Protocol

Install

Distributions for Windows (and Android) are provided by the official Qabel website at https://qabel.de/de/download . Everything below this line describes the usage of the Qabel Desktop Client for development purposes.

Changing server URLs

Even when using the official Qabel Desktop Client distribution, the URLs used for drop-, accounting- and blockserver may be changed. To do so, create a file named launch.properties in the working directory (where the QabelDesktop.exe lies) with a content like this:

drop.url=https://drop.qabel.org
accounting.url=https://accounting.qabel.org
block.url=https://block.qabel.org

this will override the default URLs.

If that doesn't work for you for any reason, you need to follow the long way with Usage

Usage

preconditions

• to build the java code, you need an OracleJDK 1.8 u67 or higher
• to run the server locally, you should have Vagrant and docker installed

start up vagrant

Start the servers in the vagrant vm with vagrant up.

build it

The build is using gradle to compile the code, run all tests and assemble the jar.

• run the gradle-based build with ./gradlew build

The tests require an X-Server to be running. The Vagrantfile enables X-Forwarding to allow using X inside the VM. If problems occur, you can alternatively use XVFB to create a virtual framebuffer and run the tests headless:

xvfb-run -a -s "-screen scrn 1280x1024x8" ./gradlew test

modules

The Qabel Desktop Client provides the following modules:

• client: contains the actual sources and all tests without GUI interactions
• guiTest: contains the GUI tests (those that actually move, hover or click in the UI)
• debugLauncher: contains options to launch the Client with debug tools or parts of the gui standalone

build targets

./gradlew accepts different targets. The (probably) most important ones are:

• client:test: run the unit tests (Tests that don't start a GUI)
• testGui:test: run the gui tests (Tests tat start a real GUI and use mouse actions to test it)
• jar: create a JAR with the compile qabel-desktop code but no dependencies
• distZip: create a zip file containing all dependencies (like libcurve) and start-scripts
• client:run: start the desktop-client
• downloadLicenses: downloads licenses from dependencies and generates an overview at build/reports
• lock: locks current dependencies to exact versions

creating a versioned release

When the release property is set, the gradle uses that version for the meta information. ./gradlew -Prelease=0.5.1 distZip This is also used by the script building the windows installer.

Creating the Windows Setup

From the installer directory you can create a versioned setup with

bash build-setup.sh {version}

and {version} needs to be a version of the form x.y.z. SemVer compatible prefixes or suffixes are currently not supported because the version is passed directly to launch4j which cannot handle that. Example:

bash build-setup.sh 0.5.1

This script will:

• download the JRE
• download Inno Setup
• download launch4j
• create a distribution with ./gradlew -Prelease={version} distZip
• create a wrapping launcher .exe for the jar
• build the setup

creating a dev-release using Vagrant

vagrant up installer    # starts a docker container via vagrant building a setup
docker ps | grep installer | cut -d' ' -f1 | xargs docker logs -f     # tails the containers logs

creating the windows setup manually

The installer dir includes two config files to create an installer for Windows:

1. launch4j.xml which can be used with launch4j to create the desktopLaunch4j.exe (launcher)
2. config.iss which can be used with Inno Setup to create the QabelSetup.exe (setup)

To do so, you need to prepare the following directory structure:

installer
├───dist        (extracted content from `build/distributions/*.zip` after `gradlew -Prelease={version} distZip`
│   ├───bin
│   └───lib
├───jre         (jre folder, >= Java8u67)
│   ├───bin
│   └───lib
└───launch4j    (extracted launch4j windows zip distribution)
     ├───bin
     ├───...

And you need to install Inno Setup 5. Then you can do the following steps to create your setup:

• java -jar launch4j/launch4j.jar launch4j.xml to create the launcher
• ISCC config.iss to create the setup containing the launcher, the jre and the Qabel distribution

If you haven't configured your PATH to include ISCC, you need to use the full path to the ISCC.exe. For example: "C:\Program Files (x86)\Inno Setup 5\ISCC.exe" config.iss

using the jar

The Qabel Desktop Client requires libcurve to do the crypto stuff in C. You can find the according lib at libs/*curve25519* they have been build using the Qabel Core. When running the jar, you need to reference this dir to allow Java to find it:

java -Djava.library.path=libs -jar qabel-desktop-dev.jar

adjust the path relative to the path you are running the command from.

Structure

• the configuration is stored in a sqlite file named db.sqlite
• Because JavaFX with FXML uses magic injections anyways, the Contollers for all JavaFX-Views get their properties by magic javax.inject implemented by Afterburner.FX

box sync architecture

+---------------------------+      +----------------------------------+
|  local fs notifications   |      |  remote fs notifications (poll)  |
+-------------------------+-+      +-+--------------------------------+
                          |          |
                          v  update  v

                          +----------+
                          |  Syncer  |
              +---------- +----------+ <------------+
 up-/download | schedules                    checks |
              v                                     v

+------------------------+   update   +-------------------------------+
|      LoadManager       | ---------> |           SyncIndex           |
+------------------------+            +-------------------------------+

One syncer is started per BoxSyncConfig. Both, the local and the remote filesystem send notifications of changed files to the syncer. Remotely, a poller let's the BoxNavigations update itself every few seconds and they will notify the syncer if a change happened. The syncer checks it's SyncIndex for information about the changed file (to prevent event loops, like a download triggering a local fs event). If everything is fine, the Syncer schedules a transaction (up- or download) at the central LoadManager that executes these transactions synchronously. Once finished, the LoadManager updates the SyncIndex (per callback) to store the current state of synchronization. The SyncIndex is persisted on change to allow detection of events that occured during a clients offline period.

Contribution

For issues using the Qabel Desktop Client, use the feedback button () inside the application.

Otherwise, use the Issue tracker of GitHub.

Please read the contribution guidelines at https://github.com/Qabel/qabel-core/blob/master/CONTRIBUTING.md carefully and don't forget to keep a keep a changelog.