cic-staff-installer/README.md

# CIC STAFF CLIENT

Services installer temporarily for internal use by GE.


## Dependencies

The os-level dependencies below must be met both at install and run time.

The version numbers are the version numbers used at implmentation time. It may very well work with earlier versions of the components, as long as they are not too old. An internet connection will be needed if the python dependencies cannot be resolved locally, either through a local repository or an existing package cache.

- systemd (249)
- gcc (11.1.0)
- git (2.33.0)
- python (>= 3.9)
- pip (20.3.4)
- sqlite (3.36.0)

For the optional bloxberg node build (`INSTALL_EVM=bloxberg`), additionally these dependencies must be met, aswell as a working internet connection:

- rustup (1.24.3)
- clang (12.0.1)
- cmake (3.21.2)


## Installation settings

The examples below assume working directory of the cic-staff-installer repository root.

<!--The `CIC_ROOT_URL` environment variable points to a location where top-level configuration settings can be found. These are individual files named after the environment variables they are setting, whose contents are signed by the trusted key defined in `CIC_SETUP_TRUSTED_FINGERPRINT`.-->

### cic-stack docker-compose cluster settings

To use against the cic-stack docker-compose local cluster:

```
export RPC_PROVIDER=http://localhost:63545
export CIC_ROOT_URL=file://`pwd`/var
```

If you want to select python packages from a specific repository only, also add:

```
export PIP_INDEX_URL=<url>
export PIP_EXTRA_INDEX_URL=<url>
```

#### Bloxberg 

If you want to build the bloxberg mode executable (be warned, that's a long wait), add:

```
export INSTALL_EVM=bloxberg
```

If you wish, you can use an existing openethereum executable instead. Make sure `<path_to_binary> --version` shows `2.7.2`, and then set:


```
export OPENETHEREUM_PATH=<path_to_binary>
```


## Installation

To proceed with the installation, enter:

```
bash setup.sh
```

During the installation you will be prompted to enter your name, email and as password for the gnupg setup. 

The gnupg key will both be used to authenticate using HTTP HOBA when necessary, aswell as encrypt local cached content.




## Running the services

```
systemctl --user start cic-cache-tracker
systemctl --user start cic-cache-server
```

Verify that they are running

```
systemctl --user status cic-cache-tracker
systemctl --user status cic-cache-server
```

The bloxberg node, if installed, runs in the same manner:

```
systemctl --user start bloxberg
systemctl --user status bloxberg
```


## Using `clicada`

It should now be possible to run `clicada` without any extra settings needed.

Please refer to the documentation on `clicada` for details on how to use the tool.


## Files and directories

The installation produces a number of files in the user home directory, some of which may be edited directly to change behavior of the program.

All paths relative to `$HOME`

| location | description | editable |
|-|-|-|
| `.config/cic/cache/*.ini` | Configuration file(s) for the `cic-cache-*` services | yes |
| `.config/cic/cache/*.ini` | Configuration file(s) for the `cic-cache-*` services | yes |
| `.config/cic/clicada/*.ini` | Configuration file(s) for the `clicada` tool | yes |
| `.config/cic/staff-client/key_fingerprint` | gnupg key fingerprint for key used by clicada for authentication | no |
| `.config/cic/staff-client/user.asc` | gnupg public key used by cicada for authentication | no |
| `.config/cic/staff-client/.gnupg` | gnupg homedir used by cicada for authentication | no |
| `.config/systemd/user/cic-cache-*.service` | systemd user service definition file for `cic-cache-*` services | yes, with `systemctl --user edit <service>` |
| `.config/systemd/user/bloxberg.service` | systemd user service definition file for bloxberg | yes, with `systemctl --user edit <service>` |
| `.config/environment.d/01-cic-cache-*.conf` | environment variables for systemd user services | yes |
| `.local/share/cic/.gnupg` | gnupg homedir for holding trust keys for global cic configurations | no |
| `.local/share/cic/clicada/.secret` | A gnupg encrypted symmetric secret used to encrypt local cached content | no |
| `.local/share/io.parity.ethereum/bloxberg` | Bloxberg chain data | no |
| `.config/io.parity.ethereum/bloxberg` | Bloxberg configurations and chain data | bootnode.toml and bootnode.txt only |


## Installing as a different user

You may want to create a dedicated user for the installation, so as to not pollute your regular user data directories.

Since the services are run using systemd, a simple `su` or `sudo` will not be sufficient in this case.

Perhaps the simplest solution is to launch a new login shell within the systemd vm using the following command:

```
machinectl login
```

Another alternative can be to open an `ssh` session.


## Advanced topics

### Changing the resource settings trusted key

The top-level settings for the applications are set from files in `<repo_root>/var/cic-staff-client`. These files are signed with PGP, and the trusted key(s) for signing are in `<repo_root>/keys`. 

In order to define alternate settings, a different key must be imported and trusted, and this key must sign the new settings files.

The code below assumes the key with fingerprint `F3FAF668E82EF5124D5187BAEF26F4682343F692`:

```
echo "F3FAF668E82EF5124D5187BAEF26F4682343F692:6:" >> <repo_root>/keys/trust
gpg -a F3FAF668E82EF5124D5187BAEF26F4682343F692 --export  > <repo_root>/keys/F3FAF668E82EF5124D5187BAEF26F4682343F692.asc
```

Now the private key holder can ceate the same contents as in `<repo_root>/var`, e.g. to set `CIC_REGISTRY_ADDRESS` in `<repo_root>/var/alt`:

```
mkdir -vp var/alt/cic-staff-client
d=`mktemp -d`
echo -n 0xcf60ebc445b636a5ab787f9e8bc465a2a3ef8299 > $d/CIC_REGISTRY_ADDRESS
gpg -a -s -u F3FAF668E82EF5124D5187BAEF26F4682343F692 -o var/alt/cic-staff-client/CIC_REGISTRY_ADDRESS $d/CIC_REGISTRY_ADDRESS
```

Running the process again you would replace this:

```
export CIC_ROOT_URL=file://`pwd`/var/alt
```