Anyone who has ever worked with our JavaScript framework Foxx was faced at some point with the challenge to install its Foxx service in its current ArangoDB instance or to replace the installed service with local code changes. This is not a big deal and can easily be done through ArangoDB's WebUI. However, we developers always want to become more productive and clicking through a graphical UI is not the best way. Furthermore, this procedure is almost impossible to use in an automated deployment process. That's why we decided to develop a node-based CLI tool to manage Foxx services, called Foxx-CLI, which we already released in version 1.1.

For all readers who have not tried Foxx until now, shame on you. No, seriously, you should really give it a try. Check out our Getting Started tutorial and come back here if you've written your first little Foxx service and would like to try it out in your running ArangoDB instance. If you have any question, join our #foxx channel in our Slack Community.

For those who are already in love with Foxx, let's get started with the new CLI...

Install

Since the Foxx-CLI is a node module, it is dead-easy to install it by using npm or yarn.

yarn

 yarn global add foxx-cli 

npm

 npm install --global foxx-cli 

Usage

Now we can already start. After you've installed the Foxx-CLI, you should be able to use the Foxx program. You can learn more about the different commands Foxx supports by using the --help flag.

 foxx --help 

Let's take a look at the most essential functionality - installing a Foxx service. For this we first switch to the directory of our Foxx service, where our manifest.json is located, and call the Foxx-CLI with the desired mountpoint, under which our service should be installed and accessible:

 cd my-service

foxx install /hello 

That was easy. By the way, we can install already bundled (zipped) services or specify a URL and download & install the service from there. In order to optimally support the workflow of a developer, it is of course also possible to switch on the development mode via the Foxx-CLI or to replace the installed service with your local files by a single command. Here everyone can work out for themselves the optimal procedure how to use the CLI.

Upgrade service with local files

 foxx upgrade /hello 

Enable development mode

 foxx set-dev /hello 

Bootstrapping

After the initial release 1.0 we have extended the Foxx CLI with the command init, which allows you to bootstrap your Foxx service. This command comes with two additional options which allow you to create your basic service resources based on specific user input or just create an example service.

Create a minimal service in your current working directory

 foxx init 

Create a hello world example service

 foxx init -e 

Answer interactive questions

 foxx init -i 

In addition, it is possible to generate boilerplate code for routers or scripts to your already existing local Foxx service.

Create and add a minimal router

 foxx add router <name>  

Create a router with crud operations for a given collection

 foxx add crud <collection>  

Why a CLI?

As already mentioned, many developers who work regularly with a terminal, prefer to type in their commands and are reluctant to clickclick themselves through a graphical UI. This is also more effective in most cases. But there are other cases where you can reach a technical limit with a WebUI, for example, keyword automation. We live in a time where everyone knows how important testing is. Nowadays, CI (continuous integration) is seen everywhere, and there are enough tools to support it. For some time already, these tools have also been using Docker more and more. For a CI tool or a Docker container, clicking through a WebUI is not an option. Here a CLI tool like Foxx-CLI fits just right.

Docker

Those of you who have run ArangoDB in Docker before may also already know the possibility to run shell scripts at initialization time of its ArangoDB instance within the container. This is the perfect environment in which our new Foxx CLI can unleash its potential. Here it is now possible to easily install your own or third-party Foxx services automatically in your running Docker ArangoDB instance and directly configure it. For some time now we have been offering alpin based Docker images, which are tagged by us as preview and are not officially published. These Docker images already include our Foxx CLI. So if you want you can start right here, but let me say again that this image is a preview release and we can not recommend to use it in production. Create a shell script, e.g. ./init-scripts/install-service.sh with the following content:

 foxx install /hello /opt/foxx-service 

When running a Docker container, based on our image arangodb/arangodb-preview:3.3, mount your shell script to /docker-entrypoint-initdb.d and your Foxx service directory to the one used in your shell script.

docker run -e ARANGO_RANDOM_ROOT_PASSWORD=1 -p 8529:8529 \
-v $(pwd)/init-scripts:/docker-entrypoint-initdb.d \
-v $(pwd)/my-service:/opt/foxx-service \
arangodb/arangodb-preview:3.3

After running this command you should see the following output:

Initializing root user...Hang on...
Initializing database...Hang on...
/entrypoint.sh: running /docker-entrypoint-initdb.d/install-service.sh
Installed service at "/hello".
Database initialized...Starting System...

Congrats, you have successfully started a Docker container with a running ArangoDB instance with your Foxx service installed.

Future Plans

We are currently in the process of planning and implementing additional functionality which hopefully further simplifies your life with Foxx. To not create stuff you guys don't need, feedback is really appreciated to guide our efforts. Feel free to open feature requests, send us ideas and any other feedback on GitHub.