.. _how_to_guides:

How-to guides
=============

Run the example EDG-AF app
--------------------------

The examples in ``example/`` of the EDG-AF repository assume the EDG server:

* is running at ``http://localhost:8080``
* supports basic authentication
* has administrator credentials ``Admin_user/password32``

(The Docker ``edg-samples`` ``docker-compose`` configuration satisfy the requirements.)

See the README's in the respective example directories for information on building and installing the example apps.


Manually install an app into EDG
--------------------------------

**Prerequisites**

* Java 11+
* Maven 3+

**Command**

::

    framework/script/cli upload-zip --app-base-url <APP_URL> --edg-base-url <EDG_URL> --edg-password <EDG_PASSWD> --edg-username <EDG_USER>


Manually create a .zip file for an app to upload into EDG
---------------------------------------------------------

**Prerequisites**

* Java 11+
* Maven 3+

**Command**

::

    framework/script/cli zip --app-base-url <APP_URL> --zip-file-path <ZIP_FILENAME>


Build the EDG App Framework command line interface (CLI) and libraries locally
------------------------------------------------------------------------------

**Prerequisites**

* Java 11+
* Maven 3+

**Building**

::

    framework/script/update


Build the EDG-AF EDG server plugin locally
------------------------------------------

The plugin is not built by default, because it requires non-public dependencies from TopBraid-Suite.

**Prerequisites**

* Java 11+
* Maven 3+

**Install TopBraid-Suite dependencies**

From a TopBraid-Suite checkout::

    /this/repo/framework/plugin/script/install-tbs-dependencies

which ``mvn install`` TopBraid-Suite Java packages into your local Maven repository (i.e., ``~/.m2``).

**Build the plugin**

::

    framework/plugin/script/update

The plugin .jar will be built to `framework/plugin/dist/`.


Using the EDG-AF EDG server plugin
----------------------------------

The plugin .jar must be on the ``CLASSPATH`` of the EDG server web application. If the latter is installed as ``$CATALINA_HOME/webapps/ROOT``, then the plugin .jar should be copied into ``$CATALINA_HOME/webapps/ROOT/WEB-INF/lib``. The .jar should not be in ``$CATALINA_HOME/lib``, because it depends on other .jars in the EDG ``WEB-INF/lib``, which are loaded after ``$CATALINA_HOME/lib``.

The plugin must be configured before EDG server startup. In ``$CATALINA_HOME/conf/catalina.properties`` you can set a system property that tells the plugin the app base URLs::

    edg.appBaseUrls=http://localhost:8081/app-example1,http://localhost:8082/app-example2

At EDG server startup plugin works similarly to the command line: at EDG server startup, the plugin retrieves ``/configuration`` from the app, generates an EDG project, and uploads it to the server.

The plugin uses the standard EDG logging facilities (i.e., ``/var/lib/topbraid/ontologies/logs/tb.log``) to record its progress.