!CHAPTER Behind the Foxx Manager scenes In the previous chapter we have seen how to install and uninstall applications. We now go into more details. There are five steps when installing or uninstalling applications. * *fetch* the application from a source * *mount* the application at a mount path * *setup* the application, creating the necessary collections * *teardown* the application, removing the application-specific collections * *unmount* the application When installing an application, the steps "fetch", "mount", and "setup" are executed automatically. When uninstalling an application, the steps "teardown" and "unmount" are executed automatically. !SECTION Installing an application manually We are now going to install the hello world application manually. You can use *search* to find application in your local copy of the central repository. So, first we update our local copy to get the newest versions from the central repository. unix> foxx-manager update Updated local repository information with 4 application(s) You can now search for words with the description of an application. unix> foxx-manager search hello Name Author Description ----------- ------------- ----------------------------------------- hello-foxx Frank Celler This is 'Hello World' for ArangoDB Foxx. ----------- ------------- ----------------------------------------- 1 application(s) found As soon as you know the name of the application, you can check its details. unix> foxx-manager info hello-foxx Name: hello-foxx Author: Frank Celler System: false Description: This is 'Hello World' for ArangoDB Foxx. Versions: 1.1.0: fetch github "fceller/hello-foxx" "v1.1.0" 1.1.1: fetch github "fceller/hello-foxx" "v1.1.1" 1.2.0: fetch github "fceller/hello-foxx" "v1.2.0" 1.2.1: fetch github "fceller/hello-foxx" "v1.2.1" 1.2.2: fetch github "fceller/hello-foxx" "v1.2.2" If you execute unix> foxx-manager fetch github "fceller/hello-foxx" "v1.2.1" the git tag *1.2.1* of the referenced repo will be downloaded and the contents of its *manifest.json* is used to determine the apps' properties. The command *fetched* lists all fetched applications. unix> foxx-manager fetched Name Author Description AppID Version Path ----------- ------------- ------------------------------ --------------------- -------- ----------------- hello-foxx A simple example application. app:hello-foxx:1.2.1 1.2.1 hello-foxx-1.2.1 hello-foxx Frank Celler A simple example application. app:hello-foxx:1.2.2 1.2.2 hello-foxx-1.2.2 ----------- ------------- ------------------------------ --------------------- -------- ----------------- 2 application(s) found We have now two versions of the hello world application. The current version fetched when installing the application using *install* and the one fetched now. Let's now mount the application in version 1.2.1 under */hello*. unix> foxx-manager mount app:hello-foxx:1.2.1 /hello unix> foxx-manager installed Name Author Description AppID Version Mount Active System ----------- ------------------ -------------------------------------------------------- --------------------- -------- ----------------- ------- ------- hello-foxx Frank Celler A simple example application. app:hello-foxx:1.2.1 1.2.1 /hello yes no hello-foxx Frank Celler A simple example application. app:hello-foxx:1.2.2 1.2.2 /example yes no aardvark Michael Hackstein Foxx application manager for the ArangoDB web interface app:aardvark:1.0 1.0 /_admin/aardvark yes yes ----------- ------------------ -------------------------------------------------------- --------------------- -------- ----------------- ------- ------- 3 application(s) found The application is mounted but not yet initialized. If you check the available collections, you will see that there is no collection called *hello_texts*. arangosh> db._collections() [ [ArangoCollection 2965927, "_routing" (type document, status loaded)], [ArangoCollection 96682407, "example_texts" (type document, status loaded)], ... ] A collection *example_texts* exists. This belongs to the mounted application at */example*. If we set-up the application, then the setup script will create the missing collection. unix> foxx-manager setup /hello Now check the list of collections again. arangosh> db._collections() [ [ArangoCollection 2965927, "_routing" (type document, status loaded)], [ArangoCollection 96682407, "example_texts" (type document, status unloaded)], [ArangoCollection 172900775, "hello_texts" (type document, status loaded)], ... ] You can now use the mounted and initialized application. unix> foxx-manager installed Name Author Description AppID Version Mount Active System ----------- ------------------ -------------------------------------------------------- --------------------- -------- ----------------- ------- ------- hello-foxx Frank Celler A simple example application. app:hello-foxx:1.2.2 1.2.2 /example yes no hello-foxx Frank Celler A simple example application. app:hello-foxx:1.2.1 1.2.1 /hello yes no aardvark Michael Hackstein Foxx application manager for the ArangoDB web interface app:aardvark:1.0 1.0 /_admin/aardvark yes yes ----------- ------------------ -------------------------------------------------------- --------------------- -------- ----------------- ------- ------- 3 application(s) found As you can see, there are two instances of the application under two mount paths in two different versions. As the collections are not shared between applications, they are completely independent from each other. !SECTION Uninstalling an application manually Now let us uninstall the application again. First we have to call the teardown script, which will remove the collection *hello_texts*. unix> foxx-manager teardown /hello This will drop the collection *hello_exists*. The application is, however, still reachable. We still need to unmount it. unix> foxx-manager unmount /hello !SUBSECTION Removing all mounts of an application The same application might be mounted multiple times under different mount paths. To get rid of all mounted instances of an application, there is the "purge" command. "purge" will unmount and tear down all mounted instances of the application, and finally will remove the application directory, too. This will remove all data of all instances of the application and also the application directory, code and configured. Use with care! !SECTION Making changes to an existing application There are two options for deploying local changes to an existing application: - the easiest way is to start the server in development mode. This will make all available foxx applications be available in under the */dev/* URL prefix. All changes to the application code will become live instantly because all applications are reloaded on each request to a URL starting with */dev/*. **Note**: that the constant reloading in the development mode has a performance impact so it shouldn't be used in product. - if the development mode is not an option, you can use the *replace* command from foxx-manager. It provides an easy mechanism to re-deploy the code for an already installed application. It can be used as follows: unix> foxx-manager replace hello-foxx /hello The above will re-deploy the code for the application *hello-foxx* which has to be already installed under the */hello* mount point. The application's setup function will be called when invoking *replace* but not *teardown*. !SECTION Installing an application from your own Github repository So far we have installed Foxx applications from the central Github repository "arangodb/foxx-apps". It is also possible to install an application from another repository. This can achieved by using the *fetch* and *mount* commands as follows: unix> foxx-manager fetch github / unix> foxx-manager mount *Examples* unix> foxx-manager fetch github arangodb/fugu unix> foxx-manager mount fugu /fugu !SECTION Installing an application from a local directory You may also install Foxx applications which are already located in the filesystem. Again, you can use the *fetch* command, but with the *directory* type. Note that the directory location must be a directory accessible by the foxx-manager. *Examples* unix> foxx-manager fetch directory /home/developer/apps/myapp unix> foxx-manager mount myapp /myapp !SUBSECTION Installing an application from a zip file It is also possible to install an application contained in a zip file. You can use the *fetch* command again, with the *zip* type. Note that the zip file must be accessible by the foxx-manager. Let's first fetch a zip file. We'll be downloading the fugu application from Github and store it in file *fugu.zip* locally: unix> wget -O fugu.zip "https://github.com/arangodb/fugu/archive/master.zip" Now we can install the application from the zip file: unix> foxx-manager fetch zip ./fugu.zip unix> foxx-manager mount fugu /fugu