Development mode for Foxx services

Development mode allows developers to make changes to deployed services in-place directly on the database server’s file system without downloading and re-uploading the service bundle. This can help during rapid development of service prototypes or diagnosing complex problems.

You can toggle development mode on and off using the Foxx CLI, the HTTP API or in the service settings tab of the web interface.

To find out where a service’s active source files are stored, check the service settings in the web interface or the service details when using the Foxx CLI or HTTP API. The root folder for all services can also be set explicitly by overriding the javascript.app-path option in the ArangoDB configuration.

In development mode the service’s source files and manifest will be re-evaluated, and its setup script (if present) re-executed, every time a route of the service is accessed, effectively re-deploying the service on every request. Additionally, error responses generated by Foxx will include stacktraces and when viewed in a browser may include relevant sections of the service code that generated the error.

To avoid losing your changes, we recommend using a tool like lsyncd  to synchronize changes from your local working copy to the service files continuously rather than modifying those files directly. Alternatively you can easily re-deploy your local copy of the service using the Foxx CLI.

There are a number of caveats you should be aware of when using development mode:

  • the additional information provided in error responses can leak critical information like source code and file system paths

  • parallel requests may result in race conditions as the setup script may be executed in multiple threads in parallel (outside development mode the setup would only be executed in one thread)

  • the setup script will likely be executed numerous times, although using additional migration scripts may help avoiding some of the added overhead

  • if you are serving static files, keep in mind that requests to these files will still result in a re-deployment of the service

  • making HTTP requests to the service via @arangodb/request (e.g. as part of an integration test) also results in re-deployment, which can result in inconsistent behavior

  • the service files should be treated as highly volatile as they will be erased if the service is uninstalled/replaced or the database removed

For these reasons we strongly advise against using development mode on production servers.

In a cluster

Using development mode in a production cluster is extremely unsafe and highly discouraged.

Development mode in a cluster applies to each Coordinator individually. Changes to the service’s file system on a single Coordinator will be reflected as usual but only on that single Coordinator. When development mode is disabled on one Coordinator, it will create a new service bundle from the local changes and distribute it across the cluster to the other Coordinators.

This can result in problems when service code is modified on multiple Coordinators. Development mode should therefore only be used for diagnostic purposes and avoided if possible.