Merge pull request #57 from sbliven/docker-run

feat: Docker compose.yaml

Author: sbliven

Development/Documentation.md

@@ -3,67 +3,30 @@
 ## Overview
 The documentation consists of three main parts.
 
-* The "Home Webgpage" of the project , describing the purpose and use cases for the software. The source is located at https://github.com/SciCatProject/scicatproject.github.io 
-* The documentation proper, split into User,Operator,Ingestor and Developer manual. The source is located at https://github.com/SciCatProject/documentation .  It covers all components of the software, i.e  frontend and backend. The documentation tool [honkit](https://honkit.netlify.app/) (successor of gitbook) is used.
-* The documentation of the REST API of the backend. This is generated from the swagger.json file, which itself is generated from the model descriptions in loopback
-
+* The "Home Webpage" of the project , describing the purpose and use cases for the software. The source is located at https://github.com/SciCatProject/scicatproject.github.io
+* The documentation proper, split into User,Operator,Ingestor and Developer manual. The source is located at https://github.com/SciCatProject/documentation . It covers all components of the software, i.e  frontend and backend. The documentation tool [honkit](https://honkit.netlify.app/) (successor of gitbook) is used.
+* The documentation of the REST API of the backend. This is generated from the OpenAPI description, which itself is generated from the model descriptions in the backend code.
 
 All parts are hosted on the [GitHub Pages platform](https://pages.github.com/). The documentation part is "injected" into the GitHub pages automatically by a travis job, which runs after each commit to the documentation repository
 
 The live web site is then visible on the following URLs respectively
 * https://scicatproject.github.io/
 * https://scicatproject.github.io/documentation
-* https://scicatproject.github.io/api
+* The REST API not generated statically but is available from each running SciCat
+  backend (for example, the public [ESS instance](https://scicat.ess.eu/explorer)).
+  <!-- TODO update following completion of https://github.com/SciCatProject/documentation/issues/42 -->
 
 ## Changes and Deployment of Home Webpage
 
-```
-git clone https://github.com/SciCatProject/scicatproject.github.io`
-cd scicatproject.github.io
-
-# make your changes on index.html directly, then git add and git commit as usual
-
-git push origin master
-```
+The homepage is built using [Jekyll](https://jekyllrb.com/) and hosted on GitHub pages.
+The source is located in the repository
+[SciCatProject/scicatproject.github.io](https://github.com/SciCatProject/scicatproject.github.io).
 
-After pushing the changes they will immediately become visible at the URL https://scicatproject.github.io/
+After pushing the changes they will become visible at the URL https://scicatproject.github.io/
 
 ## Changes and Deployment of Manuals
 
-```
-git clone https://github.com/SciCatProject/documentation.git`
-cd documentation
-
-# make your edit/add/commit cycle
-
-npm install honkit --save
-npx honkit build
-```
-
-### Serving the Documentation locally
-
-`npx honkit serve --port 4040`
-
-### Publishing the documentation
-
-`git push origin master`
-
-The push to the origin repo will trigger a travis job, which will publish the resulting documentation to https://scicatproject.github.io/documentation
-
-## Changes and Deployment of API Documentation
-
-Use the following command to regenerate  the API with an up-to-date swagger.json file
-
-```
-    # to install redoc-cli:
-    # sudo npm install -g redoc-cli
-
-    # to get an updated swagger.json file
-    # wget https://YOUR-API-SERVER/explorer/swagger.json
-
-    redoc-cli bundle -o index.html swagger.json
-
-    # the make commit which replaces the index.html file at 
-    # https://github.com/SciCatProject/scicatproject.github.io/tree/master/api
-```
-
+Manuals are built using [honkit](https://honkit.netlify.app/) from the
+[SciCatProject/documentation](https://github.com/SciCatProject/documentation)
+repository. After pushing the changes they will become visible at the URL
+https://scicatproject.github.io/documentation.

Development/v3.x/Documentation.md

@@ -3,7 +3,7 @@
 ## Overview
 The documentation consists of three main parts.
 
-* The "Home Webgpage" of the project , describing the purpose and use cases for the software. The source is located at https://github.com/SciCatProject/scicatproject.github.io 
+* The "Home Webpage" of the project , describing the purpose and use cases for the software. The source is located at https://github.com/SciCatProject/scicatproject.github.io
 * The documentation proper, split into User,Operator,Ingestor and Developer manual. The source is located at https://github.com/SciCatProject/documentation .  It covers all components of the software, i.e  frontend and backend. The documentation tool [honkit](https://honkit.netlify.app/) (successor of gitbook) is used.
 * The documentation of the REST API of the backend. This is generated from the swagger.json file, which itself is generated from the model descriptions in loopback
 
@@ -63,7 +63,6 @@ Use the following command to regenerate  the API with an up-to-date swagger.json
 
     redoc-cli bundle -o index.html swagger.json
 
-    # the make commit which replaces the index.html file at 
+    # the make commit which replaces the index.html file at
     # https://github.com/SciCatProject/scicatproject.github.io/tree/master/api
 ```
-

Development/v4.x/backend/configuration/jobconfig.md

@@ -135,12 +135,14 @@ Many actions can be configured using templates, which get filled when the action
 Template strings use [Handlebars](https://handlebarsjs.com/) syntax. The following
 top-level variables are availabe in the handlebars context:
 
+{% raw %}
 | Top-level variable | Type | Examples | Description |
 |---|---|---|---|
 | `request` | `CreateJobDto` or<br/>`UpdateJobDto` | `{{request.type}}`<br/>`{{request.jobParams}}` | HTTP Request body |
 | `job` | `JobClass` | `{{job.id}}` | The job, as stored in the database. Not available for validate actions. |
 | `datasets` | `DatasetClass[]` | `{{#each datasets}}{{pid}}{{/each}}` | All datasets referenced in `job.jobParams.datasetsList`. |
 | `env` | `object` | `{{env.SECRET_TOKEN}}` | Access environmental variables |
+{% endraw %}
 
 Environmental variables are particularly useful for secrets that should not be stored in
 the config file.
@@ -545,10 +547,12 @@ an incoming job.
 
 All arguments are optional.
 
+{% raw %}
 - `init` (optional): Log message to print during startup. The actions's configuration
   section from jobConfig.yaml is available as a Handlebars context. Default: ""
 - `validate` (optional): Log message to print when the job request is received. The
   request body (aka DTO) is available as a Handlebars context. Default: ""
 - `performJob` (optional): Log message to print after the job is saved to the database.
   The updated job object is available as a Handlebars context.
-  Default: `"Performing job for {{ type }}"`
+  Default: `"Performing job for {{type}}"`
+{% endraw %}

README.md

@@ -9,7 +9,7 @@ See the [SciCat Home Webpage](https://scicatproject.github.io) for an overview o
 
 ## Structure of Documentation
 
-The documentation is split into the following chapters:
+SciCat documentation is split into the following chapters:
 
 * [User Guide](Users) - Users of the system can come here to see screen captures, FAQs and find resources on how to better understand SciCat.
 * [Operator Guide](Operator) - System admins read this part to set up SciCat for their location
@@ -20,3 +20,29 @@ The documentation is split into the following chapters:
 
 [SciCat Project: Data Catalog System (2017)](https://icatproject.org/wp-content/uploads/2017/12/ICAT_F2F_2017_PSI.pdf)
 [SciCat talk from Luke Gorman on Joint ExPaNDS and PaNOSC Meeting Feb 2020](https://indico.esss.lu.se/event/1373/contributions/10773/attachments/9761/15638/Lund2020.pdf)
+
+## Building
+
+Docs are built using [honkit](https://honkit.netlify.app/). This can either be installed locally using npm or run via docker.
+
+### Serving documentation with docker
+
+```
+docker compose up -d
+```
+
+This should start the honkit server on http://localhost:4040. Honkit will watch for changes in the source files and automatically re-build them.
+
+### Serving the Documentation locally
+
+You can also run the honkit server locally using npm:
+
+```
+npm install
+npm run start
+```
+
+## Publishing the documentation
+
+The [website](https://scicatproject.github.io/documentation) will be automatically
+rebuilt after each change to the `master` branch by a github action.

compose.yaml

@@ -0,0 +1,12 @@
+services:
+  serve:
+    image: honkit/honkit:latest
+    command: npm run start
+    ports:
+      - "4040:4040"
+      # livereload port. Can't be changed (https://github.com/GitbookIO/plugin-livereload/pull/1)
+      - "35729:35729"
+    volumes:
+      - .:/app
+    working_dir: /app
+    platform: linux/amd64

package.json

@@ -4,7 +4,8 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start:dev": "honkit serve --port 4500",
+    "start": "honkit serve --port 4040",
+    "build": "honkit build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [],