diff --git a/README.rst b/README.rst index 49c0219..b0723f7 100644 --- a/README.rst +++ b/README.rst @@ -1,44 +1,134 @@ -Welcome to *Kapow!* -=================== +.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/f51eb40412bf09c8c800511d7bbe5634/kapow-1601675_480.png + :alt: Kapow! + +.. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg + :target: https://circleci.com/gh/BBVA/kapow/tree/master .. image:: https://goreportcard.com/badge/github.com/bbva/kapow :target: https://goreportcard.com/report/github.com/bbva/kapow - -With *Kapow!* you can publish simple **shell scripts** as **HTTP services** easily. - -*Kapow!* with an example ------------------------- - -**Goal** - -We want users on the Internet to be able to ``ping`` an *Internal Host* -which is inside a private network. - -.. image:: https://github.com/BBVA/kapow/raw/feature-new-doc/docs/source/_static/network.png - -**Limitations** - -- We can't allow users to log into any host. - -- We need to have full control over the precise command is run as - well as the parameters used. - -**Solution** - -With a *Kapow!* one-liner you can allow your users to run a command inside -*External Host* through an HTTP call. - -.. image:: https://github.com/BBVA/kapow/raw/feature-new-doc/docs/source/_static/sequence.png - -This is the only line you'll need: - -.. code-block:: bash - - $ kapow route add /ping -c 'ping -c1 10.10.10.100 | kapow set /response/body' +**Kapow!** If you can script it, you can HTTP it. -.. todo:: +CAVEAT EMPTOR +============= - Mention license and contributing +**Warning!!! Kapow!** is under **heavy development** and `specification `_; +the provided code is a Proof of Concept and the final version will not even +share programming language. Ye be warned. + +What is it? +=========== + +Kapow! is an adapter between the world of Pure UNIX® Shell and a 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 `specification `_;. 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! you just need to create a ``.pow`` file named ``backups.pow`` that +contains: + +.. code-block:: sh + + kapow route add /backups \ + -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: + +.. code-block:: sh + + 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 `_; 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 `_. diff --git a/docs/source/cheatsheet.rst b/docs/source/examples/index.rst similarity index 100% rename from docs/source/cheatsheet.rst rename to docs/source/examples/index.rst diff --git a/docs/source/install.rst b/docs/source/install.rst deleted file mode 100644 index a6670d1..0000000 --- a/docs/source/install.rst +++ /dev/null @@ -1,17 +0,0 @@ -Installation -============ - -Precompiled Binaries --------------------- - -1. Get a precompiled static binary for your system from our `releases section `_. - -2. Put it in your ``$PATH`` (Linux example): - - .. code-block:: bash - - sudo install kapow1.0.0-rc1_linux_amd64 /usr/bin/kapow - -.. todo:: - - Describe all the options available. diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst deleted file mode 100644 index c4c3cb2..0000000 --- a/docs/source/quickstart.rst +++ /dev/null @@ -1,27 +0,0 @@ -Quickstart Guide -================ - - -Hello World! -- *Kapow!* style ------------------------------- - -In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``. -Let's publish it through HTTP using *Kapow!* - -- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code: - -.. code-block:: bash - - kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body' - -- Start the *Kapow!* server with your script as an argument - -.. code-block:: bash - - kapow server greet.sh - -- Finally check that all is working as intended: - -.. image:: _static/browser.png - - diff --git a/docs/source/setup/index.rst b/docs/source/setup/index.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/theory/index.rst b/docs/source/theory/index.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst deleted file mode 100644 index b40ad1e..0000000 --- a/docs/source/tutorial.rst +++ /dev/null @@ -1,28 +0,0 @@ - -.. todo:: - - Redo - -Hello World! -- *Kapow!* style ------------------------------- - -In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``. -Let's publish it through HTTP using *Kapow!* - -- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code: - -.. code-block:: bash - - kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body' - -- Start the *Kapow!* server with your script as an argument - -.. code-block:: bash - - kapow server greet.sh - -- Finally check that all is working as intended: - -.. image:: _static/browser.png - -