Merge pull request #29 from platform9/readme-updates

Readme updates

README.md

@@ -1,17 +1,80 @@
-Fission
-=======
+Fission: Serverless Functions for Kubernetes
+============================================
+[fission.io](http://fission.io)  [@fissionio](http://twitter.com/fissionio)
 
 Fission is a fast serverless framework for Kubernetes with a focus on
 developer productivity and high performance.
 
-It's customizable (with sensible defaults), extensible to any
-language, and interoperates well with other infrastructure.
+Fission operates on _just the code_: Docker and Kubernetes are
+abstracted away under normal operation, though you can use both to
+extend Fission if you want to.
 
-See http://fission.io for more.
+Fission is extensible to any language; the core is written in Go, and
+language-specific parts are isolated in something called
+_environments_ (more below).  Fission currently supports NodeJS and
+Python, with more languages coming soon.
+
+### Performance: 100msec cold start
+
+Fission maintains a pool of "warm" containers that each contain a
+small dynamic loader.  When a function is first called,
+i.e. "cold-started", a running container is chosen and the function is
+loaded.  This pool is what makes Fission fast: cold-start latencies
+are typically about 100msec.
+
+### Kubernetes is the right place for Serverless
+
+We're built on Kubernetes because we think any non-trivial app will
+use a combination of serverless functions and more conventional
+microservices, and Kubernetes is a great framework to bring these
+together seamlessly.
+
+Building on Kubernetes also means that anything you do for operations
+on your Kubernetes cluster — such as monitoring or log
+aggregation — also helps with ops on your Fission deployment.
 
 
-Running Fission
-===============
+Fission Concepts
+----------------
+
+A _function_ is a piece of code that follows the fission function
+interface.
+
+An _environment_ contains the language- and runtime-specific parts of
+running a function.  Fission comes with NodeJS and Python
+environments; you can also extend environments or create entirely new
+ones if you want.  (An environment is essentially just a container
+with a webserver and dynamic loader.)
+
+A _trigger_ is something that maps an event to a function; Fission
+supports HTTP routes as triggers today, with upcoming support for
+other types of event triggers, such as timers and Kubernetes events.
+
+Usage
+-----
+
+```bash
+
+  # Add the stock NodeJS env to your Fission deployment
+  $ fission env create --name nodejs --image fission/node-env
+
+  # A javascript one-liner that prints "hello world"
+  $ echo 'module.exports = function(context, callback) { callback(200, "Hello, world!\n"); }' > hello.js  
+
+  # Upload your function code to fission
+  $ fission function create --name hello --env nodejs --code hello.js
+
+  # Map GET /hello to your new function
+  $ fission route create --method GET --url /hello --function hello
+
+  # Run the function.  This takes about 100msec the first time.
+  $ curl http://$FISSION_ROUTER/hello
+  Hello, world!
+```
+
+
+Running Fission on your Cluster
+===============================
 
 ### Setup Kubernetes
 
@@ -70,6 +133,10 @@ for the examples below to work.)
 Compiling Fission
 =================
 
+[You only need to do this if you're making Fission changes; if you're
+just deploying Fission, use fission.yaml which points to prebuilt
+images.]
+
 You'll need go installed, along with the glide dependecy management
 tool.  You'll also need docker for building images.
 
@@ -108,17 +175,9 @@ If you're changing the CLI:
 Status
 ======
 
-Fission is in early alpha.  Don't use it in production just yet, but
-play with it and give us feedback!
+Fission is in early alpha.  Don't use it in production just yet!
 
-
-
-
-Performance
-===========
-
-The alpha release has focussed on cold-start latency performance.  For
-requests that don't have a running instance, i.e. a "cold start",
-fission has a latency overhead of less than 100 msec for the NodeJS
-environment.
+Right now, we're looking for developer feedback -- tell us which
+languages you care about, what use cases you might use it for, and so
+on.