From d115ad6d459b579ff1f3f0599aff8ee8ef640b54 Mon Sep 17 00:00:00 2001 From: Travis Reeder Date: Thu, 25 May 2017 03:08:40 +0000 Subject: [PATCH] Cleaning up docs --- README.md | 205 ++++++--------------------------------------- docs/README.md | 1 + docs/serverless.md | 35 ++++++++ docs/usage.md | 127 ++++++++++++++++++++++++++++ fn/Makefile | 2 +- fn/release.sh | 2 +- 6 files changed, 192 insertions(+), 180 deletions(-) create mode 100644 docs/serverless.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index b5a8196d2..4d982d43e 100644 --- a/README.md +++ b/README.md @@ -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* + + ### 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). diff --git a/docs/README.md b/docs/README.md index 4d88dfb85..496ffa6ac 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/serverless.md b/docs/serverless.md new file mode 100644 index 000000000..f9ab8624a --- /dev/null +++ b/docs/serverless.md @@ -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. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 000000000..8adf034ab --- /dev/null +++ b/docs/usage.md @@ -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). \ No newline at end of file diff --git a/fn/Makefile b/fn/Makefile index 92bd44e6c..31c91453d 100644 --- a/fn/Makefile +++ b/fn/Makefile @@ -9,7 +9,7 @@ docker: vendor docker build -t treeder/fn . docker push treeder/fn -vendor: +dep: dep ensure test: diff --git a/fn/release.sh b/fn/release.sh index b26ec9cde..c8bcfe538 100755 --- a/fn/release.sh +++ b/fn/release.sh @@ -6,7 +6,7 @@ cd lambda ./release.sh cd .. -make vendor +make dep make release version=$1