search

Qabel / qabel-desktop

(B2C) :computer: Desktop frontend of Qabel
Other
11 stars 12 forks source link

readme

The Qabel Desktop Client

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



Introduction | Getting Started | Usage | Structure | Contribution

Introduction

screenshot

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:

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

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.

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:

build targets

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

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:

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:

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

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 (feedback icon) 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.