diff --git a/client/core/rs/src/api/read/deployment.rs b/client/core/rs/src/api/read/deployment.rs index b1ca396fb..89f355618 100644 --- a/client/core/rs/src/api/read/deployment.rs +++ b/client/core/rs/src/api/read/deployment.rs @@ -72,7 +72,7 @@ pub struct GetDeploymentContainer { pub deployment: String, } -/// Response for [GetDeploymentStatus]. +/// Response for [GetDeploymentContainer]. #[typeshare] #[derive(Serialize, Deserialize, Debug, Clone)] pub struct GetDeploymentContainerResponse { diff --git a/client/core/rs/src/api/read/repo.rs b/client/core/rs/src/api/read/repo.rs index d2db14c1b..3ec54541f 100644 --- a/client/core/rs/src/api/read/repo.rs +++ b/client/core/rs/src/api/read/repo.rs @@ -65,8 +65,8 @@ pub type GetRepoActionStateResponse = RepoActionState; // -/// Gets a summary of data relating to all builds. -/// Response: [GetBuildsSummaryResponse]. +/// Gets a summary of data relating to all repos. +/// Response: [GetReposSummaryResponse]. #[typeshare] #[derive( Serialize, Deserialize, Debug, Clone, Request, EmptyTraits, diff --git a/client/core/rs/src/entities/config/core.rs b/client/core/rs/src/entities/config/core.rs index 4324e061a..aa0a36457 100644 --- a/client/core/rs/src/entities/config/core.rs +++ b/client/core/rs/src/entities/config/core.rs @@ -1,3 +1,14 @@ +//! # Configuring the Core API +//! +//! Monitor core is configured by parsing base configuration file ([CoreConfig]), and overriding +//! any fields given in the file with ones provided on the environment ([Env]). +//! +//! The recommended method for running monitor core is via the docker image. This image has a default +//! configuration file provided in the image, meaning any custom configuration can be provided +//! on the environment alone. However, if a custom configuration file is prefered, it can be mounted +//! into the image at `/config/config.toml`. +//! + use serde::{Deserialize, Serialize}; use crate::entities::{ @@ -12,7 +23,7 @@ use crate::entities::{ /// although the lower case format can still be parsed. /// /// *Note.* The monitor core docker image includes the default core configuration found in -/// the `mbecker20/monitor/config_example` folder of the repo. To configigure the core api, +/// the `mbecker20/monitor/config_example` folder of the repo. To configure the core api, /// you can either mount your own custom configuration file to `/config/config.toml` inside the container, /// or simply override whichever fields you need using the environment. #[derive(Debug, Clone, Serialize, Deserialize)] @@ -100,12 +111,113 @@ fn default_config_path() -> String { /// parsing the [CoreConfig] schema from the file path specified by `env.monitor_config_path`, /// and then applying any config field overrides specified in the environment. /// -/// *Note.* The monitor core docker image includes the default core configuration found in -/// the `mbecker20/monitor/config_example` folder of the repo. To configigure the core api, -/// you can either mount your own custom configuration file to `/config/config.toml` inside the container, -/// or simply override whichever fields you need using the environment. +/// *Note.* The monitor core docker image includes the default core configuration found below. +/// To configure the core api, you can either mount your own custom configuration file +/// to `/config/config.toml` inside the container, or simply override whichever fields +/// you need using the environment. +/// +/// ## Example TOML +/// ```toml +/// ## this will be the document title on the web page (shows up as text in the browser tab). +/// ## default: 'Monitor' +/// title = "Monitor" +/// +/// ## required for oauth functionality. this should be the url used to access monitor in browser, +/// ## potentially behind DNS. +/// ## eg https://monitor.dev or http://12.34.56.78:9000. +/// ## this should match the address configured in your oauth app. +/// ## no default +/// host = "https://monitor.dev" +/// +/// ## the port the core system will run on. if running core in docker container, +/// ## leave as this port as 9000 and use port bind eg. -p 9001:9000 +/// ## default: 9000 +/// port = 9000 +/// +/// ## required to match a passkey in periphery config. +/// ## token used to authenticate core requests to periphery +/// ## no default +/// passkey = "a_random_passkey" +/// +/// ## specify the log level of the monitor core application +/// ## default: info +/// ## options: off, error, warn, info, debug, trace +/// logging.level = "info" +/// +/// ## specify the logging format for stdout / stderr. +/// ## default: standard +/// ## options: standard, json, none +/// logging.stdio = "standard" +/// +/// ## specify a opentelemetry otlp endpoint to send traces to +/// ## optional, default unassigned +/// # logging.otlp_endpoint = "http://localhost:4317" +/// +/// ## specify how long an issued jwt stays valid. +/// ## all jwts are invalidated on application restart. +/// ## default: 1-day. +/// ## options: 1-hr, 12-hr, 1-day, 3-day, 1-wk, 2-wk, 30-day +/// jwt_valid_for = "1-day" +/// +/// ## controls the granularity of the system stats collection by monitor core +/// ## default: 15-sec +/// ## options: 5-sec, 15-sec, 30-sec, 1-min, 2-min, 5-min, 15-min +/// monitoring_interval = "15-sec" +/// +/// ## number of days to keep stats around, or 0 to disable pruning. +/// ## stats older than this number of days are deleted daily +/// ## default: 0 (pruning disabled) +/// keep_stats_for_days = 0 +/// +/// ## token that has to be given to github during repo webhook config as the secret +/// ## default: empty (none) +/// github_webhook_secret = "your_random_webhook_secret" +/// +/// ## an alternate base url that is used to recieve github webhook requests +/// ## if empty or not specified, will use 'host' address as base +/// ## default: empty (none) +/// # github_webhook_base_url = "https://github-webhook.monitor.dev" +/// +/// ## these will be used by the GUI to attach to builds. +/// ## when attached to build, image will be pushed to repo under the specified organization. +/// ## if empty, the "docker organization" config option will not be shown. +/// ## default: empty +/// # docker_organizations = ["your_docker_org1", "your_docker_org_2"] +/// +/// ## allow or deny user login with username / password +/// ## default: false +/// # local_auth = true +/// +/// ## Use to configure github oauth +/// # github_oauth.enabled = true +/// # github_oauth.id = "your_github_client_id" +/// # github_oauth.secret = "your_github_client_secret" +/// +/// ## Use to configure google oauth +/// # google_oauth.enabled = true +/// # google_oauth.id = "your_google_client_id" +/// # google_oauth.secret = "your_google_client_secret" +/// +/// ## MUST comment back in some way to configure mongo. +/// # mongo.uri = "mongodb://username:password@localhost:27017" +/// ## ==== or ==== +/// mongo.address = "localhost:27017" +/// # mongo.username = "username" +/// # mongo.password = "password" +/// ## ==== other ==== +/// ## default: monitor. this is the name of the mongo database that monitor will create its collections in. +/// mongo.db_name = "monitor" +/// ## default: monitor_core. this is the assigned app_name of the mongo client +/// mongo.app_name = "monitor_core" +/// +/// ## provide aws api keys for ephemeral builders +/// # aws.access_key_id = "your_aws_key_id" +/// # aws.secret_access_key = "your_aws_secret_key" +/// ``` #[derive(Debug, Clone, Serialize, Deserialize)] pub struct CoreConfig { + /// The title of this monitor deployment. Will be used in the browser page title. + /// Default: 'Monitor' #[serde(default = "default_title")] pub title: String, @@ -248,24 +360,39 @@ fn empty_or_redacted(src: &str) -> String { } } +/// Generic Oauth credentials #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub struct OauthCredentials { + /// Whether this oauth method is available for usage. #[serde(default)] pub enabled: bool, + /// The Oauth client id. #[serde(default)] pub id: String, + /// The Oauth client secret. #[serde(default)] pub secret: String, } +/// Provide mongo connection information. +/// Must provide ONE of: +/// 1. `uri` +/// 2. `address` + `username` + `password` #[derive(Debug, Clone, Serialize, Deserialize)] pub struct MongoConfig { + /// Full mongo uri string, eg. `mongodb://username:password@your.mongo.int:27017` pub uri: Option, + /// Just the address part of the uri, eg `your.mongo.int:27017` pub address: Option, + /// Mongo user username pub username: Option, + /// Mongo user password pub password: Option, + /// Mongo app name. default: `monitor_core` #[serde(default = "default_core_mongo_app_name")] pub app_name: String, + /// Mongo db name. Which mongo database to create the collections in. + /// Default: `monitor`. #[serde(default = "default_core_mongo_db_name")] pub db_name: String, } @@ -291,8 +418,11 @@ impl Default for MongoConfig { } } +/// Provide AWS credentials for monitor to use. #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub struct AwsCredentials { + /// The aws ACCESS_KEY_ID pub access_key_id: String, + /// The aws SECRET_ACCESS_KEY pub secret_access_key: String, } diff --git a/client/core/rs/src/entities/config/periphery.rs b/client/core/rs/src/entities/config/periphery.rs index 259f76c84..8f80652e6 100644 --- a/client/core/rs/src/entities/config/periphery.rs +++ b/client/core/rs/src/entities/config/periphery.rs @@ -125,6 +125,58 @@ fn default_config_paths() -> Vec { /// The periphery agent initializes it's configuration by reading the environment, /// parsing the [PeripheryConfig] schema from the files specified by cli args (and falling back to `env.config_paths`), /// and then applying any config field overrides specified in the environment. +/// +/// ## Example TOML +/// ```toml +/// ## optional. 8120 is default +/// port = 8120 +/// +/// ## optional. /repos is default. +/// repo_dir = "/repos" +/// +/// ## optional. 5-sec is default. +/// ## can use 1-sec, 5-sec, 10-sec, 30-sec, 1-min. +/// ## controls granularity of system stats recorded +/// stats_polling_rate = "5-sec" +/// +/// ## optional. default is empty, which will not block any request by ip. +/// allowed_ips = ["127.0.0.1"] +/// +/// ## optional. default is empty, which will not require any passkey to be passed by core. +/// passkeys = ["abcdefghijk"] +/// +/// ## specify the log level of the monitor core application +/// ## default: info +/// ## options: off, error, warn, info, debug, trace +/// logging.level = "info" +/// +/// ## specify the logging format for stdout / stderr. +/// ## default: standard +/// ## options: standard, json, none +/// logging.stdio = "standard" +/// +/// ## specify an otlp endpoint to send traces to +/// ## optional, default unassigned +/// # logging.otlp_endpoint = "http://localhost:4317" +/// +/// ## specify the service name to send with otlp traces. +/// ## optional, default 'Monitor'. +/// # logging.opentelemetry_service_name = "Monitor" +/// +/// ## optional. can inject these values into your deployments configuration. +/// [secrets] +/// secret_variable = "secret_value" +/// +/// ## optional. can use these accounts with deployments / builds. +/// [github_accounts] +/// github_username1 = "github_token1" +/// github_username2 = "github_token2" +/// +/// ## optional. can use these accounts with deployments / builds. +/// [docker_accounts] +/// docker_username1 = "docker_token1" +/// docker_username2 = "docker_token2" +/// ``` #[derive(Deserialize, Debug, Clone)] pub struct PeripheryConfig { /// The port periphery will run on.