# Kroker

Kroker is a program developed by [Fixpoint][] to mediate the connection between [Kompira][] and the customers' network.

[fixpoint]: https://www.fixpoint.co.jp/
[kompira]: https://www.kompira.jp/

Note that all the commands described in this documentation assume that you are working in the `./kroker` directory after unarchived the package.

> **Note**
>
> Use `docker-compose` instead of `docker compose` when Docker Compose v1 or a standalone variant is used.
> For example, type `docker-compose run kroker setup` instead of `docker compose run kroker setup`.

## Install

First of all, load a docker image of Kroker like.

```
docker load -i kroker.tar
```

Register Kroker to Kompira by the following command.
The program will ask you to input the Kompira space name.
Access to the URL with a web browser and complete registration.

```
docker compose run kroker setup
```

This command will generate an identity file of Kroker as `.certs/id_rsa`.
Kompira will use this identity file to identify Kroker so do not move or remove it.

If the above failed with "Error: Permission denied (os error 13)" or similar, use the following command instead.

```
docker compose run -u "$(id -u):$(id -g)" kroker setup
```

## Usage

Start connection between Kroker and Kompira with the following command.

```
docker compose up -d
```

To see logs of Kroker, use the following command.

```
docker compose logs
```

Stop connection between Kroker and Kompira by the following command.

```
docker compose stop
```

## Configuration

Copy `docker-compose.override.yml.example` to `docker-compose.override.yml` and follow comments on the file to configure.
See [Share Compose configurations between files and projects](https://docs.docker.com/compose/extends/#multiple-compose-files) for more detail about overriding configuration by the `docker-compose.override.yml` file.

**NOTE: Please ensure that indentation levels are kept from `docker-compose-override.yml.example` even after modification. The YAML file uses indentation level to represent a range of a block.**

### Change logging level

Modify `KROKER_LOG` in copied `docker-compose.override.yml` like below to change Kroker's logging level.
Available value is one of `debug`, `info`, `warn`, or `error`.

```yaml
# Logging level.
# Available value is one of "debug", "info", "warn", or "error".
# Kroker conceals any value in non debug log that might include
# confidential information, shown as "**CONCEALED**."
# Additionally, non debug log records are reported as-is to Kompira
# independent of this configuration.
KROKER_LOG: "debug"
```

### Use HTTP proxy

Modify `KROKER_HTTP_XXXXX` in `docker-compose.override.yml` like below to use HTTP proxy for connecting Kompira.

```yaml
# Uncomment and fill followings to enable HTTP proxy.
KROKER_HTTP_PROXY_HOST: "proxy.example.com"
KROKER_HTTP_PROXY_PORT: "8080"

# Uncomment and fill followings to enable HTTP proxy BASIC authentication.
KROKER_HTTP_PROXY_USERNAME: "username"
KROKER_HTTP_PROXY_PASSWORD: "password"
```

### Use pre-release

If you need to use pre-release, uncomment `image` in `docker-compose.override.yml` like below.
Note that pre-release is unstable and is not covered by operation guarantee. Please pay great care when using it.

```yaml
# Uncomment the following to allow use/update Kroker from a prerelease channel.
# Note that Kroker in the prerelease channel might be unstable. Use it with great care.
image: "ghcr.io/fixpoint/kroker:v1-pre"
```

## Upgrade registered Kroker

Overwrite the contents with the one with this package to upgrade registered Kroker.
Upgrade the Docker image by the following command, once all files are overwritten.

```
docker load < kroker.tar
```

After all, restart Kroker with the following commands

```
docker compose down
docker compose up -d
```

You don't need to follow the setup procedure (`kroker setup`) for upgrading.

## Uninstall

If you want to uninstall Kroker, please execute the following command.

```
docker compose down --rmi all --volumes --remove-orphans
```

Then delete the `./kroker` directory.

## System requirements

|                | Support                          | Recommend              |
| -------------- | -------------------------------- | ---------------------- |
| OS             | Linux                            |                        |
| Arch           | x86-64, aarch64                  | x86-64                 |
| Docker         | Version 20.10.5                  | Latest                 |
| Docker Compose | Version 1.28.5<br>Version 2.12.2 | Latest                 |
| CPU            | 2 GHz / 1 core                   | 3 GHz / 2 core or more |
| Memory         | 2 GB                             | 4 GB or more           |
| Network        | 100 Mbps                         | 1 Gbps or more         |
| Storage        | 1 GB                             | 10 GB or more          |

The required amount of storage is a rough indication.
Please determine the proper amount of requirements by measuring the actual usage of storage amount in your environment.
Kroker will halt when there is no storage left.

## License

License of Kroker itself is texted in [General Terms of Use for Fixpoint's "Kompira" (Japanese)](https://www.kompira.jp/Kompira_terms.pdf).

License of guacd composed in the docker image is texted in [`LICENSE.guacd`](./LICENSE.guacd).
The included guacd has been modified to work. See [GitHub repository](https://github.com/fixpoint/guacamole-server) for the changes.
The version of the included guacd can be obtained with the following command:

```
docker compose run --entrypoint cat kroker /guacd_version
```

License of Kroker dependencies are texted in [`kroker-licenses.html`](./kroker-licenses.html).

<p align="center">
<sub>Copyright (C) 2021, Fixpoint, Inc.</sub>
</p>
