Merge pull request #329 from RDFLib/david/example-env-files-update-re…

…admes

docs: add example .env files and

.env-full-template

@@ -0,0 +1,101 @@
+############################################
+## SPARQL configuration (defaults)
+############################################
+SPARQL_ENDPOINT=""
+SPARQL_USERNAME=""
+SPARQL_PASSWORD=""
+SPARQL_REPO_TYPE="remote"
+SPARQL_TIMEOUT="30"  # in seconds
+ENABLE_SPARQL_ENDPOINT="false"
+
+############################################
+## Basic server configuration (defaults)
+############################################
+PROTOCOL="http"
+HOST="localhost"
+PORT="8000"
+SYSTEM_URI="http://localhost:8000"
+
+############################################
+## RDF & data handling (defaults)
+############################################
+CURIE_SEPARATOR=":"
+ORDER_LISTS_BY_LABEL="true"
+LISTING_COUNT_LIMIT="100"
+SEARCH_COUNT_LIMIT="10"
+DISABLE_PREFIX_GENERATION="false"
+DEFAULT_LANGUAGE="en"
+LOCAL_RDF_DIR="rdf"
+ENDPOINT_STRUCTURE='["catalogs","collections","items"]'
+
+############################################
+## Predicate lists (defaults)
+## Expressed here as JSON for clarity
+############################################
+LABEL_PREDICATES='[
+  "http://www.w3.org/2004/02/skos/core#prefLabel",
+  "http://purl.org/dc/terms/title",
+  "http://www.w3.org/2000/01/rdf-schema#label",
+  "https://schema.org/name"
+]'
+DESCRIPTION_PREDICATES='[
+  "http://www.w3.org/2004/02/skos/core#definition",
+  "http://purl.org/dc/terms/description",
+  "https://schema.org/description"
+]'
+PROVENANCE_PREDICATES='[
+  "http://purl.org/dc/terms/provenance"
+]'
+SEARCH_PREDICATES='[
+  "http://www.w3.org/2000/01/rdf-schema#label",
+  "http://www.w3.org/2004/02/skos/core#prefLabel",
+  "http://www.w3.org/2004/02/skos/core#altLabel",
+  "http://www.w3.org/2004/02/skos/core#hiddenLabel",
+  "https://schema.org/name",
+  "http://purl.org/dc/terms/title"
+]'
+OTHER_PREDICATES='[
+  "https://schema.org/color",
+  "http://purl.org/linked-data/registry#status"
+]'
+
+############################################
+## System endpoints (defaults)
+## For illustration; exact URIs can vary
+############################################
+SYSTEM_ENDPOINTS='[
+  "http://example.org/endpoint/system/profile-listing",
+  "http://example.org/endpoint/system/profile-object"
+]'
+
+############################################
+## Logging (defaults)
+############################################
+LOG_LEVEL="INFO"
+LOG_OUTPUT="stdout"
+
+############################################
+## Prez metadata (defaults)
+############################################
+PREZ_TITLE="Prez"
+PREZ_DESC="A web framework API for delivering Linked Data. It provides read-only access to Knowledge Graph data which can be subset according to information profiles."
+PREZ_VERSION=""
+PREZ_CONTACT=""
+
+############################################
+## Feature flags (defaults)
+############################################
+ENABLE_OGC_FEATURES="true"
+OGC_FEATURES_MOUNT_PATH="/catalogs/{catalogId}/collections/{recordsCollectionId}/features"
+CUSTOM_ENDPOINTS="false"
+CONFIGURATION_MODE="false"
+
+############################################
+## Misc (defaults)
+############################################
+TEMPORAL_PREDICATE="https://schema.org/temporal"
+PREZ_UI_URL=""
+SEARCH_METHOD="default"
+REQUIRED_HEADER=""
+PROXY_HEADERS="false"
+FORWARDED_ALLOW_IPS="127.0.0.1"

.env-required-template

@@ -0,0 +1,4 @@
+SPARQL_ENDPOINT=http://my-sparql-endpoint
+## Alternatively
+SPARQL_REPO_TYPE=pyoxigraph
+LOCAL_RDF_DIR=/path/to/your/data

.gitignore

@@ -7,7 +7,8 @@ __pycache__/
 .env*
 dist/
 build/
-!.env-template
+!.env-required-template
+!.env-full-template
 rdf/
 http/
 /.python-version

README.md

