diff --git a/CHANGELOG.md b/CHANGELOG.md index 22b9773474228edf7a8ffc26d81b635295561696..e936d2032060d8931259de3770a3382e9e2ebcac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * Unknown error when trying to access the user list. [linkahead-server#250](https://gitlab.com/linkahead/linkahead-server/-/issues/250) +* Legacy integer ids are incremented by 1 again, not by 2. ### Security diff --git a/src/doc/administration/server_side_scripting.rst b/src/doc/administration/server_side_scripting.rst index 23beb74eaf5a6e56d1cc5c56bbd1f077306fc48c..dc4b020ea884a170df30ddd866e77fa1f6bf5a7a 100644 --- a/src/doc/administration/server_side_scripting.rst +++ b/src/doc/administration/server_side_scripting.rst @@ -1,126 +1,4 @@ Server-Side Scripting ===================== -Introduction ------------- - -Small computation task, like some visualization, might be easily implemented in Python or some other language, but cumbersome to integrate into the server. Furthermore, the CaosDB server should stay a general tool without burden from specific projects. Also, one might want to trigger some standardized processing task from the web interface for convenience. For these situations the "server side scripting" is intended. - -Concepts ------------- - -The basic idea is that a script or program (script in the following) can be called to run on the server (or elsewhere in future) to do some calculations. This triggering of the script is done over the API so it can be done with any client. Input arguments can be passed to the script and the STDOUT and STDERR are returned. - -Each script is executed in a temporary home directory, which is automatically clean up. However, scripts can store files in the "$SHARED" folder and for example provide users a link that allows them to download files. - -Write and Install a Script --------------------------- - -A server-side script must accept at least the ``--auth-token=AUTH_TOKEN`` option. All other command-line parameters which are passed to the script are not specified by the API and maybe defined by the script itself. - -So a minimal bash script would be - -.. code-block:: sh - - #!/bin/bash - echo Hello, World! - -thereby just ignoring the ``--auth-token`` option. - -The script has to be executable and must be placed somewhere in one of the directory trees which are configured by the server config :doc:`SERVER_SIDE_SCRIPTING_BIN_DIRS <configuration>`. - -Users will need the ``SCRIPTING:EXECUTE:path:to:the:script`` permission. Here the path to the script is of course relativet to the ``SERVER_SIDE_SCRIPTING_BIN_DIRS`` where it is located. - -For more information see the :doc:`specification of the API <../specification/Server-side-scripting>` - -Environment ------------- - -The script is called with several special environment variables to accommodate -for its special location. - -`HOME` -^^^^^^^^^^^^ -To be able to run with reduced privileges, the script has its `HOME` environment -variable set to a special directory with write access. This directory will be -deleted after the script has terminated. Its content is freshly copied for each -script invocation from a skeleton directory, located in the server directory, in -`scripting/home/`. By default, this directory contains the following: - -- `readme.md` :: A small text file describing the purpose of the directory. - -Users of CaosDB are invited to populate the directory with whatever their -scripts need (for example a `.pycaosdb.ini` file). - -Invocation ------------- - -Server side scripts are triggered by sending a POST to the `/scripting` resource. There are the following arguments that can be provided: - -- `call`: the name of the script to be called -- `-pN`: positional arguments (e.g. `-p0`, `-p1` etc.) -- `-ONAME`: named arguments (e.g. `-Otest`, `-Onumber` etc.) - -The arguments will be passed to the script. - -An invocation via a button in javascript could look like: - -.. code-block:: javascript - - var _make_sss_button = function (entity) { - const script = "script.py"; - - const scripting_form = $(` - <form class="btn-group-xs ${_css_class_export_button}" - method="POST" - action="/scripting"> - <input type="hidden" name="call" value="${script}"/> - <input name="-p0" value=""/> - <button type="submit" class="btn btn-link">Start script</button> - </form>`); - return scripting_form[0]; - } - -For more information see the :doc:`specification of the API <../specification/Server-side-scripting>` - -Calling from the webui ---------------------- -Refer to `webui documentation <https://docs.indiscale.com//caosdb-webui/extension/forms.html#calling-a-server-side-script>`_ to learn how to setup the webui side of this interaction. - -The following example assumes that the form in the webui has only one filed -which is a file upload with the name ``csvfile``. - - -.. code-block:: python - - import os - import linkahead as db - from caosadvancedtools.serverside import helper - from caosadvancedtools.serverside.logging import configure_server_side_logging - - def main(): - parser = helper.get_argument_parser() - args = parser.parse_args() - db.configure_connection(auth_token=args.auth_token) - # setup logging and reporting if serverside execution - userlog_public, htmluserlog_public, debuglog_public = configure_server_side_logging() - - if not hasattr(args, "filename") or not args.filename: - raise RuntimeError("No file with form data provided!") - - # Read the input from the form (form.json) - with open(args.filename) as form_json: - form_data = json.load(form_json) - - # files are uploaded to this dicectory - upload_dir = os.path.dirname((args.filename)) - # Read content of th uplaoded file - csv_file_path = os.path.join(upload_dir, form_data["csvfile"]) - - # Do something with the upload csv file... - - - if __name__ == "__main__": - main() - - +The documentation was updated and moved to the :doc:`linkahead's documentation <caosdb-deploy/server_side_scripting.html>`.