Update documentation

This commit is contained in:
Jan Eitzinger 2023-06-13 14:35:57 +02:00
parent 76d6943691
commit 18bbd11c5e
5 changed files with 89 additions and 3 deletions

View File

@ -30,7 +30,7 @@ You find more detailed information here:
**NOTICE** **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. 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 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. 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. 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. 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 ## Database initialization and migration

13
docs/adm-customization.md Normal file
View File

@ -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.

73
docs/adm-upgrade.md Normal file
View File

@ -0,0 +1,73 @@
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. 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.

View File

@ -10,7 +10,7 @@ else
rm ./job-archive-demo.tar rm ./job-archive-demo.tar
cp ./configs/env-template.txt .env 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 --migrate-db
./cc-backend --server --dev --init-db --add-user demo:admin:demo ./cc-backend --server --dev --init-db --add-user demo:admin:demo