Merge pull request #130 from ClusterCockpit/hotfix

Update documentation

README.md

@@ -30,7 +30,7 @@ You find more detailed information here:
 
 **NOTICE**
 
-ClusterCockpit requires a recent version of the golang toolchain.
+ClusterCockpit requires a recent version of the golang toolchain and node.js.
 You can check in `go.mod` what is the current minimal golang version required.
 Homebrew and Archlinux usually have up to date golang versions. For other Linux
 distros this often means you have to install the golang compiler yourself.
@@ -107,7 +107,7 @@ Having no jobs in the job-archive at all is fine.
 
 A config file in the JSON format has to be provided using `--config` to override the defaults.
 By default, if there is a `config.json` file in the current directory of the `cc-backend` process, it will be loaded even without the `--config` flag.
-You find documentation of all supported configuration and command line options [here](./configs.README.md).
+You find documentation of all supported configuration and command line options [here](./configs/README.md).
 
 ## Database initialization and migration
 

docs/adm-customization.md

@@ -0,0 +1,13 @@
+# Overview
+
+To customize `cc-backend` means to change the logo and add specific legal texts
+in place of the placeholders. To change the logo shown in the navigation bar the
+file `web/frontend/public/img/logo.png` has to be replaced in the source tree
+and cc-backend has to be rebuild.
+
+# Replace legal texts
+
+To replace the legal texts `imprint.tmpl` and `privacy.tmpl` you can place your
+version in `./var/`. On startup `cc-backend` will check if `./var/imprint.tmpl` and/or
+`./var/privacy.tmpl` exist and use those instead of the builtin placeholders.
+You may use the placeholders in `web/templates` as blueprint.

docs/adm-upgrade.md

@@ -0,0 +1,74 @@
+In general an upgrade is not more then replacing the binary. All files that are
+required, apart from the database file, the configuration file and the job
+archive are embedded into the binary. It is recommended to use a directory where
+the binary filenames are named using some version tag. This may be, e.g., the date or
+unix epoch time. A symbolic link points to the version to be used. This allows
+to easily switch to previous versions.
+
+The database and the job archive are versioned. Every release binary supports
+specific versions of the database and the job archive. In case a version
+mismatch is detected the application will exit and a migration is required.
+
+**IMPORTANT NOTICE**
+
+It is recommended to backup the database before any upgrade. This is mandatory
+in case the database needs to be migrated. In case of sqlite this means to stop
+`cc-backend` and copy the sqlite databse file somewhere.
+
+#  Migrating the database
+After backing up the database execute the the following command to migrate the
+databse to the most recent version:
+```
+$ ./cc-backend -migrate-db
+```
+
+The migration files are embedded into the binary but can be reviewed in the
+cc-backend [source tree](https://github.com/ClusterCockpit/cc-backend/tree/master/internal/repository/migrations).
+There are separate migration files for both supported database backends.
+We use the [migrate library](https://github.com/golang-migrate/migrate).
+
+In case something goes wrong you can check the state and get the current schema
+(here for sqlite):
+```
+$ sqlite3 var/job.db
+```
+In the sqlite console execute:
+```
+.schema
+```
+to get the current databse schema.
+You can query the current version and if the migration failed with:
+```
+SELECT * FROM schema_migrations;
+```
+The first column indicates the current database version and the second column is
+a dirty flag indicating if the migration was successful.
+
+# Migrating the job archive
+
+To migrate the job archive a separate tool (`archive-migration`) is required that is part of the
+`cc-backend` source tree (build with `go build ./tools/archive-migration`) and also provided as part of releases.
+
+Migration is only supported between two subsequent versions. The migration tool
+will migrate the existing job archive into a new job archive. This means there
+has to be enough disk space for two complete job-archives. If the tool is
+called without options:
+```
+$ ./archive-migration
+```
+
+it is assumed that there is a job archive in `./var/job-archive`. The new job
+archive will be written to `./var/job-archive-new`. Because execution is
+threaded in case of a fatal error it is impossible to pinpoint in which job the
+error occured. In this case you can run the tool in debug mode (using the flag
+`-debug`). In debug mode threading will be disabled and the job id of every
+migrated job is printed. Jobs with empty files are skipped. Between multiple runs
+of the tools the directory `job-archive-new` has to be moved or deleted.
+
+The cluster.json files in `job-archive-new` need to be reviewed for errors, in
+particular it has to be checked if the aggregation attribute is set correctly
+for all metrics.
+
+The migration will take in the order of hours for fairly large (several hundred
+GB) job archives. A versioned job archive contains a file `version.txt` in the
+job archive root directory. This file contains the version as unsigned integer.

internal/config/config_test.go

@@ -17,7 +17,7 @@ func TestInit(t *testing.T) {
 }
 
 func TestInitMinimal(t *testing.T) {
-	fp := "../../docs/config.json"
+	fp := "../../configs/config-demo.json"
 	Init(fp)
 	if Keys.Addr != "127.0.0.1:8080" {
 		t.Errorf("wrong addr\ngot: %s \nwant: 127.0.0.1:8080", Keys.Addr)

startDemo.sh

@@ -10,7 +10,7 @@ else
     rm ./job-archive-demo.tar
 
     cp ./configs/env-template.txt .env
-    cp ./docs/config.json config.json
+    cp ./configs/config-demo.json config.json
 
     ./cc-backend --migrate-db
     ./cc-backend --server --dev --init-db --add-user demo:admin:demo