21 KiB
Foxx Manager
@NAVIGATE_UserManualFoxxManager @EMBEDTOC{UserManualFoxxManagerTOC}
Foxx Applications
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
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> <mount-point>
foxx-manager uninstall <mount-point>
Further help:
foxx-manager help
The most important commands are
install: Fetches a Foxx application from the centralfoxx-appsrepository, mounts it to a local URL and sets it upuninstall: Unmounts a mounted Foxx application and calls its teardown methodlist: 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
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.
fetchthe application from a sourcemountthe application at a mount pathsetupthe application, creating the necessary collectionsteardownthe application, removing the application-specific collectionsunmountthe 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
replacecommand 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 /helloThe above will re-deploy the code for the application
hello-foxxwhich has to be already installed under the/hellomount point. The application's setup function will be called when invokingreplacebut notteardown.
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 <username>/<repository>
unix> foxx-manager mount <app-id> <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
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 <database-name> when invoking
the foxx-manager binary.
Foxx Applications and Replication
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
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
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 <string> database name to use when connecting
--server.disable-authentication <bool> disable the password prompt and authentication when connecting to the server
--server.endpoint <string> endpoint to connect to, use 'none' to start without a server
--server.password <string> password to use when connecting
--server.username <string> 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