Foxx Manager {#UserManualFoxxManager} ===================================== @NAVIGATE_UserManualFoxxManager @EMBEDTOC{UserManualFoxxManagerTOC} Foxx Applications{#UserManualFoxxManagerIntro} ============================================== Foxx is an easy way to create APIs and simple web applications from within ArangoDB. It is inspired by Sinatra, the classy Ruby web framework. An application built with Foxx is written in JavaScript and deployed to ArangoDB directly. ArangoDB serves this application, you do not need a separate application server. In order to share your applications with the community, we have created a central GitHub repository https://github.com/arangodb/foxx-apps where you can register your applications. This repository also contains the hello world application for Foxx. Applications are managed using the Foxx manager `foxx-manager`. It is similar to tools like `brew` or `aptitude`. First Steps with the Foxx Manager{#UserManualFoxxManagerFirstSteps} =================================================================== The Foxx manager is a shell program. It should have been installed under `/usr/bin` or `/usr/local/bin` when installing the ArangoDB package. An instance of the ArangoDB server must be up and running. unix> foxx-manager Expecting a command, please try: Example usage: foxx-manager install foxx-manager uninstall Further help: foxx-manager help The most important commands are * `install`: Fetches a Foxx application from the central `foxx-apps` repository, mounts it to a local URL and sets it up * `uninstall`: Unmounts a mounted Foxx application and calls its teardown method * `list`: Lists all installed Foxx applications (alias: `installed`) * `config`: Get information about the configuration including the path to the app directory. When dealing with a fresh install of ArangoDB, there should be no installed applications besides the system applications that are shipped with ArangoDB. unix> foxx-manager installed Name Author Description AppID Version Mount Active System --------- ------------------ -------------------------------------------------------- ----------------- -------- ----------------- ------- ------- aardvark Michael Hackstein Foxx application manager for the ArangoDB web interface app:aardvark:1.0 1.0 /_admin/aardvark yes yes --------- ------------------ -------------------------------------------------------- ----------------- -------- ----------------- ------- ------- 1 application(s) found There is currently one application installed. It is called "aardvark" and it is a system application. You can safely ignore system applications. We are now going to install the _hello world_ application. It is called "hello-foxx" - no suprise there. unix> foxx-manager install hello-foxx /example Application app:hello-foxx:1.2.2 installed successfully at mount point /example The second parameter `/example` is the mount path of the application. You should now be able to access the example application under http://localhost:8529/example using your favorite browser. It will now also be visible when using the `installed` command. 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 aardvark Michael Hackstein Foxx application manager for the ArangoDB web interface app:aardvark:1.0 1.0 /_admin/aardvark yes yes ----------- ------------------ -------------------------------------------------------- --------------------- -------- ----------------- ------- ------- 2 application(s) found You can install the application again under different mount path. unix> foxx-manager install hello-foxx /hello Application app:hello-foxx:1.2.2 installed successfully at mount point /hello You now have two separate instances of the same application. They are completely independent of each other. 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 aardvark Michael Hackstein Foxx application manager for the ArangoDB web interface app:aardvark:1.0 1.0 /_admin/aardvark yes yes hello-foxx Frank Celler A simple example application. app:hello-foxx:1.2.2 1.2.2 /hello yes no ----------- ------------------ -------------------------------------------------------- --------------------- -------- ----------------- ------- ------- 3 application(s) found The current version of the application is `1.2.2` (check the output of `installed` for the current version). It is even possible to mount a different version of an application. Now let's remove the instance mounted under `/hello`. unix> foxx-manager uninstall /hello Application app:hello-foxx:1.2.2 unmounted successfully from mount point /hello Note that "uninstall" is a combination of "teardown" and "unmount". This allows the application to clean up its own data. Internally, this will call the application's `teardown` script as defined in the application manifest. Behind the Foxx Manager scenes{#UserManualFoxxManagerBehindScences} =================================================================== 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. 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" then the version 1.2.1 of the application will be downloaded. 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. 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 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! 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`. 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 Example: unix> foxx-manager fetch github arangodb/fugu unix> foxx-manager mount fugu /fugu 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. Example: unix> foxx-manager fetch directory /home/developer/apps/myapp unix> foxx-manager mount myapp /myapp 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 Using Multiple Databases {#UserManualFoxxManagerDatabases} ========================================================== Regular Foxx applications are database-specific. When using multiple databases inside the same ArangoDB instance, there can be different Foxx applications in each database. Every operation executed via the `foxx-manager` is run in the context of a single database. By default (i.e. if not specified otherwise), the `foxx-manager` will work in the context of the `_system` database. If you want the `foxx-manager` to work in the context of a different database, use the command-line argument `--server.database ` when invoking the `foxx-manager` binary. Foxx Applications and Replication {#UserManualFoxxManagerReplication} ===================================================================== Foxx applications consist of a file system part (scripts in the application directory) and a database part. The current version of ArangoDB cannot replicate changes in the file system so installing, updating or removing a Foxx application using `foxx-manager` will not be included in the replication. Foxx Manager Commands {#UserManualFoxxManagerCommands} ====================================================== Use `help` to see all commands unix> foxx-manager help The following commands are available: available lists all Foxx applications available in the local repository config returns configuration information from the server fetch fetches a Foxx application from the central foxx-apps repository into the local repository fetched lists all fetched Foxx applications that were fetched into the local repository help shows this help info displays information about a Foxx application install fetches a Foxx application from the central foxx-apps repository, mounts it to a local URL and sets it up installed alias for the 'list' command list lists all installed Foxx applications mount mounts a fetched Foxx application to a local URL purge uninstalls a Foxx application with all its mounts and physically removes the application directory WARNING: this will remove all data and code of the application! remove alias for the 'purge' command replace replaces an existing Foxx application with the current local version found in the application directory rescan rescans the Foxx application directory on the server side note: this is only required if the server-side apps directory was modified by other processes search searches the local foxx-apps repository setup executes the setup script (app must already be mounted) teardown executes the teardown script (app must be still be mounted) WARNING: this action will remove application data if the application implements teardown! uninstall unmounts a mounted Foxx application and calls its teardown method unmount unmounts a mounted Foxx application without calling its teardown method update updates the local foxx-apps repository with data from the central foxx-apps repository Frequently Used Options {#UserManualFoxxManagerOptions} ======================================================= Internally, `foxx-manager` is a wrapper around `arangosh`. That means you can use the options of `arangosh`. To retrieve a list of the options for `arangosh`, try unix> foxx-manager --help To most relevant `arangosh` options to pass to the `foxx-manager` will be: --server.database database name to use when connecting --server.disable-authentication disable the password prompt and authentication when connecting to the server --server.endpoint endpoint to connect to, use 'none' to start without a server --server.password password to use when connecting --server.username username to use when connecting These options allow you to use the foxx-manager with a different database or with another than the default user. @BNAVIGATE_UserManualFoxxManager