diff --git a/meilisearch-http/src/option.rs b/meilisearch-http/src/option.rs index ae12f0cc6..8a0ea0f44 100644 --- a/meilisearch-http/src/option.rs +++ b/meilisearch-http/src/option.rs @@ -66,7 +66,7 @@ const DEFAULT_LOG_LEVEL: &str = "INFO"; #[clap(version)] #[serde(rename_all = "snake_case", deny_unknown_fields)] pub struct Opt { - /// The destination where the database must be created. + /// Designates the location where database files will be created and retrieved. #[clap(long, env = MEILI_DB_PATH, default_value_os_t = default_db_path())] #[serde(default = "default_db_path")] pub db_path: PathBuf, @@ -81,51 +81,76 @@ pub struct Opt { #[clap(long, env = MEILI_MASTER_KEY)] pub master_key: Option, - /// This environment variable must be set to `production` if you are running in production. - /// More logs wiil be displayed if the server is running in development mode. Setting the master - /// key is optional; hence no security on the updates routes. This - /// is useful to debug when integrating the engine with another service + /// Configures the instance's environment. Value must be either production or development. + /// `production` + /// * Setting a master key is mandatory + /// * The search preview interface is disabled + /// + /// `development`: + /// Setting a master key is optional + /// Search preview is enabled + /// + /// # TIP + /// + /// When the server environment is set to development, providing a master key is not mandatory. + /// This is useful when debugging and prototyping, but dangerous otherwise since API routes + /// are unprotected. #[clap(long, env = MEILI_ENV, default_value_t = default_env(), possible_values = &POSSIBLE_ENV)] #[serde(default = "default_env")] pub env: String, - /// Do not send analytics to Meili. + /// Deactivates Meilisearch's built-in telemetry when provided. + /// + /// Meilisearch automatically collects data from all instances that do not opt out using this flag. + /// All gathered data is used solely for the purpose of improving Meilisearch, and can be deleted + /// at any time. #[cfg(all(not(debug_assertions), feature = "analytics"))] #[serde(skip_serializing, default)] // we can't send true #[clap(long, env = MEILI_NO_ANALYTICS)] pub no_analytics: bool, - /// The maximum size, in bytes, of the main LMDB database directory + /// Sets the maximum size of the index. Value must be given in bytes or explicitly stating a base unit. + /// + /// For example, the default value can be written as `107374182400`, `'107.7Gb'`, or `'107374 Mb'`. + /// + /// The index stores processed data and is different from the task database, which handles pending tasks. #[clap(long, env = MEILI_MAX_INDEX_SIZE, default_value_t = default_max_index_size())] #[serde(default = "default_max_index_size")] pub max_index_size: Byte, - /// The maximum size, in bytes, of the update LMDB database directory + /// Sets the maximum size of the task database. Value must be given in bytes or explicitly stating a + /// base unit. For example, the default value can be written as `107374182400`, `'107.7Gb'`, or + /// `'107374 Mb'`. + /// + /// The task database handles pending tasks. This is different from the index database, which only + /// stores processed data. #[clap(long, env = MEILI_MAX_TASK_DB_SIZE, default_value_t = default_max_task_db_size())] #[serde(default = "default_max_task_db_size")] pub max_task_db_size: Byte, - /// The maximum size, in bytes, of accepted JSON payloads + /// Sets the maximum size of accepted payloads. Value must be given in bytes or explicitly stating a + /// base unit. For example, the default value can be written as `107374182400`, `'107.7Gb'`, or + /// `'107374 Mb'`. #[clap(long, env = MEILI_HTTP_PAYLOAD_SIZE_LIMIT, default_value_t = default_http_payload_size_limit())] #[serde(default = "default_http_payload_size_limit")] pub http_payload_size_limit: Byte, - /// Read server certificates from CERTFILE. - /// This should contain PEM-format certificates - /// in the right order (the first certificate should - /// certify KEYFILE, the last should be a root CA). + /// Sets the server's SSL certificates. + /// + /// Value must be a path to PEM-formatted certificates. The first certificate should certify the + /// KEYFILE supplied by --ssl-key-path. The last certificate should be a root CA. #[serde(skip_serializing)] #[clap(long, env = MEILI_SSL_CERT_PATH, parse(from_os_str))] pub ssl_cert_path: Option, - /// Read the private key from KEYFILE. This should be an RSA - /// private key or PKCS8-encoded private key, in PEM format. + /// Sets the server's SSL key files. + /// + /// Value must be a path to an RSA private key or PKCS8-encoded private key, both in PEM format. #[serde(skip_serializing)] #[clap(long, env = MEILI_SSL_KEY_PATH, parse(from_os_str))] pub ssl_key_path: Option, - /// Enable client authentication, and accept certificates - /// signed by those roots provided in CERTFILE. + /// Enables client authentication in the specified path. #[serde(skip_serializing)] #[clap(long, env = MEILI_SSL_AUTH_PATH, parse(from_os_str))] pub ssl_auth_path: Option, @@ -136,28 +161,42 @@ pub struct Opt { #[clap(long, env = MEILI_SSL_OCSP_PATH, parse(from_os_str))] pub ssl_ocsp_path: Option, - /// Send a fatal alert if the client does not complete client authentication. + /// Makes SSL authentication mandatory. + /// + /// Sends a fatal alert if the client does not complete client authentication. #[serde(skip_serializing, default)] #[clap(long, env = MEILI_SSL_REQUIRE_AUTH)] pub ssl_require_auth: bool, - /// SSL support session resumption + /// Activates SSL session resumption. #[serde(skip_serializing, default)] #[clap(long, env = MEILI_SSL_RESUMPTION)] pub ssl_resumption: bool, - /// SSL support tickets. + /// Activates SSL tickets. #[serde(skip_serializing, default)] #[clap(long, env = MEILI_SSL_TICKETS)] pub ssl_tickets: bool, - /// Defines the path of the snapshot file to import. - /// This option will, by default, stop the process if a database already exists, or if no snapshot exists at - /// the given path. If this option is not specified, no snapshot is imported. + /// Launches Meilisearch after importing a previously-generated snapshot at the given filepath. + /// + /// This command will throw an error if: + /// * A database already exists + /// * No valid snapshot can be found in the specified path + /// + /// This behavior can be modified with the `--ignore-snapshot-if-db-exists` and + /// `--ignore-missing-snapshot` options, respectively. + /// + /// *This option is not available as an environment variable.* #[clap(long, env = MEILI_IMPORT_SNAPSHOT)] pub import_snapshot: Option, - /// The engine will ignore a missing snapshot and not return an error in such a case. + /// Prevents a Meilisearch instance from throwing an error when `--import-snapshot` + /// does not point to a valid snapshot file. + /// + /// This command will throw an error if `--import-snapshot` is not defined. + /// + /// *This option is not available as an environment variable.* #[clap( long, env = MEILI_IGNORE_MISSING_SNAPSHOT, @@ -166,7 +205,13 @@ pub struct Opt { #[serde(default)] pub ignore_missing_snapshot: bool, - /// The engine will skip snapshot importation and not return an error in such case. + /// Prevents a Meilisearch instance with an existing database from throwing an + /// error when using `--import-snapshot`. Instead, the snapshot will be ignored + /// and Meilisearch will launch using the existing database. + /// + /// This command will throw an error if `--import-snapshot` is not defined. + /// + /// *This option is not available as an environment variable.* #[clap( long, env = MEILI_IGNORE_SNAPSHOT_IF_DB_EXISTS, @@ -175,20 +220,19 @@ pub struct Opt { #[serde(default)] pub ignore_snapshot_if_db_exists: bool, - /// Defines the directory path where Meilisearch will create a snapshot each snapshot-interval-sec. + /// Sets the directory where Meilisearch will store snapshots. #[clap(long, env = MEILI_SNAPSHOT_DIR, default_value_os_t = default_snapshot_dir())] #[serde(default = "default_snapshot_dir")] pub snapshot_dir: PathBuf, - /// Activate snapshot scheduling. + /// Activates scheduled snapshots when provided. Snapshots are disabled by default. #[clap(long, env = MEILI_SCHEDULE_SNAPSHOT)] #[serde(default)] pub schedule_snapshot: bool, - /// Defines time interval, in seconds, between each snapshot creation. + /// Defines the interval between each snapshot. Value must be given in seconds. #[clap(long, env = MEILI_SNAPSHOT_INTERVAL_SEC, default_value_t = default_snapshot_interval_sec())] #[serde(default = "default_snapshot_interval_sec")] - // 24h pub snapshot_interval_sec: u64, /// Import a dump from the specified path, must be a `.dump` file.