# Kroker

Kroker は [Fixpoint][] が開発する [Kompira][] と利用者のネットワークを仲介するアプリケーションです。

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

なお、ドキュメントに記載しているコマンドは、すべてパッケージ解凍後の `./kroker` ディレクトリ内での作業と仮定しています。

> **Note**
>
> Docker Compose の v1 やスタンドアローン版を利用している場合は `docker compose` の部分を `docker-compose` と読み替えてください。
> 例えば `docker compose run kroker setup` としている部分は、代わりに `docker-compose run kroker setup` を実行してください。

## インストール

まず以下のコマンドで Kroker の Docker イメージを読み込みます。

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

以下のコマンドで Kroker を Kompira に登録します。
Kompira のスペース名の入力が必要です。
表示された URL にブラウザなどでアクセスし、Kroker の登録操作を行ってください。

```
docker compose run kroker setup
```

このコマンドを実行することで、識別ファイルが `.certs/id_rsa` に生成されます。
このファイルは Kompira が Kroker を識別するために利用するため、移動や削除は行わないでください。

上記を実行した際に "Error: Permission denied (os error 13)" のようなエラーで失敗した場合は、代わりに以下のコマンドを実行してください。

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

## 利用方法

以下のコマンドで Kroker と Kompira の接続を開始します。

```
docker compose up -d
```

Kroker のログを見るには以下のコマンドを利用してください。

```
docker compose logs
```

Kroker と Kompira の接続を終了する場合は以下のコマンドを利用してください。

```
docker compose stop
```

## 設定方法

設定を行うには `docker-compose.override.yml.example` を `docker-compose.override.yml` にコピーした後、ファイルに書いてあるコメントに従ってください。
`docker-compose.override.yml` を利用した設定の上書き方法に関する詳細は [ファイル間、プロジェクト間での Compose 設定の共有](https://docs.docker.jp/compose/extends.html) （[原文](https://docs.docker.com/compose/extends/#multiple-compose-files)）を参照してください。

**注意: 設定に利用している YAML ファイルはインデントでブロック範囲を表します。そのため、行頭スペースの数は `docker-compose.override.yml.example` の状態を守るように意識してください。**

### ログレベルの変更

Kroker のログレベルを変更するには、コピーした `docker-compose.override.yml` の `KROKER_LOG` を以下のように `debug` 、 `info` 、 `warn` 、もしくは `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"
```

### HTTP プロキシの利用

Kroker が Kompira に接続するために HTTP プロキシを経由する必要がある場合は、コピーした `docker-compose.override.yml` に以下のようにプロキシ設定を記述し、再接続してください。

```yaml
# Uncomment and fill followings to enable HTTP proxy.
KROKER_HTTP_PROXY_HOST: "proxy.example.com" # HTTP プロキシのホスト
KROKER_HTTP_PROXY_PORT: "8080" # HTTP プロキシのポート

# Uncomment and fill followings to enable HTTP proxy BASIC authentication.
KROKER_HTTP_PROXY_USERNAME: "username" # HTTP プロキシ BASIC 認証のユーザー名（必要な場合のみ）
KROKER_HTTP_PROXY_PASSWORD: "password" # HTTP プロキシ BASIC 認証のパスワード（必要な場合のみ）
```

### プレリリースの利用

何らかの事情によりプレリリースを利用する場合は、コピーした `docker-compose.override.yml` の `image` 指定部分のコメントを外して、再接続してください。
プレリリースは非安定版で動作保証対象外です。利用する場合は細心の注意を払ってください。

```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"
```

## 既存 Kroker のアップグレード

既に Kompira に登録済みの Kroker をアップグレードする場合は、展開した本パッケージの内容で上書きしてください。
すべてのファイルを本パッケージの内容で置き換えた後、以下のコマンドで Docker イメージを更新します。

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

最後に以下コマンドで Kroker を再起動してください。

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

なお「インストール」で行ったセットアップ手順 ( `kroker setup` ) は不要です。

## アンインストール

Kroker をアンインストールする場合は以下コマンドを実行してください。

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

その後 `./kroker` ディレクトリを削除してください。

## 動作環境

| 項目           | サポート                         | 推奨                |
| -------------- | -------------------------------- | ------------------- |
| OS             | Linux                            |                     |
| Arch           | x86-64, aarch64                  | x86-64              |
| Docker         | Version 20.10.5                  | 最新版              |
| Docker Compose | Version 1.28.5<br>Version 2.12.2 | 最新版              |
| CPU            | 2 GHz / 1 core                   | 3 GHz / 2 core 以上 |
| メモリ         | 2 GB                             | 4 GB 以上           |
| ネットワーク   | 100 Mbps                         | 1 Gbps 以上         |
| ストレージ     | 1 GB                             | 10 GB 以上          |

必要ストレージ容量については、利用量により大きく変わるため、10 GB 程度確保した上で一定期間の使用量を計測し、必要量を算出してください。
ストレージが枯渇した場合、Kroker は停止します。

## ライセンス

Kroker のライセンスは [フィックスポイント「Kompira」利用規約総覧](https://www.kompira.jp/Kompira_terms.pdf) を参照してください。

guacd のライセンスは [`LICENSE.guacd`](./LICENSE.guacd) に記載されています。
同梱されている guacd は動作に改変を加えたものです。変更点は [GitHub のリポジトリ](https://github.com/fixpoint/guacamole-server) を参照してください。
なお、guacd のバージョンは以下のコマンドで取得できます。

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

Kroker の依存ライブラリのライセンスは [`kroker-licenses.html`](./kroker-licenses.html) に記載されています。

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