alihan/fn-serverless
1
0
Fork 0
mirror of https://github.com/fnproject/fn.git synced 2022-10-28 21:29:17 +03:00
Code Issues Packages Projects Releases Wiki Activity

Cleaning up docs

Browse Source
This commit is contained in:
Travis Reeder
2017-05-25 03:08:40 +00:00
committed by Chad Arimura
parent acb2af526b
commit d115ad6d45
6 changed files with 192 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
README.md
View File

@@ -7,7 +7,7 @@ Welcome to Oracle Functions! The open source serverless platform.
## What is Oracle Functions?
Oracle Functions is an open source serverless platform, or as we like to refer to it, Functions as a
Oracle Functions is an open source [serverless](serverless.md) platform, or as we like to refer to it, Functions as a
Service (FaaS) platform that you can run anywhere.
* Write once
@@ -20,42 +20,6 @@ Service (FaaS) platform that you can run anywhere.
* Easy to manage [for operators](docs/README.md#for-operators)
* Written in [Go](https://golang.org)
## What is Serverless/FaaS?
Serverless is a new paradigm in computing that enables simplicity, efficiency and scalability for both developers
and operators. It's important to distinguish the two, because the benefits differ:
### Benefits for developers
The main benefits that most people refer to are on the developer side and they include:
* No servers to manage (serverless) -- you just upload your code and the platform deals with the infrastructure
* Super simple coding -- no more monoliths! Just simple little bits of code
* Pay by the milliseconds your code is executing -- unlike a typical application that runs 24/7, and you're paying
24/7, functions only run when needed
Since you'll be running Oracle Functions yourself, the paying part may not apply, but it does apply to
cost savings on your infrastructure bills as you'll read below.
### Benefits for operators
If you will be operating Oracle Functions (the person who has to manage the servers behind the serverless),
then the benefits are different, but related.
* Extremely efficient use of resources
* Unlike an app/API/microservice that consumes resources 24/7 whether they
are in use or not, functions are time sliced across your infrastructure and only consume resources while they are
actually doing something
* Easy to manage and scale
* Single system for code written in any language or any technology
* Single system to monitor
* Scaling is the same for all functions, you don't scale each app independently
* Scaling is simply adding more Oracle Functions nodes
There is a lot more reading you can do on the topic, just search for
["what is serverless"](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=what%20is%20serverless)
and you'll find plenty of information.
## Join Our Community
TODO: Slack or Discord community.
@@ -69,22 +33,24 @@ This guide will get you up and running in a few minutes.
* Docker 17.05 or later installed and running
* Logged into Docker Hub (`docker login`)
### Run Oracle Functions
To get started quickly with Oracle Functions, just fire up a `treeder/functions` container:
# UNTIL THIS IS PUBLIC, YOU'LL NEED TO BUILD AND RUN THE CODE FROM THIS REPO
```sh
docker run --rm -it --name functions -v ${PWD}/data:/app/data -v /var/run/docker.sock:/var/run/docker.sock -p 8080:8080 treeder/functions
# install cli tool
cd fn
make dep # just once
make install
# Start server:
cd ..
make dep # just once
make run
```
*where ${PWD}/data is the directory where the functions application data files will be stored*
<!-- ADD BACK ONCE PUBLIC
This will start Oracle Functions in single server mode, using an embedded database and message queue. You can find all the
configuration options [here](docs/operating/options.md). If you are on Windows, check [here](docs/operating/windows.md).
### Install CLI tool
### CLI tool
Install the Oracle Functions CLI tool:
This isn't required, but it sure makes things a lot easier. Just run the following to install:
```sh
curl -LSs https://goo.gl/KKDFGn | sh
@@ -92,6 +58,19 @@ curl -LSs https://goo.gl/KKDFGn | sh
This will download a shell script and execute it. If the script asks for a password, that is because it invokes sudo.
### Run Oracle Functions Server
To get started quickly with Oracle Functions, just fire up a functions container:
```sh
fn start
```
This will start Oracle Functions in single server mode, using an embedded database and message queue. You can find all the
configuration options [here](docs/operating/options.md). If you are on Windows, check [here](docs/operating/windows.md).
-->
### Write a Function
Functions are small, bite sized bits of code that do one simple thing. Forget about monoliths when using functions,
@@ -147,137 +126,9 @@ To update your function:
fn deploy myapp
```
See below for more details. And you can find a bunch of examples in various languages in the [examples](examples/) directory. You can also
See the [documentation](docs/README.md) for more information. And you can find a bunch of examples in various languages in the [examples](examples/) directory. You can also
write your functions in AWS's [Lambda format](docs/lambda/README.md).
## Usage
This is a more detailed explanation of the main commands you'll use in Oracle Functions as a developer.
### Create an Application
An application is essentially a grouping of functions, that put together, form an API. Here's how to create an app.
```sh
fn apps create myapp
```
Or using a cURL:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"app": { "name":"myapp" }
}' http://localhost:8080/v1/apps
```
[More on apps](docs/apps.md).
Now that we have an app, we can route endpoints to functions.
### Add a Route
A route is a way to define a path in your application that maps to a function. In this example, we'll map
`/hello` to a simple `Hello World!` function called `treeder/hello` which is a function we already made that you
can use -- yes, you can share functions! The source code for this function is in the [examples directory](examples/hello/go).
You can read more about [writing your own functions here](docs/writing.md).
```sh
fn routes create myapp /hello -i treeder/hello
```
Or using cURL:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"route": {
"path":"/hello",
"image":"treeder/hello"
}
}' http://localhost:8080/v1/apps/myapp/routes
```
[More on routes](docs/routes.md).
### Calling your Function
Calling your function is as simple as requesting a URL. Each app has its own namespace and each route mapped to the app.
The app `myapp` that we created above along with the `/hello` route we added would be called via the following
URL: http://localhost:8080/r/myapp/hello
Either surf to it in your browser or use `fn`:
```sh
fn call myapp /hello
```
Or using a cURL:
```sh
curl http://localhost:8080/r/myapp/hello
```
### Passing data into a function
Your function will get the body of the HTTP request via STDIN, and the headers of the request will be passed in
as env vars. You can test a function with the CLI tool:
```sh
echo '{"name":"Johnny"}' | fn call myapp /hello
```
Or using cURL:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"name":"Johnny"
}' http://localhost:8080/r/myapp/hello
```
You should see it say `Hello Johnny!` now instead of `Hello World!`.
### Add an asynchronous function
Oracle Functions supports synchronous function calls like we just tried above, and asynchronous for background processing.
Asynchronous function calls are great for tasks that are CPU heavy or take more than a few seconds to complete.
For instance, image processing, video processing, data processing, ETL, etc.
Architecturally, the main difference between synchronous and asynchronous is that requests
to asynchronous functions are put in a queue and executed on upon resource availability so that they do not interfere with the fast synchronous responses required for an API.
Also, since it uses a message queue, you can queue up millions of function calls without worrying about capacity as requests will
just be queued up and run at some point in the future.
To add an asynchronous function, create another route with the `"type":"async"`, for example:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"route": {
"type": "async",
"path":"/hello-async",
"image":"treeder/hello"
}
}' http://localhost:8080/v1/apps/myapp/routes
```
Now if you request this route:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"name":"Johnny"
}' http://localhost:8080/r/myapp/hello-async
```
You will get a `call_id` in the response:
```json
{"call_id":"572415fd-e26e-542b-846f-f1f5870034f2"}
```
If you watch the logs, you will see the function actually runs in the background:
![async log](docs/assets/async-log.png)
Read more on [logging](docs/logging.md).
## Functions UI
```sh
@@ -319,8 +170,6 @@ You can get community support via:
* [Stack Overflow](http://stackoverflow.com/questions/tagged/functions)
* [Slack](http://get.iron.io/open-slack)
You can get commercial support by contacting [Iron.io](https://iron.io/contact)
## Want to contribute to Oracle Functions?
See [contributing](CONTRIBUTING.md).

1
docs/README.md
View File

@@ -7,6 +7,7 @@
If you are a developer using Oracle Functions through the API, this section is for you.
* [Quickstart](https://github.com/treeder/functions#quickstart)
* [Usage](usage.md)
* [Definitions](definitions.md)
* [fn (CLI Tool)](/fn/README.md)
* [Writing functions](writing.md)

35
docs/serverless.md Normal file
View File

@@ -0,0 +1,35 @@
# What is Serverless/FaaS?
Serverless is a new paradigm in computing that enables simplicity, efficiency and scalability for both developers
and operators. It's important to distinguish the two, because the benefits differ:
## Benefits for developers
The main benefits that most people refer to are on the developer side and they include:
* No servers to manage (serverless) -- you just upload your code and the platform deals with the infrastructure
* Super simple coding -- no more monoliths! Just simple little bits of code
* Pay by the milliseconds your code is executing -- unlike a typical application that runs 24/7, and you're paying
24/7, functions only run when needed
Since you'll be running Oracle Functions yourself, the paying part may not apply, but it does apply to
cost savings on your infrastructure bills as you'll read below.
## Benefits for operators
If you will be operating Oracle Functions (the person who has to manage the servers behind the serverless),
then the benefits are different, but related.
* Extremely efficient use of resources
* Unlike an app/API/microservice that consumes resources 24/7 whether they
are in use or not, functions are time sliced across your infrastructure and only consume resources while they are
actually doing something
* Easy to manage and scale
* Single system for code written in any language or any technology
* Single system to monitor
* Scaling is the same for all functions, you don't scale each app independently
* Scaling is simply adding more Oracle Functions nodes
There is a lot more reading you can do on the topic, just search for
["what is serverless"](https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=what%20is%20serverless)
and you'll find plenty of information.

127
docs/usage.md Normal file
View File

@@ -0,0 +1,127 @@
# Detailed Usage
This is a more detailed explanation of the main commands you'll use in Oracle Functions as a developer.
### Create an Application
An application is essentially a grouping of functions, that put together, form an API. Here's how to create an app.
```sh
fn apps create myapp
```
Or using a cURL:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"app": { "name":"myapp" }
}' http://localhost:8080/v1/apps
```
[More on apps](docs/apps.md).
Now that we have an app, we can route endpoints to functions.
### Add a Route
A route is a way to define a path in your application that maps to a function. In this example, we'll map
`/hello` to a simple `Hello World!` function called `treeder/hello` which is a function we already made that you
can use -- yes, you can share functions! The source code for this function is in the [examples directory](examples/hello/go).
You can read more about [writing your own functions here](docs/writing.md).
```sh
fn routes create myapp /hello -i treeder/hello
```
Or using cURL:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"route": {
"path":"/hello",
"image":"treeder/hello"
}
}' http://localhost:8080/v1/apps/myapp/routes
```
[More on routes](docs/routes.md).
### Calling your Function
Calling your function is as simple as requesting a URL. Each app has its own namespace and each route mapped to the app.
The app `myapp` that we created above along with the `/hello` route we added would be called via the following
URL: http://localhost:8080/r/myapp/hello
Either surf to it in your browser or use `fn`:
```sh
fn call myapp /hello
```
Or using a cURL:
```sh
curl http://localhost:8080/r/myapp/hello
```
### Passing data into a function
Your function will get the body of the HTTP request via STDIN, and the headers of the request will be passed in
as env vars. You can test a function with the CLI tool:
```sh
echo '{"name":"Johnny"}' | fn call myapp /hello
```
Or using cURL:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"name":"Johnny"
}' http://localhost:8080/r/myapp/hello
```
You should see it say `Hello Johnny!` now instead of `Hello World!`.
### Add an asynchronous function
Oracle Functions supports synchronous function calls like we just tried above, and asynchronous for background processing.
Asynchronous function calls are great for tasks that are CPU heavy or take more than a few seconds to complete.
For instance, image processing, video processing, data processing, ETL, etc.
Architecturally, the main difference between synchronous and asynchronous is that requests
to asynchronous functions are put in a queue and executed on upon resource availability so that they do not interfere with the fast synchronous responses required for an API.
Also, since it uses a message queue, you can queue up millions of function calls without worrying about capacity as requests will
just be queued up and run at some point in the future.
To add an asynchronous function, create another route with the `"type":"async"`, for example:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"route": {
"type": "async",
"path":"/hello-async",
"image":"treeder/hello"
}
}' http://localhost:8080/v1/apps/myapp/routes
```
Now if you request this route:
```sh
curl -H "Content-Type: application/json" -X POST -d '{
"name":"Johnny"
}' http://localhost:8080/r/myapp/hello-async
```
You will get a `call_id` in the response:
```json
{"call_id":"572415fd-e26e-542b-846f-f1f5870034f2"}
```
If you watch the logs, you will see the function actually runs in the background:
![async log](docs/assets/async-log.png)
Read more on [logging](docs/logging.md).

2
fn/Makefile
View File

@@ -9,7 +9,7 @@ docker: vendor
docker build -t treeder/fn .
docker push treeder/fn
vendor:
dep:
dep ensure
test:

2
fn/release.sh
View File

@@ -6,7 +6,7 @@ cd lambda
./release.sh
cd ..
make vendor
make dep
make release
version=$1