Clarabot Nano
=====

Nano is the client-side component of the privacy-first hybrid file sharing system developed at Clarabot. The goal of
the system is to provide the users with ease of use while allowing them custody over their data and storage.

For copyright and legal information see the `LICENSE.md` file.

Architecture
-----

The Nano application has a service oriented architecture. Each type of process has their responsibilities.
See `docs/architecture-overview.md` for more information and details.

Running from source installation
-----
When installing from source tarballs the following dependencies are necessary:

 - Python 3.10 (with cryptography, virtualenv and sqlite support)
 - Build tools of the platform for compiling C extensions
 - Development build of protobuf to link against (if no bdist package of gcld3 dependency is available)
 - Development build of wxWidgets to link against (if no bdist package of wxPython dependency is available)
 - OpenJDK 11 aka Java
 - Apache Solr 8.11.2
 - Apache Tika 2.6.0

The versions are recommendations based on what the software is developed and tested with.

The first five in the list shall be installed by the package manager of the platform or distribution usually.

### Installation guide

After all platform dependencies are ready, create the environment of the application:

1. Create a new virtualenv to work with: `python3.10 -m venv <location>`
2. Activate it (example assumes bash-like shell): `source <location>/bin/activate`
3. Install wheel before all: `pip install wheel`
4. Install Nano into the venv. Java must be in PATH already to compile the Picoture extension.
   
   To install all and use the newest available dependencies: `pip install -U clarabot-nano-1.1.0-src.tgz -U clarabot-crypto-1.0.1-src.tgz`
   
   Alternatively the `--no-deps` flag can be utilized when installing the clarabot-* packages, and the frozen requirements may be installed by `pip-tools`:
    - `pip install pip-tools`
    - `tar -xf clarabot-nano-1.1.0-src.tgz --wildcards requirements/*.txt`
    - `pip-sync requirements/base.linux.txt` where `linux` may be replaced by `win` for Windows or `darwin` for macOS

5. Starting Nano now will complain about missing external dependencies: `python -m clarabot_nano`

   The error dialog will say something like *"Without Nano bundle root (CBNANO_ROOT), the local.solr_bundle_dir config must be set"* at the bottom.
   The example basically means that Solr is not found, but the missing dependency could be Java or Tika as well.
   
6. There are multiple ways to provide the external dependencies to Nano.
   - If Java, Solr and Tika will be used by the Nano exclusively, then they may be put into a directory like they would be in bundled distribution.
     
     The OpenJDK and Solr distribution package needs to extracted, while a Tika standalone server JAR needs to be put into a directory.
     The directory structure of the bundle root needs to be made to match up with these files:

     ```
     <bundle-root>/deps/jre/bin/java
     <bundle-root>/deps/solr/server/start.jar
     <bundle-root>/deps/tika/tika-server-standard-2.6.0.jar
     ```
     
     To make nano use the created bundle-root set it as the environment variable `CBNANO_ROOT`.

   - If there are already suitable installations somewhere, the `local.yml` config can be modified to specify them explicitly.
     
     Usually it can be found at:
      - Linux: `~/.config/clarabot/nano/local.yml` 
      - macOS: `~/Library/Preferences/clarabot/nano/local.yml`
      - Windows: `~\AppData\Local\clarabot\config\nano\local.yml`

     The `java_dir` or `JAVA_HOME` environment variable needs to be set, so `bin/java` is found relative to it.
     The `solr_bundle_dir` needs to be set, so `server/start.jar` is found relative to it.
     The `tika_bundle_dir` needs to be set, so `tika-server-standard-2.6.0.jar` for example, is found relative to it.
     
   Java is also looked for, in the PATH if nothing else matches.

7. Successfully providing the dependencies, Nano can start. For example when I use the development bundle root it works: `CBNANO_ROOT=~/.local/share/devtest/root python -m clarabot_nano`

8. For automatic start, the distribution's session or service manager should be utilized.
