Merge branch 'f-readme-remote-server' into 'dev'

Readme remote server

See merge request !2

README.md

@@ -7,14 +7,34 @@ CaosDB project.
 
 # Getting started #
 
-- To run tests, start up a CaosDB server with (documentation for this can be found elsewhere).
+- To run tests, start up a CaosDB server with the following properties (documentation for this can
+  be found elsewhere):
   - The CaosDB server must have debugging enabled.
-  - Certificates must be valid and be listed in `pycaosdb.ini`.
-- Modify `pycaosdb.ini.template` accordingly and save it as `pycaosdb.ini`.
+  - The database should be empty.
+- Modify `pycaosdb.ini.template` and save it as `pycaosdb.ini`, taking care of the following points:
+  - Certificates must be valid and be specified in `pycaosdb.ini`.
+  - Server-side scripting paths must be given, otherwise server-side scripting will be omitted.
 - Run the tests with `pytest` or `pytest-3` (depending on your system).
 - If you want to run just a single test, you can also select a single test file:  
   `pytest-3 tests/test_issues.py`
 
+## Requirements ##
+
+- Running the tests needs `pytest`, obviously, and also the `nose` library:
+  - `pip3 install pytest nose`
+
+## Run tests agains a remote caosdb server
+
+* There is a special mark `local_server`, which marks all test which cannot
+  pass when the server is not on the host where the test suite is running.
+* Start tests with `pytest -m "not local_server"` or
+  `tox -- -m "not local_server"`.
+* The remote caosdb server must have a TLS certificate which maches the name given in
+  `pycaosdb.ini`.  If you use the *LinkAhead* distribution of CaosDB, this can be achieved by:
+    * `linkahead cert_gen -- --hostname <your hostname>`
+    * `linkahead certs -d <your profile path>/custom/other/cert`
+    * `linkahead start`
+
 # Further Reading
 
 Please refer to the [official gitlab repository of the CaosDB
@@ -24,7 +44,8 @@ project](https://gitlab.com/caosdb/caosdb) for more information.
 
 Copyright (C) 2018 Research Group Biomedical Physics, Max Planck Institute for
 Dynamics and Self-Organization Göttingen.
+Copyright (C) 2021 Indiscale GmbH <info@indiscale.com>
 
-All files in this repository are licensed under a [GNU Affero General Public
+All files in this repository are licensed under the [GNU Affero General Public
 License](LICENCE.md) (version 3 or later).
 

pycaosdb.ini.template

 # -*- mode:conf; -*-
-## This sections needs to exist in addition to the usual section
+
+## This sections must exist in addition to the usual section.
 [IntegrationTests]
-test_server_side_scripting.bin_dir.local=/path/to/scripting/bin
-test_server_side_scripting.bin_dir.server=/opt/caosdb/git/caosdb-server/scritping/bin
+########## Server-side scripting ##################
+## These are used by tests of server side scripting. Both paths have
+## to point to existing directories in which the CaosDB server has the
+## permissions to create and execute scripts.
+
+# location of the scripting bin dir which is used for the test scripts from the
+# pyinttest's perspective.
+#test_server_side_scripting.bin_dir.local=/path/to/scripting/bin
+
+# location of the scripting bin dir which is used for the test scripts from the
+# server's perspective.
+#test_server_side_scripting.bin_dir.server=/opt/caosdb/git/caosdb-server/scripting/bin
+
+########## Files ##################
+## Used by tests of file handling. Specify the path to an existing
+## directory in which file tests are performed, once as seen by the
+## host and once as seen by the server.
+
+# location of the files from the pyinttest (i.e. host) perspective
+#test_files.test_insert_files_in_dir.local=/extroot/test_insert_files_in_dir/
+
+# location of the files from the caosdb server's perspective
+#test_files.test_insert_files_in_dir.server=/opt/caosdb/mnt/extroot/test_insert_files_in_dir/
 
-# location of the files from the pyinttest perspective
-test_files.test_insert_files_in_dir.local=/extroot/test_insert_files_in_dir/
-# location of the files from the caosdb_servers perspective
-test_files.test_insert_files_in_dir.server=/opt/caosdb/mnt/extroot/test_insert_files_in_dir/
+########## Authentication tokens ##################
+# # location of the one-time tokens from the pyinttest's perspective
+# test_authentication.admin_token_crud = /authtoken/admin_token_crud.txt
+# test_authentication.admin_token_expired = /authtoken/admin_token_expired.txt
+# test_authentication.admin_token_3_attempts = /authtoken/admin_token_3_attempts.txt
 
-# location of the one-time tokens from the pyinttest's perspective
-test_authentication.admin_token_crud = /authtoken/admin_token_crud.txt
-test_authentication.admin_token_expired = /authtoken/admin_token_expired.txt
-test_authentication.admin_token_3_attempts = /authtoken/admin_token_3_attempts.txt
 
 ## Insert your usual settings here
 [Connection]
 #url=https://caosdb-server:10443/
-#username=admin
-#cacert=/path/to/cert/caosdb.cert.pem
-#cacert=/etc/ssl/cert.pem
-#debug=0
 
+## Some integration tests will fail without valid credentials.
+#username=admin
 #password_method=plain
 #password=caosdb
 
+## Provide SSL certificate used by the CaosDB server for all tests to
+## run. Some integration tests will fail without a valid certificate here.
+#cacert=/path/to/cert.pem
+
+#debug=0
 #ssl_insecure=True
 #timeout=500