Easily Spin Up an ArangoDB Foxx Microservice

ascii fox

At the end you will have:

  • A microservice
  • Unit tests passed
  • Integration tests passed
  • Swagger doc
  • Ready to build your own app on it!

If you don’t have ArangoDB yet you can download it and follow along.

git clone https://gitlab.com/tcrowe/foxx-template.git
cd foxx-template
npm install
cp .env-example .env

The .env file has the URL, username, password, and database. For this example we’re using a test database setup manually.

⚠️ This will upload and overwrite the microservice into ArangoDB in development mode.

npm run dev

Output

logged into arangodb as test
foxx service updated c49ee48f
http://127.0.0.1:8529/_db/test/foxx-template
/opt/arangodb/js/apps/_db/test/foxx-template/APP
suites 3 tests 2 passes 2 pending 0 failures 0 duration 399ms
unit tests 1/1
    ok rootHandler
integration tests 1/1
    ok router initialized

What just happened there?

Webpack has logged in to ArangoDB using arangojs. It built the source, zipped it, and uploaded it to ArangoDB. It ran the unit tests, integration tests, and the output above is what you would see.

The service appears in the list.
The readme from your repo displays.
Foxx service swagger docs generated.
JSON output if you call it via the service API.
The tests also run in the GUI.
Scripts are available in the menu.

⚠️ When ready push to production.

npm run prd

We get a lot of visibility on those things in the images but it’s not clear yet a convenient way to get the console.log outputs generated in the service and scripts. If you know please send me a message.

Why Webpack?📎

Normally when you deploy a Foxx microservice you’re providing a directory with the files or a zip. The zip is sent up to ArangoDB and then the lifecycle scripts run. There is a list of modules from the node JS community which are available to each Foxx service. In addition services can have other services as dependencies. For many uses that will be sufficient and no change would need to be made.

Here the main service, lifecycle setup and teardown, and scheduled tasks are bundled along with their dependencies. Webpack is serving the purpose to tap into all the node/npm modules. And then special care is taking not to use async callbacks and Promises in those modules. If you’re particular about your modules, or you’re using different versions from ArangoDB, or you have libraries your team uses, then Webpack will facilitate those cases.

Beyond that you could start adding in your babel loader or your TypeScript loader and use more of the language features you prefer. (Or livescript 🧐) It makes sense that at some point your team will likely want to add some tooling as the complexity of the code and reliance on the features of ArangoDB grow.

Built-in modules are marked external in webpack and they do not need to be installed in your project.

Comparing with foxx-cli deploy📎

Underneath a set of webpack plugins is doing a service upgrade like foxx-cli is doing.

foxx upgrade /foxx-template --server http://127.0.0.1:8529 \
  --database test --username test --password-file passtest \
  --dev --setup
# Upgraded service at "/foxx-template".

As an aside, –password is currently enforcing a different password validation than ArangoDB and different than –password-file. 🤔

foxx test /foxx-template --server http://127.0.0.1:8529 \
  --database test --username test --password-file passtest

#  unit tests
#    ✓ rootHandler (0ms)
#
#  integration tests
#    ✓ router initialized (264ms)
#
#
#  2 passing (265ms)

At the time of writing the template v0.1.0 it wasn’t clear to me yet all the capabilities of foxx-cli. It’s not necessary to publish modules via the webpack plugins but I personally wanted to understand how it works which is very simple.

Sometimes I’m having the Foxx services built in a CI/CD system and they don’t have access to ~/.foxxrc because they are a system user. A lot of times with the CI/CD systems there is some scheme set up providing secrets into .env. Or in Kubernetes some virtual drive is mounted into the containers. It’s not obvious to me yet how I can integrate those cases with foxx-cli.

Testing📎

Watch how easy it is to create a test. I run BDD style but you can do TDD and expect with a minimal change. Tests are built-in to Foxx framework.

require("chai").should();
const { rootHandler } = require("../../src/index");

describe("unit tests", function () {
  it("rootHandler", function () {
    rootHandler(null, {
      json(op) {
        op.name.should.be.a("string");
      }
    });
  });
});

✅ Done

Future of Foxx microservice deployments📎

It’s easy and convenient to do these kinds of deployments over HTTP. After learning more about how it works I can see some additional use cases for Webpack and Foxx combinations. Even if it’s not actually simpler in totality it would seem simpler if most of the team members do not have to edit the build scripts.

  • TypeScript, Babel+JS, CoffeeScript transpiled
  • import modules
  • Deploy an HTML static sites straight into a Foxx service instead of having to deal with ssh or scp.
  • Generate a static site using template engines from npm and data available inside the database. Think “JAMStack” in Foxx.
  • Dynamic sites using template engine and data in the databases.
  • Combine Webpack and foxx-cli instead of Webpack plugins.
  • Document JSON Schema conformity checker using jsonschema module in synchronous mode.
  • How can we get the console.log output from ArangoDB?
  • How to debug, breakpoints, and profile?
  • Dazzle our dev friends with Redoc swagger & openapi visualizer.
  • Is there a tool to analyze the swagger json and provide suggestions?
  • Versioned service increment e.g. /foxx-template-v0.1.0 ++
  • Synchronize individual files instead of zip.
  • Turn ArangoDB into a FaaS(Functions as a Service)
  • Maybe WASM will go in.

There are some things webpack and tooling can do which we would never want to integrate into foxx-cli. It doesn’t make sense to bloat foxx-cli with everything we want. Webpack can handle all our bloat. 😉


I encourage you to go over to the repository and make an issue with your ideas and corrections or over to contact. Thanks for having a read and I look forward to the feedback.