Update doc files

docs/ConfigurationManagement.md

@@ -1,22 +1,22 @@
-# Release versioning
+# Release versions
 
-Releases are numbered with an integer ID, starting with 1.
-Each release embeds the following assets in the binary:
-* Web front-end with Javascript files and all static assets.
+Versions are marked according to [semantic versioning] (https://semver.org).
+Each version embeds the following static assets in the binary:
+* Web frontend with javascript files and all static assets.
 * Golang template files for server-side rendering.
 * JSON schema files for validation.
-* Database migration files
+* Database migration files.
 
 The remaining external assets are:
-* The SQL database used
+* The SQL database used.
 * The job archive
-* The configuration file `config.json`
+* The configuration files `config.json` and `.env`.
 
-Both external assets are also versioned with integer IDs.
+The external assets are versioned with integer IDs.
 This means that each release binary is bound to specific versions of the SQL
 database and the job archive.
-The configuration file is validated against the current schema on startup.
-The command line switch `-migrate-db` can be used to upgrade the SQL database
+The configuration file is checked against the current schema at startup.
+The `-migrate-db` command line switch can be used to upgrade the SQL database
 to migrate from a previous version to the latest one.
 We offer a separate tool `archive-migration` to migrate an existing job archive
 archive from the previous to the latest version.
@@ -24,14 +24,15 @@ archive from the previous to the latest version.
 # Versioning of APIs
 
 cc-backend provides two API backends:
-* A REST API for querying jobs
-* A GraphQL API for data exchange between web frontend and cc-backend
+* A REST API for querying jobs.
+* A GraphQL API for data exchange between web frontend and cc-backend.
 
-Both APIs will also be versioned. We still need to decide wether we will also support
-older REST API version by versioning the endpoint URLs.
+The REST API will also be versioned. We still have to decide whether we will also
+support older REST API versions by versioning the endpoint URLs.
+The GraphQL API is for internal use and will not be versioned.
 
 # How to build
 
-Please always build `cc-backend` with the supplied Makefile. This will ensure
-that the frontend is also built correctly and that the version in the binary file is coded
-in the binary.
+In general it is recommended to use the provided release binary.
+In case you want to build build `cc-backend` please always use the provided makefile. This will ensure
+that the frontend is also built correctly and that the version in the binary is encoded in the binary.

docs/Hands-on.md

@@ -1,9 +1,9 @@
-# CC-HANDSON - Setup ClusterCockpit from scratch (w/o docker)
+# Hands-on setup ClusterCockpit from scratch (w/o docker)
 
 ## Prerequisites
-* Perl
-* Yarn
-* Go
+* perl
+* go
+* npm
 * Optional: curl
 * Script migrateTimestamp.pl
 
@@ -33,22 +33,17 @@ Start by creating a base folder for all of the following steps.
 * Clone Repository
     - `git clone https://github.com/ClusterCockpit/cc-backend.git`
     - `cd cc-backend`
-* Setup Frontend
-    - `cd ./web/frontend`
-    - `yarn install`
-    - `yarn build`
-    - `cd ../..`
-* Build Go Executable
-    - `go build ./cmd/cc-backend/`
-* Activate & Config environment for cc-backend
+* Build
+    - `make`
+* Activate & configure environment for cc-backend
     - `cp configs/env-template.txt  .env`
-    - Optional: Have a look via `vim ./.env`
+    - Optional: Have a look via `vim .env`
     - Copy the `config.json` file included in this tarball into the root directory of cc-backend: `cp ../../config.json  ./`
 * Back to toplevel `clustercockpit`
     - `cd ..`
 * Prepare Datafolder and Database file
     - `mkdir var`
-    - `./cc-backend --migrate-db`
+    - `./cc-backend -migrate-db`
 
 ### Setup cc-metric-store
 * Clone Repository
@@ -112,7 +107,7 @@ Done for checkpoints
     - `cp source-data/job-archive-source/woody/cluster.json cc-backend/var/job-archive/woody/`
 * Initialize Job-Archive in SQLite3 job.db and add demo user
     - `cd cc-backend`
-    - `./cc-backend --init-db --add-user demo:admin:AdminDev`
+    - `./cc-backend -init-db -add-user demo:admin:demo`
     - Expected output:
 ```
 <6>[INFO]    new user "demo" created (roles: ["admin"], auth-source: 0)
@@ -123,7 +118,7 @@ Done for checkpoints
     - `cd ..`
 
 ### Startup both Apps
-* In cc-backend root:  `$./cc-backend --server --dev`
+* In cc-backend root:  `$./cc-backend -server -dev`
     - Starts Clustercockpit at `http:localhost:8080`
         - Log: `<6>[INFO]    HTTP server listening at :8080...`
     - Use local internet browser to access interface
@@ -161,7 +156,7 @@ Content-Length: 119
 ```
 
 ### Development API web interfaces
-The `--dev` flag enables web interfaces to document and test the apis:
+The `-dev` flag enables web interfaces to document and test the apis:
 * http://localhost:8080/playground - A GraphQL playground. To use it you must have a authenticated session in the same browser.
 * http://localhost:8080/swagger - A Swagger UI. To use it you have to be logged out, so no user session in the same browser. Use the JWT token with role Api generate previously to authenticate via http header.