diff --git a/README.rst b/README.rst index 9d264f1..56cddef 100644 --- a/README.rst +++ b/README.rst @@ -1,49 +1,42 @@ -With *Kapow!* you can publish simple **shell scripts** as **HTTP -services**. +Welcome to *Kapow!* +=================== -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. +With *Kapow!* you can publish simple **shell scripts** as **HTTP services** easily. -.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png - :alt: Where Kapow! lives +*Kapow!* with an example +------------------------ -Installation -============ +**Goal** -1. Get a precompiled static binary for your system from our `releases section `_. +We want users on the Internet to be able to ``ping`` an *Internal Host* +which is inside a private network. -2. Put it in your ``$PATH`` (Linux example): +.. image:: _static/network.png - .. code-block:: bash +**Limitations** - sudo install kapow1.0.0-rc1_linux_amd64 /usr/bin/kapow +- 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. -Hello World! -- *Kapow!* style -============================== +**Solution** -In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``. -Let's publish it through HTTP using *Kapow!* +With a *Kapow!* one-liner you can allow your users to run a command inside +*External Host* through an HTTP call. -- 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: +.. image:: _static/sequence.png + +This is the only line you'll need: .. code-block:: bash - kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body' + $ kapow route add /ping -c 'ping -c1 10.10.10.100 | kapow set /response/body' -- Start the *Kapow!* server with your script as an argument -.. code-block:: bash +.. todo:: - kapow server greet.sh + Mention license and contributing -- Finally check that all is working as intended using `curl` -.. code-block:: bash - - $ curl http://localhost:8080/greet - Hello World! diff --git a/docs/Pipfile b/docs/Pipfile index 57a81a3..7c726e3 100644 --- a/docs/Pipfile +++ b/docs/Pipfile @@ -10,4 +10,4 @@ sphinx = "*" sphinx-rtd-theme = "*" [requires] -python_version = "3.7" +python_version = "3.8" diff --git a/docs/source/_static/browser.png b/docs/source/_static/browser.png new file mode 100644 index 0000000..a466a63 Binary files /dev/null and b/docs/source/_static/browser.png differ diff --git a/docs/source/_static/network.png b/docs/source/_static/network.png new file mode 100644 index 0000000..3f5d222 Binary files /dev/null and b/docs/source/_static/network.png differ diff --git a/docs/source/_static/sequence.png b/docs/source/_static/sequence.png new file mode 100644 index 0000000..6cdaa82 Binary files /dev/null and b/docs/source/_static/sequence.png differ diff --git a/docs/source/contents.rst b/docs/source/cheatsheet.rst similarity index 100% rename from docs/source/contents.rst rename to docs/source/cheatsheet.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index a3cd8ce..8020ecb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,7 +48,12 @@ exclude_patterns = [] html_theme = "sphinx_rtd_theme" html_logo = "_static/logo.png" html_theme_options = { - 'logo_only': True + 'logo_only': True, + 'collapse_navigation': False, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False + } # Add any paths that contain custom static files (such as style sheets) here, diff --git a/docs/source/index.rst b/docs/source/index.rst index be31410..b39d9b3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,14 +2,17 @@ .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: TODO -Quickstart Guide -================ + install + quickstart -.. todo:: +.. toctree:: + :maxdepth: 2 + :caption: Tutorial + + tutorial - Here an end to end tutorial (15-20 minutes) Indices and tables diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000..a6670d1 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,17 @@ +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 new file mode 100644 index 0000000..c4c3cb2 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,27 @@ +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/tutorial.rst b/docs/source/tutorial.rst new file mode 100644 index 0000000..b40ad1e --- /dev/null +++ b/docs/source/tutorial.rst @@ -0,0 +1,28 @@ + +.. 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 + +