updated readme

2019-11-22 13:11:53 +01:00
parent 105220b864
commit 2ad36d42d7
2 changed files with 69 additions and 109 deletions
@@ -0,0 +1,34 @@
 ************
 Contributing
 ************
 Want to hack on ``Kapow!``? Awesome! Here are a few instructions to get you
 started. They are probably not perfect, please let us know if anything feels
 wrong or incomplete.
 In general, we follow the "fork-and-pull" Git workflow.
 1. **Fork** this repo
 2. **Clone** the project to your own machine
 3. **Commit** changes to your own branch
 4. **Push** your work back up to your fork
 5. Submit a **Pull request** so that we can review your changes
 NOTE: Be sure to merge the latest commits from **upstream** before making a pull
 request!
 If your pull request is not accepted on the first try, don't be discouraged! If
 there's a problem with the implementation, hopefully you'll receive feedback on
 what to improve.
 Submit unit tests for your changes. Python has a great testing framework built
 in; use it! Take a look at existing tests for inspiration. Run the full test
 suite on your branch before submitting a pull request.
 Make sure you include relevant updates or additions to documentation
 when creating or modifying features.
 Before creating a Pull Request
 ------------------------------
 Please, run the tests :)
@@ -15,131 +15,57 @@ Kapow!
 |Author          | BBVA Innovation Labs                           |
 |Latest Version  | v0.3.0                                         |
 What's Kapow!
 -------------
 Say you have nice cozy **shell command** that solves a problem for you. Kapow! let us easily **turn that into an HTTP API**. 
 **Let's explain this with an example**
 We want to expose **log entries** for files not found on our **Apache Web Server**, as an HTTP API. With Kapow! we just need to write this file: 
-CAVEAT EMPTOR
+    [apache-host]$ cat search-apache-errors.pow
-=============
+    kapow route add /apache-errors - <<-'EOF'
       cat /var/log/apache2/access.log | grep "File does not exist" | kapow set /response/body
    EOF
-**Warning!!! Kapow!** is under **heavy development** and `specification </spec>`_;
+and then, run it using Kapow!
 the provided code is a Proof of Concept and the final version will not even
 share programming language.  Ye be warned.
    [apache-host]$ kapow server --bind 0.0.0.0:8080 search-apache-errors.pow
-What is it?
+finally, we can read from the just-defined endpoint:
 ===========
-Kapow! is an adapter between the world of Pure UNIX® Shell and an HTTP service.
+    [another-host]$ curl http://apache-host:8080/apache-errors
    [Fri Feb 01 22:07:57.154391 2019] [core:info] [pid 7:tid 140284200093440] [client 172.17.0.1:50756] AH00128: File does not exist: /usr/var/www/mysite/favicon.ico
    [Fri Feb 01 22:07:57.808291 2019] [core:info] [pid 8:tid 140284216878848] [client 172.17.0.1:50758] AH00128: File does not exist: /usr/var/www/mysite/favicon.ico
    [Fri Feb 01 22:07:57.878149 2019] [core:info] [pid 8:tid 140284208486144] [client 172.17.0.1:50758] AH00128: File does not exist: /usr/var/www/mysite/favicon.ico
    ...
-Some tasks are more convenient in the shell, like cloud interactions, or some
+**Why Kapow! shines in these cases**
 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
+- We can share information without having grant SSH access to anybody.
-about how this kind of magic can happen; if you want to know the nitty-gritty
+- We want to limit what is executed.
-details, just read our `specification </spec>`_;.  Or, if you want to know how
+- We can share information easily over HTTP. 
 Kapow! can help you first, let's start with a common situation.
-Think about that awesome command that you use every day, something very
+Documentation
-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
+Here you can find the complete documentation [here](https://kapow.readthedocs.io)
 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
+Authors
-an infinite number of times!  Instead, let's put Kapow! into action.
+-------
-With Kapow! you just need to create a ``.pow`` file named ``backups.pow`` that
+Kapow! is being developed by BBVA-Labs Security team members:
 contains:
-.. code-block:: sh
+- Roberto Martinez
 - Hector Hurtado
 - César Gallego
 - pancho horrillo
-    kapow route add /backups \
+Kapow! is Open Source Software and available under the [Apache 2 license](https://raw.githubusercontent.com/BBVA/kapow/master/LICENSE).
        -c 'cloudx storage ls /backups | grep "$(kapow get /request/params/query)" | kapow set /response/body'
-and execute it in the remote host with the command:
+Contributions
 -------------
-.. code-block:: sh
+Contributions are of course welcome. See [CONTRIBUTING](https://raw.githubusercontent.com/BBVA/kapow/blob/master/CONTRIBUTING.rst) or skim existing tickets to see where you could help out.
    kapow server backups.pow
 and that's it.  Done.  You have a web server that people can use to request
 their backups every time they need only by invoking the URL
 `http://remotehost/backups?query=project`
 Do you like it? yes?  Then let's start learning a little more, you can access
 the `documentation </doc>`_; section to find installation instructions and some
 examples.
 How it was born
 ---------------
 Some awesome history is coming.
 Kapow! for the impatient
 ========================
 When you need to **share** a ``command`` but **not** a complete remote ``ssh
 access``, Kapow!  will help you with the power of HTTP:
 .. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png
    :alt: Where Kapow! lives
 Kapow! allows you to write a litte script that will **serve an executable as REST
 service**.  This script will let you define how to connect HTTP and the  Shell
 using Kapow!'s shell abstractions to the HTTP world. See it to believe:
 .. image:: resources/kapow.gif?raw=true
    :alt: Kapow! in action
 Superpowers
 -----------
 Kapow! gives you:
 * A very simple way to turn any shell **executable into an API**
 * A **remote administration** API
 * A way to define the integration in you own terms, obligations-free!
 Curses
 ------
 Kapow! can't help when:
 -----------------------
 * You need high throughput: Kapow! spawns a new executable for every HTTP call
 * You must perform complex logic to attend the request: never use Kapow! if
  your executables don't perform al least 90% of the hard work
 * You are building a huge application
 When it is your best friend:
 ----------------------------
 * Easy command + Hard API = Kapow! to the rescue
 * SSH for one command?  Kapow! allows you to share only that command
 * Remote instrumentation of several machines?  Make it easy with Kapow!
 The more you know
 =================
 If you want to know more, please follow our `documentation </doc>`_.