@@ -40,6 +40,12 @@ poetry install
 
 > **Note:** Poetry must be installed on the system. To check if you have Poetry installed run `poetry --version`. For tips on installing and managing specific dependency groups check the [documentation](https://python-poetry.org/docs/managing-dependencies/).
 
+## Running a demonstration instance
+
+[Docker Compose](https://docs.docker.com/compose/) can be used to run a demonstration instance. The compose files comprises three services: Prez (Prez API), Prez UI, and Fuseki. To run the stack, change directory into the `demo` directory and run: `docker compose up`.
+
+The Fuseki instance is empty, but can have data added to it, such as the test data under `test_data`.
+
 ## Endpoints
 
 Prez delivers the following endpoints:
@@ -92,115 +98,111 @@ The following Environment Variables can be used to configure Prez:
 These can be set in a '.env' file which will get read in via python-dotenv.
 Alternatively, set them directly in the environment from which Prez is run.
 
+An example .env file with the minimum required variables is in the repo as [`.env-required-template`](./.env-required-template), and an example .env file with all possible configuration variables, showing defaults, is in the repo as [`.env-full-template`](./.env-full-template).
+
 #### SPARQL Endpoint Configuration
 
-- **`sparql_endpoint`**: Read-only SPARQL endpoint for Prez. Default is `None`.
-- **`sparql_username`**: A username for the Prez SPARQL endpoint, if required by the RDF DB. Default is `None`.
-- **`sparql_password`**: A password for the Prez SPARQL endpoint, if required by the RDF DB. Default is `None`.
-- **`enable_sparql_endpoint`**: Whether to enable the SPARQL endpoint. I.e. whether prez exposes the remote repository's SPARQL endpoint (typically a triplestore). Default is `False`. NB the SPARQL endpoint when enabled supports POST requests. Prez itself does not make any updates to the remote repository (e.g. the remote Triplestore), however, if the remote SPARQL endpoint is enabled it is then possible that users can make updates to the remote repository using the SPARQL endpoint.
+- **`SPARQL_ENDPOINT`**: Read-only SPARQL endpoint for Prez. Default is `None`.
+- **`SPARQL_USERNAME`**: A username for the Prez SPARQL endpoint, if required by the RDF DB. Default is `None`.
+- **`SPARQL_PASSWORD`**: A password for the Prez SPARQL endpoint, if required by the RDF DB. Default is `None`.
+- **`ENABLE_SPARQL_ENDPOINT`**: Whether to enable the SPARQL endpoint. I.e. whether prez exposes the remote repository's SPARQL endpoint (typically a triplestore). Default is `False`. NB the SPARQL endpoint when enabled supports POST requests. Prez itself does not make any updates to the remote repository (e.g. the remote Triplestore), however, if the remote SPARQL endpoint is enabled it is then possible that users can make updates to the remote repository using the SPARQL endpoint.
+
 
 #### Network Configuration
 
-- **`protocol`**: The protocol used to deliver Prez. Default is `"http"`.
-- **`host`**: Prez's host domain name. Default is `"localhost"`.
-- **`port`**: The port Prez is made accessible on. Default is `8000`.
+- **`PROTOCOL`**: The protocol used to deliver Prez. Default is `"http"`.
+- **`HOST`**: Prez's host domain name. Default is `"localhost"`.
+- **`PORT`**: The port Prez is made accessible on. Default is `8000`.
 
 #### System URI
 
-- **`system_uri`**: An IRI for the Prez system as a whole. This value appears in the landing page RDF delivered by Prez (`"/"`). Default is `f"{protocol}://{host}:{port}"`.
+- **`SYSTEM_URI`**: An IRI for the Prez system as a whole. This value appears in the landing page RDF delivered by Prez (`"/"`). Default is `f"{protocol}://{host}:{port}"`.
 
 #### Logging Configuration
 
-- **`log_level`**: Logging level. Default is `"INFO"`.
-- **`log_output`**: Logging output destination. Default is `"stdout"`.
+- **`LOG_LEVEL`**: Logging level. Default is `"INFO"`.
+- **`LOG_OUTPUT`**: Logging output destination. Default is `"stdout"`.
 
 #### Prez Metadata
 
-- **`prez_title`**: Title for the Prez instance. Default is `"Prez"`.
-- **`prez_desc`**: Description of the Prez instance. Default is a description of the Prez web framework API.
-- **`prez_version`**: Version of the Prez instance. Default is `None`.
+- **`PREZ_TITLE`**: Title for the Prez instance. Default is `"Prez"`.
+- **`PREZ_DESC`**: Description of the Prez instance. Default is a description of the Prez web framework API.
+- **`PREZ_VERSION`**: Version of the Prez instance. Default is `None`.
 
 #### CURIE Separator
 
-- **`curie_separator`**: Separator used in CURIEs. Default is `":"`. This separator appears in links generated by Prez, and in turn in URL paths.
-#### Ordering and Predicate Configuration
-
-- **`order_lists_by_label`**: Whether to order lists by label. Default is `True`.
+- **`CURIE_SEPARATOR`**: Separator used in CURIEs. Default is `":"`. This separator appears in links generated by Prez, and in turn in URL paths.
 
-##### Label Predicates
+#### Predicate Configuration
 Used for displaying RDF with human readable labels.
-- **`label_predicates`**: List of predicates used for labels. Default includes:
+- **`LABEL_PREDICATES`**: List of predicates used for labels. Default includes:
     - `skos:prefLabel`
     - `dcterms:title`
     - `rdfs:label`
     - `sdo:name`
 > When an annotated (`+anot`) mediatype is used, Prez includes triples for *every* URI in the initial response which has one of the above properties. These annotation triples are then cached. The annotations are used for display purposes, for example HTML pages. 
 ##### Description Predicates
 Similar to label predicates above.
-- **`description_predicates`**: List of predicates used for descriptions. Default includes:
+- **`DESCRIPTION_PREDICATES`**: List of predicates used for descriptions. Default includes:
     - `skos:definition`
     - `dcterms:description`
     - `sdo:description`
 ##### Provenance Predicates
 Similar to provenance predicates above.
-- **`provenance_predicates`**: List of predicates used for provenance. Default includes:
+- **`PROVENANCE_PREDICATES`**: List of predicates used for provenance. Default includes:
     - `dcterms:provenance`
 
 ##### Other Predicates
 The annotation mechanism can further be used to generally return certain properties wherever present.
-- **`other_predicates`**: List of other predicates. Default includes:
+- **`OTHER_PREDICATES`**: List of other predicates. Default includes:
     - `sdo:color`
     - `reg:status`
     - `skos:narrower`
     - `skos:broader`
 
 #### SPARQL Repository Configuration
 
-- **`sparql_repo_type`**: Type of SPARQL repository. Default is `"remote"`. Options are `"remote"`, `"pyoxigraph"`, and `"oxrdflib"`
-- **`sparql_timeout`**: Timeout for SPARQL queries. Default is `30`.
+- **`SPARQL_REPO_TYPE`**: Type of SPARQL repository. Default is `"remote"`. Options are `"remote"`, `"pyoxigraph"`, and `"oxrdflib"`
+- **`SPARQL_TIMEOUT`**: Timeout for SPARQL queries. Default is `30`.
 
 #### Contact Information
 
-- **`prez_contact`**: Contact information for Prez. Default is `None`.
+- **`PREZ_CONTACT`**: Contact information for Prez. Default is `None`.
 
 #### Prefix Generation
 
-- **`disable_prefix_generation`**: Whether to disable prefix generation. **It is recommended to disable prefix generation for large data repositories**, further, it is recommended to always specify prefixes in the `prez/reference_data/prefixes/` directory. Default is `False`.
+- **`DISABLE_PREFIX_GENERATION`**: Whether to disable prefix generation. **It is recommended to disable prefix generation for large data repositories**, further, it is recommended to always specify prefixes in the `prez/reference_data/prefixes/` directory. Default is `False`.
 #### Language and Search Configuration
 
-- **`default_language`**: Default language for Prez. Default is `"en"`.
-- **`default_search_predicates`**: Default search predicates. Default includes:
+- **`DEFAULT_LANGUAGE`**: Default language for Prez. Default is `"en"`.
+- **`DEFAULT_SEARCH_PREDICATES`**: Default search predicates. Default includes:
     - `rdfs:label`
     - `skos:prefLabel`
     - `sdo:name`
     - `dcterms:title`
 
 #### Local RDF Directory
 Used in conjunction with the Pyoxigraph repo. Specifies a directory (from the repository root) to load into the Pyoxigraph in memory data graph. Not used for other repository types.
-- **`local_rdf_dir`**: Directory for local RDF files. Default is `"rdf"`.
+- **`LOCAL_RDF_DIR`**: Directory for local RDF files. Default is `"rdf"`.
 
 #### Endpoint Structure
 
-- **`endpoint_structure`**: Default structure of the endpoints, used to generate links. Default is `("catalogs", "collections", "items")`.
+- **`ENDPOINT_STRUCTURE`**: Default structure of the endpoints, used to generate links. Default is `("catalogs", "collections", "items")`.
 
 #### System Endpoints
 
-- **`system_endpoints`**: List of system endpoints. Default includes:
+- **`SYSTEM_ENDPOINTS`**: List of system endpoints. Default includes:
     - `ep:system/profile-listing`
     - `ep:system/profile-object`
 
 #### Listing and Search Configuration
 
-- **`listing_count_limit`**: The maximum number of items to count for a listing endpoint. Counts greater than this limit will be returned as ">N" where N is the limit. Default is `100`.
-- **`search_count_limit`**: The maximum number of items to return in a search result. Default is `10`.
+- **`LISTING_COUNT_LIMIT`**: The maximum number of items to count for a listing endpoint. Counts greater than this limit will be returned as ">N" where N is the limit. Default is `100`.
+- **`SEARCH_COUNT_LIMIT`**: The maximum number of items to return in a search result. Default is `10`.
 
 #### Temporal Configuration
 
-- **`temporal_predicate`**: The predicate used for temporal properties. Default is `sdo:temporal`.
-
-#### Query Template Configuration
-
-- **`endpoint_to_template_query_filename`**: A dictionary mapping endpoints to query template filenames. Default is an empty dictionary.
+- **`TEMPORAL_PREDICATE`**: The predicate used for temporal properties. Default is `sdo:temporal`.
 
 ## Running
 

main.py

@@ -1,9 +1,18 @@
 from os import environ
 
-import uvicorn
 from dotenv import load_dotenv
 
 if __name__ == "__main__":
+    try:
+        import uvicorn
+    except ImportError:
+        print(
+            'Error: Uvicorn is not installed. Install it with \'poetry install --extras "server".'
+        )
+        import sys
+
+        sys.exit(1)
+
     # Load config from .env file.
     # See .env-template and prez/config.py for usage.
     load_dotenv()