diff --git a/.gitignore b/.gitignore index f6d3a04..372dd5d 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,6 @@ __pycache__ output build .vscode + +docs/build +docs/Pipfile.lock diff --git a/README.md b/README.md deleted file mode 100644 index bdf1edd..0000000 --- a/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# What is it? - -Kapow! is an adapter between the world of Pure UNIX® Shell and a HTTP service. -It lies between these two worlds, making your life easier. - -Kapow! allows yo to publish a simple shell script as a REST HTTP service so you -can delegate in others its execution as they don't need access to the host in -which the command is ran. Those repetitive tasks that everybody ask you to do -because they require administrative access to some host can be published through -a Kapow! server deployed in that host and the users who need the results can -invoke it directly using a easy to use interfaz, a HTTP request. - -In the tradicional way you needed to create a project, manage its dependencies, -code the server (probably including only a command execution) and deploy it -somewhere. And that's fine... until you find yourself again in the same -situation with another awesome command. - -### From now on you can put Kapow! into action - -- Create a pow file containing an api call to Kapow! for creating the route -that will publish your command, lets's call it `greet.pow` - ```sh - kapow route add /greet -c 'name=$(kapow get /request/params/name); echo Hello ${name:-World} | kapow set /response/body' - ``` -- Start the Kapow! server providing your pow file to configure the route - ```sh - kapow server greet.pow - ``` -- check that all it is working as intended using `curl` - ```sh - $ curl localhost:8080/greet - Hello World - - $ curl localhost:8080/greet?name=friend - Hello friend - ``` - -# Installing Kapow! - -Kapow! has a reference implementation in Go that is under active development right -now. If you want to start using Kapow! you can: -* Download a binary (only linux is available , at this moment) from our -[releases](https://github.com/BBVA/kapow/releases/latest) section -* Install the package with Go's `get` command (you need the Go runtime installed -and [configured](https://golang.org/cmd/go/)) -```sh -go get -u github.com/BBVA/kapow -``` diff --git a/README.rst b/README.rst index 9569931..9d264f1 100644 --- a/README.rst +++ b/README.rst @@ -1,131 +1,49 @@ -.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/f51eb40412bf09c8c800511d7bbe5634/kapow-1601675_480.png - :alt: Kapow! +With *Kapow!* you can publish simple **shell scripts** as **HTTP +services**. -.. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg - :target: https://circleci.com/gh/BBVA/kapow/tree/master - -**Kapow!** If you can script it, you can HTTP it. - - -CAVEAT EMPTOR -============= - -**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: +This way you can delegate in others its execution as they don't need access to the host in +which the command is ran. In summary, those repetitive tasks that everybody ask you to do +because they require administrative access to some host can be published through +a *Kapow!* server deployed in that host and the users who need the results can +invoke it directly using an easy to use interface, an HTTP request. .. 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: +Installation +============ -.. image:: resources/kapow.gif?raw=true - :alt: Kapow! in action +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 -Superpowers ------------ +Hello World! -- *Kapow!* style +============================== -Kapow! gives you: +In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``. +Let's publish it through HTTP using *Kapow!* -* 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! +- 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 -Curses ------- + kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body' -Kapow! can't help when: ------------------------ +- Start the *Kapow!* server with your script as an argument -* 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 +.. code-block:: bash + kapow server greet.sh -When it is your best friend: --------------------------- +- Finally check that all is working as intended using `curl` -* 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! +.. code-block:: bash + $ curl http://localhost:8080/greet + Hello World! -The more you know -================= - -If you want to know more, please follow our `documentation `_. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/Pipfile b/docs/Pipfile new file mode 100644 index 0000000..57a81a3 --- /dev/null +++ b/docs/Pipfile @@ -0,0 +1,13 @@ +[[source]] +name = "pypi" +url = "https://pypi.org/simple" +verify_ssl = true + +[dev-packages] + +[packages] +sphinx = "*" +sphinx-rtd-theme = "*" + +[requires] +python_version = "3.7" diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png new file mode 100644 index 0000000..148bd92 Binary files /dev/null and b/docs/source/_static/logo.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..a3cd8ce --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,57 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Kapow!' +copyright = '2019, BBVA Innovation Labs' +author = 'BBVA Innovation Labs' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.todo', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" +html_logo = "_static/logo.png" +html_theme_options = { + 'logo_only': True +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..be31410 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. include:: ../../README.rst + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +Quickstart Guide +================ + +.. todo:: + + Here an end to end tutorial (15-20 minutes) + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`