Command Line Reference
======================
Lakesuperior comes with some command-line tools aimed at several purposes.
If Lakesuperior is installed via ``pip``, all tools can be invoked as normal
commands (i.e. they are in the virtualenv ``PATH``).
The tools are currently not directly available on Docker instances (*TODO add
instructions and/or code changes to access them*).
``lsup-server``
---------------
Single-threaded server. Use this for testing, debugging, or to multiplex via
WSGI in a Windows environment. For non-Windows production environments, use
``fcrepo``.
``fcrepo``
----------
This is the main server command. It has no parameters. The command spawns
Gunicorn workers (as many as set up in the configuration) and can be sent in
the background, or started via init script.
The tool must be run in the same virtual environment Lakesuperior
was installed in (if it was)—i.e.::
source <virtualenv root>/bin/activate
must be run before running the server.
Note that if ``app_mode`` is set to ``prod`` in :doc:`application.yml
<config>`, the server will just print the configuration and immediately go in
the background without logging anything on screen (daemon mode).
In the case an init script is used, ``coilmq`` (belonging to a 3rd party
package) needs to be launched as well; unless a message broker is already set
up, or if messaging is disabled in the configuration.
**Note:** This command is not available in Windows because GUnicorn is not
available in Windows. Windows users should look for alternative WSGI servers
to run the single-threaded service (``lsup-server``) over multiple processes
and/or threads.
``lsup-admin``
--------------
``lsup-admin`` is the principal repository management tool. It is
self-documented, so this is just a redundant overview::
$ lsup-admin
Usage: lsup-admin [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
bootstrap Bootstrap binary and graph stores.
check_fixity [STUB] Check fixity of a resource.
check_refint Check referential integrity.
cleanup [STUB] Clean up orphan database items.
migrate Migrate an LDP repository to Lakesuperior.
stats Print repository statistics.
All entries marked ``[STUB]`` are not yet implemented, however the
``lsup_admin <command> --help`` command will issue a description of what
the command is meant to do. Check the
`issues page <https://github.com/scossu/lakesuperior/issues>`__ for what's on
the radar.
All of the above commands are also available via, and based upon, the
native Python API.
``lsup-benchmark``
------------------
This command is used to run performance tests in a predictable way.
The command line options can be queried with the ``--help`` option::
Usage: lsup-benchmark [OPTIONS]
Run the benchmark.
Options:
-m, --mode TEXT Mode of ingestion. One of `ldp`, `python`. With
the former, the HTTP/LDP web server is used. With
the latter, the Python API is used, in which case
the server need not be running. Default:
http://localhost:8000/ldp
-e, --endpoint TEXT LDP endpoint. Only meaningful with `ldp` mode.
Default: http://localhost:8000/ldp
-c, --count INTEGER Number of resources to ingest. Default: {def_ct}
-p, --parent TEXT Path to the container resource under which the new
resources will be created. It must begin with a
slash (`/`) character. Default: /pomegranate
-d, --delete-container Delete container resource and its children if
already existing. By default, the container is not
deleted and new resources are added to it.
-X, --method TEXT HTTP method to use. Case insensitive. Either PUT
or POST. Default: PUT
-s, --graph-size INTEGER Number of triples in each random graph, rounded
down to a multiple of 8. Default: 200
-S, --image-size INTEGER Size of random square image, in pixels for each
dimension, rounded down to a multiple of 8.
Default: 1024
-t, --resource-type TEXT Type of resources to ingest. One of `r` (only LDP-
RS, i.e. RDF), `n` (only LDP-NR, i.e. binaries),
or `b` (50/50% of both). Default: r
-P, --plot Plot a graph of ingest timings. The graph figure
is displayed on screen with basic manipulation and
save options.
--help Show this message and exit.
The benchmark tool is able to create RDF sources, or non-RDF, or an equal mix
of them, via POST or PUT, in a given lDP endpoint. It runs single threaded.
The RDF sources are randomly generated graphs of consistent size and
complexity. They include a mix of in-repository references, literals, and
external URIs. Each graph has 200 triples by default.
The non-RDF sources are randomly generated 1024x1024 pixel PNG images.
You are warmly encouraged to run the script and share the performance results (
*TODO add template for posting results*).
``lsup-profiler``
-----------------
This command launches a single-threaded HTTP server (Flask) on port 5000 that
logs profiling information. This is useful for analyzing application
performance.
For more information, consult the `Python profilers guide
<https://docs.python.org/3/library/profile.html>`__.
Do not launch this while a WSGI server (``fcrepo``) is already running, because
that also launches a Flask server on port 5000.
Locust (experimental)
---------------------
`Locust <http://locust.io>`__ is an HTTP load tester. It can launch many
requests on an HTTP endpoint. A rudimentary Locust file is currently available.
To run Locust against Lakesuperior or FCREPO, run in the project root::
locust -f lakesuperior/util/locustfile.py http://localhost:8000/