mirror of https://gitee.com/bigwinds/arangodb
Started with a README to get started with Foxx Documentation
This commit is contained in:
Michael Hackstein
parent
799707f657
commit
17cf9fb154
|
|
@ -1,177 +1,66 @@
|
||||||
!CHAPTER Foxx
|
!CHAPTER Foxx
|
||||||
!SUBSECTION Build APIs and simple web applications in ArangoDB
|
|
||||||
|
|
||||||
Foxx is an easy way to create APIs and simple web applications from within
|
TODO: Awesome introduction (micro-service framework)
|
||||||
ArangoDB. It is inspired by Sinatra, the classy Ruby web framework. If
|
|
||||||
Foxx is Sinatra, [ArangoDB's Actions](../ArangoActions/README.md) are the corresponding *Rack*.
|
|
||||||
They provide all the HTTP goodness.
|
|
||||||
|
|
||||||
If you just want to install an existing application, please use the
|
!SECTION Foxx in a nutshell
|
||||||
[Foxx Manager](../FoxxManager/README.md). If you want to create your own application,
|
|
||||||
please continue reading.
|
|
||||||
|
|
||||||
!SUBSECTION Overview
|
This chapter is for the impatient and for the ones that just want to get a quick overview
|
||||||
|
of what Foxx is, how it works and how to get it up and running in short time.
|
||||||
|
It is tutorial that should be solvable in 10 minutes or less and will guide you to your first
|
||||||
|
application giving a few insights on the way.
|
||||||
|
|
||||||
An application built with Foxx is written in JavaScript and deployed to
|
[Read More](Foxx/Nutshell/README.md)
|
||||||
ArangoDB directly. ArangoDB serves this application, you do not need a
|
|
||||||
separate application server.
|
|
||||||
|
|
||||||
Think of an Foxx app as a typical web app similar to any other web app using
|
!SECTION Install a Foxx Application
|
||||||
other technologies. A Foxx app provides one or more URLs, which can either
|
|
||||||
be accessed directly from the browser or from a backend application written e.g. in
|
|
||||||
Ruby or C#. Other features include:
|
|
||||||
|
|
||||||
* *Routing:* Define arbitrary routes namespaced via the *Controllers*
|
You would like to get some inspiration from running Applications?
|
||||||
* *Accesses data:* Direct access to all data in ArangoDB using simple queries, AQL, traversals and more
|
Or you already have an Application that does what you need?
|
||||||
* *Manipulates data:* Create new or manipulate existing entries
|
This chapter will guide you to get an Application up and running.
|
||||||
* Deliver *static files* like HTML pages, CSS or images directly
|
|
||||||
|
|
||||||
The typical request to a Foxx application will work as follows (only conceptually,
|
[Read More](Foxx/Install/README.md)
|
||||||
a lot of the steps are cached in reality):
|
|
||||||
|
|
||||||
1. The request is routed to a Foxx application depending on the mount point
|
!SECTION Develop your own Foxx
|
||||||
2. The according controller of this application is determined (via something called the manifest file)
|
|
||||||
3. The request is then routed to a specific handler in this controller
|
|
||||||
|
|
||||||
The handler will now parse the request. This includes determining all parameters
|
Ready to get to bare metal?
|
||||||
from the body (which is typically JSON encoded) to the path parameters of the URL.
|
In this chapter you will get to know the details on Foxx development.
|
||||||
It is then up to you to handle this request and generate a response. In this process
|
It will explain how to use the development mode and which debugging mechanisms are at hand.
|
||||||
you will probably access the database. This is done via the *Repository*: This is an
|
It introduces the tips and tricks on how to build your own API.
|
||||||
entity that is responsible for a collection and specifically:
|
And presents all libraries that are available from a Foxx Application.
|
||||||
|
|
||||||
1. Creating new entries in this collection
|
[Read More](Foxx/Develop/README.md)
|
||||||
2. Modify or delete existing entries in this collection
|
|
||||||
3. Search for entries in this collection
|
|
||||||
|
|
||||||
To represent an entry in this collection it will use a *Model*, which is a wrapper around
|
|
||||||
the raw data from the database. Here you can implement helper functions or simple access
|
|
||||||
methods.
|
|
||||||
|
|
||||||
!SUBSECTION Your first Foxx app in 5 minutes
|
!SECTION Running Foxx Applications in production
|
||||||
|
|
||||||
Let's build an application that sends a plain-text response
|
This chapter is dedicated to all the possibilities on how to run a Foxx Application in production.
|
||||||
"Hello YourName!" for all requests to */dev/my_app/hello/YourName*.
|
It will start with how to leverage it from development to production.
|
||||||
|
We will continue with migration of the Application to a newer version.
|
||||||
|
|
||||||
First, create a directory *apps* somewhere in your filesystem. This will be
|
[Read More](Foxx/Production/README.md)
|
||||||
the Foxx application base directory for your database instance. Let's assume
|
|
||||||
from now on that the absolute path for this directory is */home/user/apps*.
|
|
||||||
When you have created the directory, create a sub-directory *databases* in it.
|
|
||||||
|
|
||||||
Foxx applications are database-specific, and the *databases* sub-directory is
|
!SECTION Available Foxx Applications
|
||||||
used to separate the Foxx applications of different databases running in the
|
|
||||||
same ArangoDB instance.
|
|
||||||
|
|
||||||
Let's assume for now that you are working in the default database (*_system*), that
|
You do not want to reinvent the wheel?
|
||||||
is used when no [database name](../Glossary/README.html#database_name) is specified otherwise. To use Foxx applications with
|
We neither, therefore we shared some general-use applications, like user- and session-management.
|
||||||
the *_system* database, create a sub-directory *_system* inside the *databases*
|
This chapter will introduce you some of these applications and will give you an introduction on
|
||||||
subdirectory. All Foxx applications for the *_system* database will go into this
|
how to use each of them.
|
||||||
directory. Note: to add a Foxx application for a different databases than *_system*,
|
Some of them can be integrated directly in your own applications.
|
||||||
use the database's name as the directory name instead of *_system*.
|
Others follow the micro-service philosophy and can be added independently.
|
||||||
|
|
||||||
Finally, we can add a sub-directory *my_app* in the *_system* directory and should
|
[Read More](Foxx/Apps/README.md)
|
||||||
end up with the following directory layout (starting at */home/user* in our example):
|
|
||||||
|
|
||||||
```
|
!SECTION Foxx in a cluster
|
||||||
apps/
|
|
||||||
databases/
|
|
||||||
_system/
|
|
||||||
my_app/
|
|
||||||
```
|
|
||||||
|
|
||||||
In the *my_app* directory, create a file named *app.js* and save the following content
|
Ready to scale out?
|
||||||
in it:
|
Want to setup your micro-service based application?
|
||||||
|
This chapter will explain what has to be changed to run a Foxx application within a cluster setup.
|
||||||
|
It will also explain how to move your application from a single server to an unlimited amount of servers.
|
||||||
|
|
||||||
```js
|
[Read More](Foxx/Cluster/README.md)
|
||||||
(function() {
|
|
||||||
"use strict";
|
|
||||||
|
|
||||||
var Foxx = require("org/arangodb/foxx"),
|
!SECTION Advanced features
|
||||||
controller = new Foxx.Controller(applicationContext)
|
|
||||||
|
|
||||||
controller.get("/hello/:name", function(req, res) {
|
|
||||||
res.set("Content-Type", "text/plain");
|
|
||||||
res.body = "Hello " + req.params("name");
|
|
||||||
});
|
|
||||||
|
|
||||||
}());
|
|
||||||
```
|
|
||||||
|
|
||||||
Beside the *app.js* we need a manifest file. In order to achieve that, we
|
|
||||||
create a file called *manifest.json* in our *my_app* directory with the
|
|
||||||
following content:
|
|
||||||
|
|
||||||
```js
|
|
||||||
{
|
|
||||||
"name": "my_app",
|
|
||||||
"version": "0.0.1",
|
|
||||||
"author": "me and myself",
|
|
||||||
"controllers": {
|
|
||||||
"/": "app.js"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
You **must** specify a name and a version number for your application,
|
|
||||||
otherwise it won't be loaded into ArangoDB.
|
|
||||||
|
|
||||||
You should now have the following files and directories with your
|
|
||||||
application (starting at */home/user* in our example):
|
|
||||||
|
|
||||||
```js
|
|
||||||
apps/
|
|
||||||
databases/
|
|
||||||
_system/
|
|
||||||
my_app/
|
|
||||||
manifest.json
|
|
||||||
app.js
|
|
||||||
```
|
|
||||||
|
|
||||||
This is your application, and you're ready to use it.
|
|
||||||
|
|
||||||
!SUBSECTION Testing the application
|
|
||||||
|
|
||||||
Start ArangoDB as follows:
|
|
||||||
|
|
||||||
```js
|
|
||||||
$ arangod --javascript.dev-app-path /home/user/apps /tmp/fancy_db
|
|
||||||
```
|
|
||||||
|
|
||||||
If you chose a different directory name, you need to replace */home/user/apps*
|
|
||||||
with the actual directory name of course. Replace */tmp/fancy_db* with the
|
|
||||||
directory your database data is located in.
|
|
||||||
|
|
||||||
The command will start the ArangoDB server in a **development mode** using the
|
|
||||||
directory */home/user/apps* as the workspace and */tmp/fancy_db* as your
|
|
||||||
database directory. In development mode the server automatically reloads all
|
|
||||||
application files on every request, so changes to the underlying files are
|
|
||||||
visible instantly.
|
|
||||||
Note: if you use the development mode for the first time or choose a different
|
|
||||||
directory for *dev-app-path*, it may be necessary to start ArangoDB with the
|
|
||||||
*--upgrade* option once. This will initialize the specified application directory.
|
|
||||||
|
|
||||||
**Note**: the development mode is convenient when developing applications but the
|
|
||||||
permanent reloading has an impact on performance. Therefore permanent reloading is
|
|
||||||
only performed in development mode and not in production mode. Whenever you think
|
|
||||||
your application is ready for production, you can install it using the Foxx manager
|
|
||||||
and avoid the overhead of reloading.
|
|
||||||
|
|
||||||
Now point your browser to *localhost:8529/dev/my_app/hello/YourName* and you should
|
|
||||||
see "Hello YourName".
|
|
||||||
|
|
||||||
**Note**: the above and all following examples assume that you are using the default
|
|
||||||
database (*_system*).If you use a different database than *_system*, URLs must be
|
|
||||||
changed to include the database name, too. For example, if your database name is
|
|
||||||
*mydb*, the above URL changes to *localhost:8529/_db/mydb/dev/my_app/hello/YourName*.
|
|
||||||
For more information on how to access specific databases, please refer to
|
|
||||||
[Address of a Database](../HttpDatabase/README.md).
|
|
||||||
|
|
||||||
After this short overview, let's get into the details. There are several example
|
|
||||||
apps available on Github. You can install them via Foxx manager (covered in the
|
|
||||||
chapter on Foxx manager) or simply clone them from [github](https://github.com/arangodb/).
|
|
||||||
|
|
||||||
Start with ["hello-foxx"](https://github.com/arangodb/hello-foxx) as it contains
|
|
||||||
several basic usage examples. ["aye-aye"](https://github.com/arangodb/aye-aye)
|
|
||||||
and ["fugu"](https://github.com/arangodb/aye-aye) are more advanced apps showing how
|
|
||||||
to use Backbone, Underscore and Jquery together with Foxx. ["foxx-authentication"](https://github.com/arangodb/foxx-authentication)
|
|
||||||
shows how to register users, log in and check permissions.
|
|
||||||
|
|
||||||
|
This chapter will present the more advanced capabilities of Foxx.
|
||||||
|
It requires that you know the details presented in the chapters before.
|
||||||
|
Here you will learn about foxx feature exports and imports to implement abstract APIs for reuse in several Apps.
|
||||||
|
Furthermore you will learn about background and periodical tasks in foxx applications.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue