diff --git a/docs/source/tutorial/tutorial01.rst b/docs/source/tutorial/tutorial01.rst index 7909556..2a1bd7b 100644 --- a/docs/source/tutorial/tutorial01.rst +++ b/docs/source/tutorial/tutorial01.rst @@ -82,4 +82,105 @@ Backup that Database! **Junior** - ... + I've just installed it in my laptop, but I don't understand how all of + this is going to work. + +**Senior** + + Don't worry it is pretty easy. Basically we will provide an HTTP + endpoint managed by Kapow! at the **Corporate Server**; when the + project team wants to perform a backup they only need to call the + endpoint and Kapow! will call the backup script. + +**Junior** + + It seems pretty easy. How can I create the endpoint? + +**Senior** + + First you have to start a fresh server. Please run this in your laptop: + + .. code-block:: console + + $ kapow server + + .. warning:: + + It is important that you run this command in the same directory + in which you downloaded ``backup_db.sh``. + +**Junior** + + Done! But it doesn't do anything. + +**Senior** + + Now you have the port 8080 open but don't have any endpoints defined. + To define our endpoint you have to run this in another terminal: + + .. code-block:: console + + $ kapow route add -X PUT /db/backup -e ./backup_db.sh + + This will create an endpoint accessible via + ``http://localhost:8080/db/backup``. This endpoint have to be invoked + with the ``PUT`` method to prevent accidental calls. + +**Junior** + + Cool! Do we need to do all this stuff every time we start the + **Corporate Server**? + +**Senior** + + Not at all. The have thought of everything. You can put all your route + definitions in a special script file and pass it to the server on + startup. They call those files `POW` files and have ``.pow`` + extension. + + It should look something like: + + .. code-block:: console + + $ cat backup.pow + kapow route add -X PUT /db/backup -e ./backup_db.sh + + And then you can start Kapow! with it: + + .. code-block:: console + + $ kapow server backup.pow + +**Junior** + + Great! Now it says: + + .. code-block:: console + + $ kapow server backup.pow + 2019/11/26 11:40:01 Running powfile: "backup.pow" + {"id":"19bb4ac7-1039-11ea-aa00-106530610c4d","method":"PUT","url_pattern":"/db/backup","entrypoint":"./backup_db.sh","command":"","index":0} + 2019/11/26 11:40:01 Done running powfile: "backup.pow" + + I understand that this is proof that we have the endpoint available. + +**Senior** + + That appears to be the case, but better we check it. + + Call it with ``curl``: + + .. code-block:: console + + $ curl -X PUT http://localhost:8080/db/backup + +**Junior** + + Yay! I can see the log file at ``/tmp/backup_db.log`` + +**Senior** + + That's great. I am going to install all this in the *Corporate Server* + and forget about the old procedure. + + That enough for your first day! You can go home.