mirror of https://gitee.com/bigwinds/arangodb
268 lines
14 KiB
Markdown
268 lines
14 KiB
Markdown
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`
|
|
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 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
|
|
* `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 delivered with ArangoDB.
|
|
|
|
unix> foxx-manager list
|
|
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 `list` command.
|
|
|
|
unix> foxx-manager list
|
|
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 to separated instances of the same application. They are
|
|
completely independent of each other.
|
|
|
|
unix> foxx-manager list
|
|
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 `list`
|
|
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
|
|
|
|
Behind the Foxx Manager scenes{#UserManualFoxxManagerBehindScences}
|
|
===================================================================
|
|
|
|
In the previous chapter we have seen how to install and install 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 application.
|
|
|
|
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 list
|
|
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 list
|
|
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
|
|
|
|
Frequently Used Options {#UserManualFoxxManagerOptions}
|
|
=======================================================
|
|
|
|
Use `help` to see all options
|
|
|
|
unix> foxx-manager help
|
|
|
|
The following commands are available:
|
|
fetch fetches a foxx application from the central foxx-apps repository into the local repository
|
|
mount mounts a fetched foxx application to a local URL
|
|
setup setup executes the setup script (app must already be mounted)
|
|
install fetches a foxx application from the central foxx-apps repository, mounts it to a local URL and sets it up
|
|
teardown teardown execute the teardown script (app must be still be mounted)
|
|
unmount unmounts a mounted foxx application
|
|
uninstall unmounts a mounted foxx application and calls its teardown method
|
|
purge physically removes a foxx application and all mounts
|
|
list lists all installed foxx applications
|
|
fetched lists all fetched foxx applications that were fetched into the local repository
|
|
available lists all foxx applications available in the local repository
|
|
info displays information about a foxx application
|
|
search searches the local foxx-apps repository
|
|
update updates the local foxx-apps repository with data from the central foxx-apps repository
|
|
help shows this help
|