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
|
||||
!SUBSECTION Build APIs and simple web applications in ArangoDB
|
||||
|
||||
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. If
|
||||
Foxx is Sinatra, [ArangoDB's Actions](../ArangoActions/README.md) are the corresponding *Rack*.
|
||||
They provide all the HTTP goodness.
|
||||
TODO: Awesome introduction (micro-service framework)
|
||||
|
||||
If you just want to install an existing application, please use the
|
||||
[Foxx Manager](../FoxxManager/README.md). If you want to create your own application,
|
||||
please continue reading.
|
||||
!SECTION Foxx in a nutshell
|
||||
|
||||
!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
|
||||
ArangoDB directly. ArangoDB serves this application, you do not need a
|
||||
separate application server.
|
||||
[Read More](Foxx/Nutshell/README.md)
|
||||
|
||||
Think of an Foxx app as a typical web app similar to any other web app using
|
||||
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:
|
||||
!SECTION Install a Foxx Application
|
||||
|
||||
* *Routing:* Define arbitrary routes namespaced via the *Controllers*
|
||||
* *Accesses data:* Direct access to all data in ArangoDB using simple queries, AQL, traversals and more
|
||||
* *Manipulates data:* Create new or manipulate existing entries
|
||||
* Deliver *static files* like HTML pages, CSS or images directly
|
||||
You would like to get some inspiration from running Applications?
|
||||
Or you already have an Application that does what you need?
|
||||
This chapter will guide you to get an Application up and running.
|
||||
|
||||
The typical request to a Foxx application will work as follows (only conceptually,
|
||||
a lot of the steps are cached in reality):
|
||||
[Read More](Foxx/Install/README.md)
|
||||
|
||||
1. The request is routed to a Foxx application depending on the mount point
|
||||
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
|
||||
!SECTION Develop your own Foxx
|
||||
|
||||
The handler will now parse the request. This includes determining all parameters
|
||||
from the body (which is typically JSON encoded) to the path parameters of the URL.
|
||||
It is then up to you to handle this request and generate a response. In this process
|
||||
you will probably access the database. This is done via the *Repository*: This is an
|
||||
entity that is responsible for a collection and specifically:
|
||||
Ready to get to bare metal?
|
||||
In this chapter you will get to know the details on Foxx development.
|
||||
It will explain how to use the development mode and which debugging mechanisms are at hand.
|
||||
It introduces the tips and tricks on how to build your own API.
|
||||
And presents all libraries that are available from a Foxx Application.
|
||||
|
||||
1. Creating new entries in this collection
|
||||
2. Modify or delete existing entries in this collection
|
||||
3. Search for entries in this collection
|
||||
[Read More](Foxx/Develop/README.md)
|
||||
|
||||
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
|
||||
"Hello YourName!" for all requests to */dev/my_app/hello/YourName*.
|
||||
This chapter is dedicated to all the possibilities on how to run a Foxx Application in production.
|
||||
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
|
||||
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.
|
||||
[Read More](Foxx/Production/README.md)
|
||||
|
||||
Foxx applications are database-specific, and the *databases* sub-directory is
|
||||
used to separate the Foxx applications of different databases running in the
|
||||
same ArangoDB instance.
|
||||
!SECTION Available Foxx Applications
|
||||
|
||||
Let's assume for now that you are working in the default database (*_system*), that
|
||||
is used when no [database name](../Glossary/README.html#database_name) is specified otherwise. To use Foxx applications with
|
||||
the *_system* database, create a sub-directory *_system* inside the *databases*
|
||||
subdirectory. All Foxx applications for the *_system* database will go into this
|
||||
directory. Note: to add a Foxx application for a different databases than *_system*,
|
||||
use the database's name as the directory name instead of *_system*.
|
||||
You do not want to reinvent the wheel?
|
||||
We neither, therefore we shared some general-use applications, like user- and session-management.
|
||||
This chapter will introduce you some of these applications and will give you an introduction on
|
||||
how to use each of them.
|
||||
Some of them can be integrated directly in your own applications.
|
||||
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
|
||||
end up with the following directory layout (starting at */home/user* in our example):
|
||||
[Read More](Foxx/Apps/README.md)
|
||||
|
||||
```
|
||||
apps/
|
||||
databases/
|
||||
_system/
|
||||
my_app/
|
||||
```
|
||||
!SECTION Foxx in a cluster
|
||||
|
||||
In the *my_app* directory, create a file named *app.js* and save the following content
|
||||
in it:
|
||||
Ready to scale out?
|
||||
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
|
||||
(function() {
|
||||
"use strict";
|
||||
[Read More](Foxx/Cluster/README.md)
|
||||
|
||||
var Foxx = require("org/arangodb/foxx"),
|
||||
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.
|
||||
!SECTION Advanced features
|
||||
|
||||
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