# Table of contents - [Table of contents](#table-of-contents) - [System Prerequisites](#system-prerequisites) - [Docker Login](#docker-login) - [Potential Errors](#potential-errors) - [Repository `testing-environment`](#repository-testing-environment) - [Repository `k3k-controller`](#repository-k3k-controller) - [`config.toml`](#configtoml) - [Details in `config.toml`](#details-in-configtoml) - [Potential Errors for Config](#potential-errors-for-config) - [Diesel](#diesel) - [Potential Errors for Postgres](#potential-errors-for-postgres) - [Keycloak: Set up a Local Instance](#keycloak-set-up-a-local-instance) - [Run `cargo run` Command](#run-cargo-run-command) - [Notes for `cargo run` on OS X](#notes-for-cargo-run-on-os-x) - [Potential Errors for `cargo run`](#potential-errors-for-cargo-run) ## System Prerequisites The pre-requisites for starting the `k3k-controller` locally includes: - Install `Rust` - Run `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` - Or use your package manager - Install `docker` and `docker compose` (e.g. [on Ubuntu][docker_on_ubuntu]) - Run [post-installation steps for Docker][docker_post_install] - Install build essentials for your system via your package manager - Example: `sudo apt-get install build-essential` for Debian/Ubuntu) - Install `postgresql` and `libpq-dev` via your package manager - Note: For OS X, use `brew install libpq` to install `libpq` instead of `libpq-dev` ## Docker Login Make sure to generate an access token on [Gitlab][access-token-page] and login to our Docker repository with your username and the key. You should only need to select `read_registry` and `write_registry` for the scope of your access token. Login via Docker by: ```sh $ docker login git.opentalk.dev:5050 -u [token name] -p [token key] # Example: # docker login git.opoentalk.dev:5050 -u n.kang -p MYACCESSTOKEN ``` ### Potential Errors <details> <summary>Error: permission denied</summary> If you run into `permission denied` issue: ``` $ sudo groupadd docker $ sudo usermod -aG docker $USER $ sudo chmod 666 /var/run/docker.sock ``` </details> ## Repository `testing-environment` Run the following command would spin up all the dependent services: ``` $ docker-compose up -d # Or use the following to see full logs as docker composes: $ docker-compose up ``` This assumes that you are using a staging `Keycloak` instance. If you need to use a local `Keycloak` instance, see [Keycloack: Local Instance](#Keycloak-Local-Instance) for more information. ## Repository `k3k-controller` Generally speaking, after starting all the required services in [`testing-environment`](#Repository-testing-environment) with `docker-compose`, running the following command in the root project directory for `k3k-controller` would spin up the controller: ``` $ cargo run ``` However, for first-time users, there are additional steps to perform before you can run the controller. ### `config.toml` First, `k3k-controller` repository comes with an `extra/example.toml` file. Inside the `k3k-controller` directory, run: ``` $ cp extra/example.toml ./config.toml ``` Some important term clarifications: - `keycloak`: Open source tool for OIDC authentication (think `OneLogin`, etc.) - `minio`: Open source object storage (think `S3`) Below is a fully-working example of `config.toml` without comments and with the most common fields filled for first-time users to get the server running. This example ignores many other fields such as `[logging]`. For a complete example, refer to `extra/example.toml` in [the repository][example-config-toml]. ```toml [database] # URL used to connect to a postgres. url = "postgres://postgres:password123@localhost:5432/k3k" [http] # The port to bind the HTTP Server to (defaults to 11311). port = 8000 # URLs that requests are allowed from. Leave empty to allow all. cors.allowed_origin = ["http://localhost:8080", "http://localhost:8111", "http://localhost:3000", "https://p01nc.heinlein-video.de"] [keycloak] # URL to the keycloak base_url = "https://p01nc.heinlein-video.de:8443/auth" # Name of the keycloak realm realm = "K3K" # Client ID client_id = "Controller" # Client secret (application requires confidential client). client_secret = "ASK-A-COLLEAGUE-FOR-THIS" [room_server] # Maximum bitrate allowed for media sessions that will be used to transmit webcam video/audio # Example: 1.5 Mbit/s max_video_bitrate = "1500000" # Maximum bitrate allowed for media sessions used for screen share # Example: 1MB/s max_screen_bitrate = "8000000" [[room_server.connections]] to_routing_key = "to-janus" exchange = "janus-exchange" from_routing_key = "from-janus" # MinIO configuration [minio] # The URI to the MinIO instance uri = "http://localhost:9555" # Name of the bucket # The bucket has to be created manually before starting the controller bucket = "controller" # Access key for the MinIO bucket access_key = "minioadmin" # Secret key for the MinIO bucket secret_key = "minioadmin" ``` #### Details in `config.toml` There are a few details to pay attention to. <details> <summary>CORS specification</summary> Specify an HTTP port for the controller and update the CORS list: ```toml [http] port = 8000 cors.allowed_origin = ["http://localhost:8080", "http://localhost:8111", "http://localhost:3000", "https://p01nc.heinlein-video.de"] ``` </details> <details> <summary>MinIO Specification</summary> The `minio` section should look like: ```toml # fix config.toml minio section (which is a copy of extra/example.toml) bucket = "controller" # Access key for the MinIO bucket access_key = "minioadmin" # Secret key for the MinIO bucket secret_key = "minioadmin" ``` </details> <details> <summary>Keycloak Specification</summary> The `keycloak` section has the following `base_url` key-value pair, which points to the correct staging `Keycloak` instance: ```yaml [keycloak] # URL to the keycloak base_url = "https://p01nc.heinlein-video.de:8443/auth" ``` You can also set up `keycloak` locally. See [below](#Keycloak-Local-Instance). </details> #### Potential Errors for Config <details> <summary>Cannot find configured MinIO bucket</summary> If incorrect information is filled in `minio` section, you will encounter `Cannot find configured MinIO bucket` error. The `minio` section should look like: ```toml # fix config.toml minio section (which is a copy of extra/example.toml) bucket = "controller" # Access key for the MinIO bucket access_key = "minioadmin" # Secret key for the MinIO bucket secret_key = "minioadmin" ``` </details> <details> <summary>Failed to initialize OIDC Context</summary> If incorrect information is filled in `keycloak` section, you will encounter `Failed to initialize OIDC Context` error. Make sure that the `keycloak` section has the following `base_url` key-value pair, which points to the correct staging `Keycloak` instance: ```toml [keycloak] # URL to the keycloak base_url = "https://p01nc.heinlein-video.de:8443/auth" ``` </details> ### Diesel Before we can start the server, we must install `diesel_cli`. Follow the steps listed in [`DB_MIGRATIONS.md`][DB_MIGRATIONS.md]. Specifically, run the following command (which can be found in the notes of the `DB_MIGRATIONS.md` file): ```sh # Install rustfmt first $ rustup component add rustfmt # Install diesel $ cargo install diesel_cli --version 1.4.1 --no-default-features --features="barrel-migrations,barrel/pg,postgres" ``` #### Potential Errors for Postgres <details> <summary>lpq linker with cc failed error</summary> If you encounter an error with `lpq linker with cc failed error`, fix it by installing `libpq-dev` client for Postgres on your corresponding operating system. For instance, the following steps are for Debian/Ubuntu: ```sh # Linux sudo apt-get install libpq-dev # OS X brew install libpq ``` </details> ### Keycloak: Set up a Local Instance Sometimes we might want to spin up keycloak locally. To do so, go into the `testing-environment` directory and remove the `depends_on: postgres` field in the OIDC compose file `docker-compose.oidc.yaml` might help spin up `Keycloak` locally since the `postgres` service is most likely spinned up already in [repository: `testing-environment`](#Repository-testing-environment) already: ```sh $ docker-compose -f docker-compose.oidc.yaml up -d ``` On the Keycloak web UI (`user: admin`, `password: admin`), choose the `K3K` realm instead of the `Master` realm. Then inside the `clients`, choose `controller` and copy the client secret. Copy the controller client secret from the local `Keycloak` instance and paste into `config.toml` (might need to change realm name in config too). ```yaml [keycloak] # URL to the keycloak base_url = "http://localhost:8080/auth" # Name of the keycloak realm realm = "K3K" # Client ID client_id = "Controller" # Client secret (application requires confidential client). client_secret = "SOME_SECRET_YOU_COPIED_FROM_KEYCLOAK_WEB_UI" ``` Note that Keycloak is a separate service from the `controller`, so the base URL should use a different port like `8080` instead of the `controller`'s port (`8000` in this case). ### Run `cargo run` Command Now, run `cargo run` again should work and start the controller: ```sh $ cargo run Finished dev [unoptimized + debuginfo] target(s) in 0.34s Running `target/debug/k3k-controller` 2022-11-18T12:11:56.615683Z INFO k3k_controller_core: Starting K3K Controller 2022-11-18T12:11:56.858477Z INFO init: k3k_controller_core::storage: Using MinIO S3 bucket: controller 2022-11-18T12:11:57.062099Z WARN k3k_protocol: Skipping the Protocol module as no etherpad is specified in the config 2022-11-18T12:11:57.062252Z WARN k3k_whiteboard: Skipping the Whiteboard module as no spacedeck is specified in the config 2022-11-18T12:11:57.116181Z INFO k3k_controller_core: Making sure the default permissions are set 2022-11-18T12:11:57.159478Z INFO k3k_controller_core: Startup finished ``` #### Notes for `cargo run` on OS X In case you are using the new M1 chip with OS X, ensure that the following is added to `k3k-controller/.cargo/config` ([solution found here](https://github.com/rust-lang/rust/issues/86658#issuecomment-983925155)): ``` [target.aarch64-apple-darwin] rustflags = [ "-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup", ] ``` Once you run have other necessary steps set up, running `cargo run` should spin up the BE server. #### Potential Errors for `cargo run` <details> <summary>Failed to create session: Timeout</summary> Sometimes, `janus` might crash with a `timeout`: ```sh # k3k-controller/ $ cargo run Finished dev [unoptimized + debuginfo] target(s) in 0.33s Running `target/debug/k3k-controller` 2022-11-18T12:10:40.847331Z INFO k3k_controller_core: Starting K3K Controller 2022-11-18T12:10:41.084515Z INFO init: k3k_controller_core::storage: Using MinIO S3 bucket: controller 2022-11-18T12:11:11.345361Z ERROR k3k_controller_core: Crashed with error: Failed to create mcu client Caused by: Failed to create session, Timeout ``` This is because `Janus` might have a racing condition problem with `Keycloak`. This can be easily fixed by simply restarting the `janus` service inside `testing-environment` directory: ```sh $ docker-compose restart janus ``` </details> [access-token-page]: https://git.opentalk.dev/-/profile/personal_access_tokens [DB_MIGRATIONS.md]: https://git.opentalk.dev/opentalk/k3k-controller/-/blob/main/DB_MIGRATIONS.md [docker_on_ubuntu]: https://docs.docker.com/engine/install/ubuntu/ [docker_post_install]: https://docs.docker.com/engine/install/linux-postinstall/ [example-config-toml]: https://git.opentalk.dev/opentalk/k3k-controller/-/blob/main/extra/example.toml