more simple Readme and brand new doc

2019-06-20 11:04:24 +02:00
parent dd6afc21bb
commit e773f8ec29
2 changed files with 214 additions and 181 deletions
@@ -1,12 +1,13 @@
 ![Kapow!](https://trello-attachments.s3.amazonaws.com/5c6edee98297dc18aa4e2b63/960x720/ff8d28fc24af11e3295afa5a9665bdc0/kapow-1601675_960_720.png)
-**Kapow!** allows you to leverage the Ultimate Power™ of the UNIX® shell via HTTP.
+**Kapow!** If you can script it, you can HTTP it.
 # CAVEAT EMPTOR
-**Warning!!! Kapow!** is in the process of being defined by a
+**Warning!!! Kapow!** is under heavy develepment and 
-[specification](/spec/); the provided code is an *unsupported* Proof of Concept.
+[specification](/spec/); the provided code is a Proof of Concept and the final
 version will not even share programming language.
 Ye be warned.
@@ -16,200 +17,43 @@ Some awesome history is coming.
 # Kapow! for the impatient
 When you need to share a command but not a whole system, Kapow! will help you by
 the power of HTTP:
 ![Kapow! lives](https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png)
 Kapow! allows you to write a litte script that will serve an executable.
 This script will let you define how connect HTTP to Shell using Kapow!'s shell
 abstractions to the HTTP world. See it to believe:
 ![Kapow! in action](https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/b5e2554ff02fd9dba5ed2cec5c5d41e1/hello_kapow.gif)
 On a simple schematics you can understand where Kapow! lives:
-![Kapow! lives](https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png)
+## Kapow! Superpowers
 ## Kapow! Features
 Kapow! gives you:
- * A very simple way of APIfy any shell executable
+ * A very simple way to turn any shell executable into an API
 * A remote administration API
 * Opinion free shell integration
-When Kapow! is your best ally:
+
 ## Kapow! Curses
 Kapow! can't help when:
 * You need high throughput: Kapow! spawn a new executable every HTTP call
 * You must perform complex logic to attend the request: never use Kapow! if
   your executables doesn't perform al least 90% of the hard work
 * You are building a huge application
 ## When Kapow! is your best ally:
 * Easy command + Hard API = Kapow! to the rescue
 * SSH for one command? Kapow! allow you to share only that command
 * Remote instrumentation of several machines? make it easy with Kapow!
 # Kapow! The more you know
-# What is Kapow!
+If you want to know more, please follow our [documentation](/doc).
 Kapow! is an adapter between the world of Pure UNIX® Shell and an HTTP service.
 Some tasks are more convenient in the shell, like cloud interactions, or some
 administrative tools.  On the other hand, some tasks are more convenient as a
 service, like DevSecOps tooling.
 Kapow! lies between these two worlds, making your life easier.  Maybe you wonder
 about how this kind of magic can happen; if you want to know the nitty-gritty
 details, just read our [spec](/spec/).  Or, if you want to know how Kapow! can
 help you first, let's start with a common situation.
 Think about that awesome command that you use every day, something very
 familiar, like `cloudx storage ls /backups`.  Then someone asks you for an
 specific backup, so you `ssh` into the host, execute your command, possibly
 `grepping` through its output, copy the result and send it back to him. 
 And that's fine... for the 100 first times.
 Then you decide, let's use an API for this and generate an awesome web server
 with it.  So, you create a project, manage its dependencies, code the server,
 parse the request, learn how to use the API, call the API and deploy it
 somewhere.  And that's fine... until you find yourself again in the same
 situation with another awesome command.
 The awesomeness of UNIX® commands is infinite, so you'll be in this situation
 an infinite number of times!  Instead, let's put Kapow! into action.
 With Kapow!, when someone asks you for an specific backup (remember your
 familiar command?) you just need to create a `.pow` file named `backups.pow`
 that contains:
 ```bash
 kapow route add /backups \
    -c 'cloudx storage ls /backups | grep $(request /params/query) | response /body'
 ```
 and execute it in the host with the command:
 ```bash
 kapow server backups.pow
 ```
 and that's it.  Done.  Do you like it? yes?  Then let's start learning a little
 more.
 ## The mandatory Hello World (for WWW fans)
 First you must create a pow file named `hello.pow` with the following contents:
 ```bash
 kapow route add /greet -c "echo 'hello world' | response /body"
 ```
 then, you must execute:
 ```bash
 kapow server hello.pow
 ```
 and you can check that it works as intended with good ole' `curl`:
 ```bash
 curl localhost:8080/greet
 ```
 ## The mandatory Echo (for UNIX fans)
 First you must create a pow file named `echo.pow` with the following contents:
 ```bash
 kapow route add -X POST /echo -c 'request /body | response /body'
 ```
 then, you must execute:
 ```bash
 kapow server echo.pow
 ```
 and you can check that it works as intended with good ole `curl`:
 ```bash
 curl -X POST -d '1,2,3... testing' localhost:8080/echo
 ```
 ## The multiline fun
 Unless you're a hardcore Perl hacker, you'll probably need to write your stuff
 over more than one line.
 Don't worry, we need to write several lines, too. Bash, in its magnificent
 UNIX® style, provides us with the
 [here-documents](https://www.gnu.org/software/bash/manual/bash.html#Here-Documents)
 mechanism that we can leverage precisely for this purpose.
 Let's write a `multiline.pow` file with the following content:
 ```bash
 kapow route add /log_and_love - <<- 'EOF'
 	echo "[$(date)] and stuff" >> stuff.log
 	echo love | response /body
 EOF
 ```
 and then we serve it with `kapow`:
 ```bash
 kapow server multiline.pow
 ```
 Yup.  As simple as that.
 # Sample Docker usage
 ## Clone the project
 ```bash
 # clone this project
 ```
 ## Build the kapow! docker image
 ```bash
 docker build -t bbva/kapow:0.1 /path/to/kapow/poc
 ```
 ## Build a docker image for running the nmap example
 ```bash
 docker build -t kapow-nmap /path/to/kapow/poc/examples/nmap
 ```
 ## Run kapow
 ```bash
 docker run \
        -it \
        -p 8080:8080 \
        kapow-nmap
 ```
 which will output something like this:
 ```
 ======== Running on http://0.0.0.0:8080 ========
 (Press CTRL+C to quit)
 Route created POST /list/{ip}
 ROUTE_8ed01c48_bf23_455a_8186_a1df7ab09e48
 bash-4.4#
 ```
 ## Test /list endpoint
 In another terminal, try running:
 ```bash
 curl http://localhost:8080/list/github.com
 ```
 which will respond something like:
 ```
 Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC
 Nmap scan report for github.com (140.82.118.3)
 rDNS record for 140.82.118.3: lb-140-82-118-3-ams.github.com
 Nmap done: 1 IP address (0 hosts up) scanned in 0.04 seconds
 ```
 et voilà !
 # License
 This project is distributed under the [Apache License 2.0](/LICENSE).
@@ -0,0 +1,189 @@
 What is Kapow!
 ==============
 Kapow! is an adapter between the world of Pure UNIX® Shell and an HTTP service.
 Some tasks are more convenient in the shell, like cloud interactions, or some
 administrative tools.  On the other hand, some tasks are more convenient as a
 service, like DevSecOps tooling.
 Kapow! lies between these two worlds, making your life easier.  Maybe you wonder
 about how this kind of magic can happen; if you want to know the nitty-gritty
 details, just read our [spec](/spec/).  Or, if you want to know how Kapow! can
 help you first, let's start with a common situation.
 Think about that awesome command that you use every day, something very
 familiar, like ``cloudx storage ls /backups``.  Then someone asks you for an
 specific backup, so you ``ssh`` into the host, execute your command, possibly
 ``grepping`` through its output, copy the result and send it back to him. 
 And that's fine... for the 100 first times.
 Then you decide, let's use an API for this and generate an awesome web server
 with it.  So, you create a project, manage its dependencies, code the server,
 parse the request, learn how to use the API, call the API and deploy it
 somewhere.  And that's fine... until you find yourself again in the same
 situation with another awesome command.
 The awesomeness of UNIX® commands is infinite, so you'll be in this situation
 an infinite number of times!  Instead, let's put Kapow! into action.
 With Kapow!, when someone asks you for an specific backup (remember your
 familiar command?) you just need to create a ``.pow`` file named ``backups.pow``
 that contains:
 .. code-block:: bash
    kapow route add /backups \
        -c 'cloudx storage ls /backups | grep $(request /params/query) | response /body'
 and execute it in the host with the command:
 .. code-block:: bash
    kapow server backups.pow
 and that's it.  Done.  Do you like it? yes?  Then let's start learning a little
 more.
 The mandatory Hello World (for WWW fans)
 ----------------------------------------
 First you must create a pow file named ``hello.pow`` with the following contents:
 .. code-block:: bash
    kapow route add /greet -c "echo 'hello world' | response /body"
 then, you must execute:
 .. code-block:: bash
    kapow server hello.pow
 and you can check that it works as intended with good ole' ``curl``:
 .. code-block:: bash
    curl localhost:8080/greet
 The mandatory Echo (for UNIX fans)
 ----------------------------------
 First you must create a pow file named ``echo.pow`` with the following contents:
 .. code-block:: bash
    kapow route add -X POST /echo -c 'request /body | response /body'
 then, you must execute:
 .. code-block:: bash
    kapow server echo.pow
 and you can check that it works as intended with good ole ``curl``:
 .. code-block:: bash
    curl -X POST -d '1,2,3... testing' localhost:8080/echo
 The multiline fun
 -----------------
 Unless you're a hardcore Perl hacker, you'll probably need to write your stuff
 over more than one line.
 Don't worry, we need to write several lines, too. Bash, in its magnificent
 UNIX® style, provides us with the
 `here-documents`_ mechanism that we can leverage precisely for this purpose.
 .. _here-documents: https://www.gnu.org/software/bash/manual/bash.html#Here-Documents
 Let's write a ``multiline.pow`` file with the following content:
 .. code-block:: bash
    kapow route add /log_and_love - <<- 'EOF'
        echo "[$(date)] and stuff" >> stuff.log
        echo love | response /body
    EOF
 and then we serve it with ``kapow``:
 .. code-block:: bash
    kapow server multiline.pow
 Yup.  As simple as that.
 Sample Docker usage
 ===================
 Clone the project
 -----------------
 .. code-block:: bash
    # clone this project
 Build the kapow! docker image
 -----------------------------
 .. code-block:: bash
    docker build -t bbva/kapow:0.1 /path/to/kapow/poc
 Build a docker image for running the nmap example
 .. code-block:: bash
    docker build -t kapow-nmap /path/to/kapow/poc/examples/nmap
 Run kapow
 ---------
 .. code-block:: bash
    docker run \
            -it \
            -p 8080:8080 \
            kapow-nmap
 which will output something like this:
 .. code-block:: bash
    ======== Running on http://0.0.0.0:8080 ========
    (Press CTRL+C to quit)
    Route created POST /list/{ip}
    ROUTE_8ed01c48_bf23_455a_8186_a1df7ab09e48
    bash-4.4#
 Test /list endpoint
 -------------------
 In another terminal, try running:
 .. code-block:: bash
    curl http://localhost:8080/list/github.com
 which will respond something like:
 .. code-block:: bash
    Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC
    Nmap scan report for github.com (140.82.118.3)
    rDNS record for 140.82.118.3: lb-140-82-118-3-ams.github.com
    Nmap done: 1 IP address (0 hosts up) scanned in 0.04 seconds
 et voilà !
 License
 =======
 This project is distributed under the [Apache License 2.0](/LICENSE).