From b955ceb5858c46403016b9ee8e05a3e99f7b1d72 Mon Sep 17 00:00:00 2001 From: David Legrand <1110600+davlgd@users.noreply.github.com> Date: Fri, 19 Jan 2024 20:12:46 +0100 Subject: [PATCH] docs: introduce new Clever Tools documentation --- bin/clever.js | 2 +- docs/README.md | 90 ++++++++++++ docs/addons-backups.md | 74 ++++++++++ docs/applications-config.md | 128 ++++++++++++++++++ docs/applications-deployment-lifecycle.md | 118 ++++++++++++++++ docs/applications-management.md | 106 +++++++++++++++ docs/nexus-config.md | 47 +++---- docs/services-depedencies.md | 51 +++++++ ...{log-drains.md => services-logs-drains.md} | 32 ++--- docs/services-notifications-webhooks.md | 64 +++++++++ docs/setup-systems.md | 77 ++++++----- 11 files changed, 698 insertions(+), 91 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/addons-backups.md create mode 100644 docs/applications-config.md create mode 100644 docs/applications-deployment-lifecycle.md create mode 100644 docs/applications-management.md create mode 100644 docs/services-depedencies.md rename docs/{log-drains.md => services-logs-drains.md} (80%) create mode 100644 docs/services-notifications-webhooks.md diff --git a/bin/clever.js b/bin/clever.js index 9022617f..2b5c18a5 100755 --- a/bin/clever.js +++ b/bin/clever.js @@ -348,7 +348,7 @@ function run () { parser: Parsers.commaSeparated, }), showAllActivity: cliparse.flag('show-all', { description: 'Show all activity' }), - showAll: cliparse.flag('show-all', { description: 'Show all available dependencies' }), + showAll: cliparse.flag('show-all', { description: 'Show all available add-ons and applications' }), loginToken: cliparse.option('token', { metavar: 'token', description: 'Directly give an existing token', diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..eb2650ce --- /dev/null +++ b/docs/README.md @@ -0,0 +1,90 @@ +# How to use Clever Tools + +Clever Tools is the command line interface (CLI) of Clever Cloud. You can use it to create and manage multiple services of the platform as applications, databases or storage add-ons. It also provides an easy authenticated access to Clever Cloud public APIv2 and APIv4 through the [`clever curl` command](#curl). + +It's an [easy to setup](/docs/setup-systems.md) multiplatform and open source tool, based on Node.js. You can contribute to it through +[issue](https://github.com/CleverCloud/clever-tools/issues) or [pull requests](https://github.com/CleverCloud/clever-tools/pulls). You're free +to ask for new features, enhancements or help us to provide them to our community. + +- [How to install Clever Tools](/docs/setup-systems.md) +- [Create a Clever Cloud account](https://console.clever-cloud.com) + +You'll find below the first commands to know to connect Clever Tools to your account, get its informations and manage some options. Others are developed in dedicated pages: + +- [Applications: configuration](/docs/applications-config.md) +- [Applications: management](/docs/applications-management.md) +- [Applications: deployment and lifecycle](/docs/applications-deployment-lifecycle.md) +- [Add-ons: management and backups](/docs/addons-backups.md) +- [Services: depedencies](/docs/services-depedencies.md) +- [Services: logs drains](/docs/services-logs-drains.md) +- [Services: notifications and webhooks](/docs/services-notifications-webhooks.md) + +## basic commands + +To show Clever tools available commands, use: + +``` +clever +clever help +``` + +For each of them, you can add these parameters: + +``` +[--help, -?] Display help about this program (default: false) +[--version, -V] Display the version of this program (default: false) +[--verbose, -v] Verbose output (default: false) +[--no-update-notifier] Don't notify available updates for clever-tools (default: false) +``` + +## diag | version + +To check the current version or get informations about your setup, use: + +``` +clever version +clever diag +``` + +> [!NOTE] +> Such informations are nice to provide in your issues report or when you contact Clever Cloud technical support team. + +## login | logout + +To connect to your Clever Cloud account, use: + +``` +clever login +``` + +It will open your default browser and start an Open Authorization ([OAuth](https://en.wikipedia.org/wiki/OAuth)) process get a `token` and `secret` pair added in your account if it succeeds. You can manage it from the [Console](https://console.clever-cloud.com/users/me/tokens). Clever Tools will automatically store these `token` and `secret` values in a hidden `clever-tools.json` config file in the current local user home folder. + +If you already know them, you can use: + +``` +clever login --secret SECRET --token TOKEN +``` + +> [!TIP] +> If environment variables `CC_SECRET` and `CC_TOKEN` are set, Clever Tools will use them, `login` is not needed. + +To logout, delete this file or use: + +``` +clever logout +``` + +## profile + +To get informations about the current logged in user (ID, name, email, 2FA activation), use: + +``` +clever profile +``` + +## curl + +To use our public API, you need to be authentified on many endpoints. If you're logged in through Clever Tools, there is a simple way to make any request you want: `clever curl`. It's `curl`, you an use exactly the same way as the famous tool, but in an authenticated context for Clever Cloud API. + +- [Clever Cloud public APIv2 documentation](https://developers.clever-cloud.com/api/v2/) +- [Clever Cloud public APIv4 documentation](https://developers.clever-cloud.com/api/v4/) diff --git a/docs/addons-backups.md b/docs/addons-backups.md new file mode 100644 index 00000000..b2bb1ab0 --- /dev/null +++ b/docs/addons-backups.md @@ -0,0 +1,74 @@ +# Clever Cloud Add-ons: management and backups + +Add-ons on Clever Cloud are databases, storage services, tools or third party services you can enable through ` clever addon provider`. For each of the folowing commands, you can target a specific user/organisation: + +``` +[--org, -o, --owner] Organisation ID (or name, if unambiguous) +``` + +## providers + +To use add-ons, you need to identify the corresponding provider. To get informations about them (plans, regions, versions), use: + +``` +clever addon providers +clever addon providers show PROVIDER_NAME +``` + +## create | rename | delete + +To create an add-on, select a provider and choose a name: + +``` +clever addon create PROVIDER ADDON_NAME +``` + +You can set `plan`, `region`, `version`, `option` and directly `link` an add-on to an application through these parameters: + +``` +[--link, -l] ALIAS Link the created add-on to the app with the specified alias +[--yes, -y] Skip confirmation even if the add-on is not free (default: false) +[--plan, -p] PLAN Add-on plan, depends on the provider (default: dev) +[--region, -r] REGION Region to provision the add-on in, depends on the provider (default: par) +[--addon-version] ADDON-VERSION The version to use for the add-on +[--option] OPTION Option to enable for the add-on. Multiple --option argument can be passed to enable multiple options +``` + +To rename an add-on, use: + +``` +clever addon rename ADDON_ID_OR_NAME ADDON_NEW_NAME +``` + +To delete an add-on, use: + +``` +clever addon delete [--yes, -y] ADDON_ID_OR_NAME +``` + +## env + +Each add-on comes with environement variables. To get them, use: + +``` +clever addon env [--format, -F] FORMAT ADDON_ID +``` + +> [!NOTE] +> Available formats are: `human` (default), `json` and `shell` + +## database backups + +Databases are backup every day, with last 7 days of backups available to download. To get these files, use: + +``` +clever database backups download [--output, --out] OUTPUT_FILE DATABASE_ID BACKUP_ID +``` + +This command is still under development and will evolve over time. To get informations about backups and download them, you can use our API and `clever curl`. For example: + +``` +clever curl -X GET https://api.clever-cloud.com/v2/backups// +``` + +This will list available backups for the database, with creation and delete time. The anwser will also contains a direct HTTPS `download_url`. diff --git a/docs/applications-config.md b/docs/applications-config.md new file mode 100644 index 00000000..fbc13a6f --- /dev/null +++ b/docs/applications-config.md @@ -0,0 +1,128 @@ +# Clever Cloud Applications: configuration + +A Clever Cloud application can easily be configured once created, through following commands. Each can target a specfic application in the current folder, adding `[--alias, -a] ALIAS`. + +## config + +Each application have options you can get/set: `name`, `description`, `zero-downtime`, `sticky-sessions`, `cancel-on-push`, `force-https`. + +``` +clever config get parameter +clever config set parameter value +``` + +To update multiple configuration parameters at a time, use: + +``` +clever config update FLAGS +``` + +Available parameters are : + +``` +[--name] Set name +[--description] Set description +[--enable-zero-downtime] Enable zero-downtime (default: false) +[--disable-zero-downtime] Disable zero-downtime (default: false) +[--enable-sticky-sessions] Enable sticky-sessions (default: false) +[--disable-sticky-sessions] Disable sticky-sessions (default: false) +[--enable-cancel-on-push] Enable cancel-on-push (default: false) +[--disable-cancel-on-push] Disable cancel-on-push (default: false) +[--enable-force-https] Enable force-https (default: false) +[--disable-force-https] Disable force-https (default: false) +``` + +## env + +Environment variables of Clever Cloud applications can easily be modified: + +``` +clever env set VARIABLE VALUE +clever env rm VARIABLE +``` + +You can import local environment variables (comma separated) or from a file through `stdin`. If it's a JSON file, each object should be composed of a `name` and a `value`. + +``` +clever env import-vars VAR_NAME1,VAR_NAME2 +clever env import < .env +cat .env.json | clever env import --json +``` + +To show or export environment variables of an application, use: + +``` +clever env +clever env > .env +``` + +You can also export environment variable in a sourceable format (`export ENV_NAME="VALUE";`): + +``` +clever env --add-export +``` + +## domain + +By default, a Clever Cloud application gets an `app_id.cleverapps.io`. To see it, use: + +``` +clever domain +``` + +To add/remove domains through these commands, use: + +``` +add Add a domain name to a Clever Cloud application +favourite Manage Clever Cloud application favourite domain name +rm Remove a domain name from a Clever Cloud application +``` + +> [!TIP] +> You can can set the same domain with multiple apps thanks to [prefix routing](https://developers.clever-cloud.com/doc/administrate/domain-names/#prefix-routing), regex are also supported. For example you can add `mydomain.com/app1` domain to an application and `mydomain.com/app2` to another + +To (un)set the favourite domain, use: + +``` +clever domain favourite set FQDN +clever domain favourite unset FQDN +``` + +## scale and dedicated build + +You can easily change the number of instances and `flavor` for an application. It can also have a different `flavor` used for build phase, to get +it done faster. We also provides horizontal and vertical scaling: you can set a +minimal/maximal `flavor` and number of instance, then we autoscale depending on +incoming load. To change this, use `clever scale` with the following options: + +``` +[--flavor] FLAVOR The scale of your application +[--min-flavor] MINFLAVOR The minimum scale for your application +[--max-flavor] MAXFLAVOR The maximum scale for your application +[--instances] INSTANCES The number of parallels instances +[--min-instances] MININSTANCES The minimum number of parallels instances +[--max-instances] MAXINSTANCES The maximum number of parallels instances +[--build-flavor] BUILDFLAVOR The size of the build instance, or `disabled` +``` + +> [!NOTE] +> Available instances flavors are: `pico`, `nano`, `XS`, `S`, `M`, `L`, `XL`, `2XL`, `3XL` +> +> Due to its low memory (256 MiB) `pico` is not always available. When selected, a dedicated `S` instance is used for build by default. + +## tcp-redirs + +A Clever Cloud application activate TCP redirections in `default` or `cleverapps` namespace: + +``` +clever tcp-redirs add --namespace NAMESPACE +clever tcp-redirs remove --namespace NAMESPACE PORT +``` + +To list enabled TCP redirection, use: + +``` +clever tcp-redirs +``` + +- [Learn more about TCP redirections](https://developers.clever-cloud.com/doc/administrate/tcp-redirections/) diff --git a/docs/applications-deployment-lifecycle.md b/docs/applications-deployment-lifecycle.md new file mode 100644 index 00000000..f2c2db2a --- /dev/null +++ b/docs/applications-deployment-lifecycle.md @@ -0,0 +1,118 @@ +# Clever Cloud Applications: deployment and lifecycle + +A Clever Cloud application can easily be deployed and accessed once created, through following commands. Each can target a specfic application in the current folder, adding `[--alias, -a] ALIAS`. + +## deploy | cancel + +Once changes are commited in your local git repository, you can deploy it: + +``` +clever deploy +``` + +It will `git push` your code on the remote repository of your application on Clever Cloud automatically. You can, of course, use option to `force push` or use specific local branch for example: + +``` +[--branch, -b] BRANCH Branch to push (current branch by default) (default: ) +[--quiet, -q] Don't show logs during deployment (default: false) +[--force, -f] Force deploy even if it's not fast-forwardable (default: false) +[--follow] Continue to follow logs after deployment has ended (default: false) +[--same-commit-policy, -p] SAME-COMMIT-POLICY Which policy to apply when the local commit is the same as the remote one. Available policies are (error, ignore, restart, rebuild) (default: error) +``` + +> [!TIP] +> You can cancel a deployment with `clever cancel-deploy` command. You can also [configure an application](applications-config.md#config) so that a new deployment cancels the current one. + +## console | open + +Once deployed, you can open the application on your default browser or [Clever Cloud Console](https://console.clever-cloud.com): + +``` +clever open +clever console +``` + +## status + +To get application state, options or running/scaling status, use: + +``` +clever status +``` + +## restart + +Once deployed, an application can be restarted: + +``` +clever restart +``` + +By default, it will use its build cache when available but you can override it or use other available options: + +``` +[--commit] COMMIT ID Restart the application with a specific commit id +[--without-cache] Restart the application without using cache (default: false) +[--quiet, -q] Don't show logs during deployment (default: false) +[--follow] Continue to follow logs after deployment has ended (default: false) +``` + +## ssh + +A Clever Cloud application is a running virtual machine you can ssh to, as a user (`bas`). By default, it will use `OpenSSH` configuration, but you can target a specific identity file: + +``` +clever ssh [--identity-file, -i] IDENTITY-FILE +``` + +## logs + +When you deploy an application on Clever Cloud, we collect its logs, hosted in our internal Pulsar stack, all included. To listen to the stream, use: + +``` +clever logs +``` + +You can also get logs from a specific timeline, deployment or add-on through +options: + +``` +[--before, --until] BEFORE Fetch logs before this date (ISO8601) +[--after, --since] AFTER Fetch logs after this date (ISO8601) +[--search] SEARCH Fetch logs matching this pattern +[--deployment-id] DEPLOYMENT_ID Fetch logs for a given deployment +[--addon] ADDON_ID Add-on ID +``` + +## access logs + +When you deploy an application on Clever Cloud, we collect its access logs, hosted in our internal Pulsar stack, all included. To listen to the stream, use: + +``` +clever accesslogs +``` + +You can also get access logs from a specific timeline or add-on through options, in multiple formats: + +``` +[--format, -F] FORMAT Output format (human, json, simple, extended, clf) (default: human) +[--before, --until] BEFORE Fetch logs before this date (ISO8601) +[--after, --since] AFTER Fetch logs after this date (ISO8601) +[--follow, -f] Display access logs continuously (ignores before/until, after/since) (default: false) +[--addon] ADDON_ID Add-on ID +``` + +## activity + +To get deployment activity, use: + +``` +clever activity +``` + +By default, it will show you last 10 deployments. You can show all or listen to a stream of incoming deployments through options: + +``` +[--follow, -f] Track new deployments in activity list (default: false) +[--show-all] Show all activity (default: false) +``` diff --git a/docs/applications-management.md b/docs/applications-management.md new file mode 100644 index 00000000..31a29965 --- /dev/null +++ b/docs/applications-management.md @@ -0,0 +1,106 @@ +# Clever Cloud Applications: management + +## create + +You can create a new application on Clever Cloud and it will be linked to your local folder. Only its `type` is required, it should be one of: `docker`, `go`, `gradle`, `haskell`, `jar`,`maven`, `meteor`, `node`, `php`, `play1`, `play2`, `python`, `ruby`, `rust`, `sbt`, `static-apache` or `war`. Choose also its name . + +``` +clever create -t TYPE APP_NAME +``` + +You can also use one of the following optional parameters: + +#### Tasks + +``` +--task -T [CC_RUN_COMMAND] +``` + +You can declare a new application as a Clever Task. Once deployed, a Task executes its `CC_RUN_COMMAND` and then stops. This value can be set by an (optional) parameter or later through `clever env set` command. + +You can execute a Task whenever needed through a `clever restart` or modify it and `clever deploy` a new revision. You'll only be billed for the build/execution time, per second. + +> [!NOTE] +> Except its lifecycle, a Clever Task is identical to an application and accepts the same environment variables. + +#### GitHub repositories + +``` +--github owner/repo +``` + +If your Clever Cloud account is linked to a GitHub account, you can deploy any of your GitHub repositories as an application thanks to this parameter. + +#### Other optional parameters + +You can ask to deploy your application in a specific organisation/user account, region, with an alias different from its name: + +``` +[--org, -o, --owner] ID/NAME +[--alias, -a] ALIAS +[--region, -r] ZONE +``` + +Default region is our Paris datacenters (`par`), but it can be: + +- `par` (Paris, [Clever Cloud](https://www.clever-cloud.com/infrastructure/)) +- `rbx` (Roubaix, OVHcloud) +- `rbxhds` (Roubaix, HDS servers, OVHcloud) +- `scw` (Paris, [Scaleway DC5](https://www.clever-cloud.com/blog/press/2023/01/17/clever-cloud-and-scaleway-join-forces-to-unveil-a-sovereign-european-paas-offering/)) +- `jed` (Jeddah, Oracle Cloud) +- `mtl` (Montreal, OVHcloud) +- `sgp` (Singapore, OVHcloud) +- `syd` (Sydney, OVHcloud) +- `wsw` (Warsaw, OVHcloud) + +After the application creation, you can ask for a `json` formatted report instead of an `human` sentence: + +``` +[--format, -F] FORMAT +``` + +## (un)link and make-default + +If an application already exists in you Clever Clound account, you can link it to any local directory to control it. You can even link several applications to a single folder, each one with a different name and/or alias. This is done through the `.clever.json` file. + +``` +clever link APP_ID/NAME [--alias, -a] ALIAS [--org, -o, --owner] ID/NAME +``` + +If muliple applications are linked, you can define one as default with it alias: + +``` +clever make-default ALIAS +``` + +To unlink an application: + +``` +clever unlink ALIAS +``` + +## applications + +You can list linked applications of a folder, you'll get : ID, alias and deployment URL. + +``` +clever applications +``` + +If you only need to get aliases or the result in the JSON format: + +``` +[--only-aliases] List only application aliases (default: false) +[--json, -j] Show result in JSON format (default: false) +``` + +## delete + +To delete an application and unlink it from the current folder you only need to: + +``` +clever delete [--alias, -a] ALIAS +``` + +> [!TIP] +> You can skip confirmation adding the `--yes` or `-y` parameter. diff --git a/docs/nexus-config.md b/docs/nexus-config.md index 7ceffa4c..48e42522 100644 --- a/docs/nexus-config.md +++ b/docs/nexus-config.md @@ -1,53 +1,38 @@ # Nexus configuration -We use a self hosted Nexus repository to distribute `.deb`, `.nupkg` and `.rpm`. -It's available at [https://nexus.clever-cloud.com/](https://nexus.clever-cloud.com/). +We use a self hosted Nexus repository to distribute `.deb`, `.nupkg` and `.rpm`. It's available at [https://nexus.clever-cloud.com/](https://nexus.clever-cloud.com/). ## Repositories -### `.deb` repositories +### `.deb` repository -We have two repositories for `.deb` packages: +We have a repository for `.deb` packages, available [here](https://nexus.clever-cloud.com/#browse/browse:deb). * stable: [deb](https://nexus.clever-cloud.com/#browse/browse:deb) -Link to Nexus [apt-repositories docs](https://help.sonatype.com/repomanager3/formats/apt-repositories). +The repository is signed with the PGP key `Clever Cloud Nexus (deb)`. The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key). The private key, public key and passphrase are stored in our vault. -The repository is signed with the PGP key `Clever Cloud Nexus (deb)`. +### `.nupkg` repository -* The public key is available publised on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key) -* The private key, public key and passphrase are stored in our vault. +We have a repository for `.nupkg` packages, available [here](https://nexus.clever-cloud.com/#browse/browse:nupkg) -### `.nupkg` repositories +* Link to Nexus [nuget-repositories docs](https://help.sonatype.com/repomanager3/formats/nuget-repositories) -We have two repositories for `.nupkg` packages: +### `.rpm` repository -* stable: [nupkg](https://nexus.clever-cloud.com/#browse/browse:nupkg) +We have a repository for `.rpm` packages, available [here](https://nexus.clever-cloud.com/#browse/browse:rpm). -Link to Nexus [nuget-repositories docs](https://help.sonatype.com/repomanager3/formats/nuget-repositories). +* Link to Nexus [yum-repositories docs](https://help.sonatype.com/repomanager3/formats/yum-repositories) -WIP +The repository is not signed, but the `.rpm` packages are. -### `.rpm` repositories +The repo description is maintained in this git repo at `templates/rpm/cc-nexus-rpm.repo`. It's published on the Cellar at [https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo](https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo). The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key). The private key, public key and passphrase are stored in our vault. -We have two repositories for `.rpm` packages: +### GnuPG Keys -* stable: [rpm](https://nexus.clever-cloud.com/#browse/browse:rpm) +Steps to follow to generate a new pair of GnuPG keys: -Link to Nexus [yum-repositories docs](https://help.sonatype.com/repomanager3/formats/yum-repositories). - -The repository is not signed but the `.rpm` packages are. - -* The repo description is maintained in this git repo at `templates/rpm/cc-nexus-rpm.repo`. - * It's published on the Cellar at [https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo](https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo) -* The public key is available publised on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key) -* The private key, public key and passphrase are stored in our vault. - -### PGP Keys - -Steps to follow to generate a new pair of PGP keys: - -* Prepate a random string for the passphrase (30 chars is good) +* Prepare a random string for the passphrase (30+ chars is good) * Run `gpg --gen-key` * Name: `Clever Cloud Nexus (deb)` * Email: ci@clever-cloud.com @@ -65,4 +50,4 @@ Steps to follow to generate a new pair of PGP keys: * `cat cc-nexus-deb.*.gpg.key cc-nexus-deb.combined.gpg.key` * Add the combined key to the vault along with the random passphrase. -This is an example for `deb` but the same goes for `rpm`. +This is an example for `deb` but the same goes for `rpm`. \ No newline at end of file diff --git a/docs/services-depedencies.md b/docs/services-depedencies.md new file mode 100644 index 00000000..cb658712 --- /dev/null +++ b/docs/services-depedencies.md @@ -0,0 +1,51 @@ +# Clever Cloud Services dependencies + +On Clever Cloud, applications can expose configuration to share environment variables with other services within the same account/organization. Add-ons are preconfigured with an exposed configuration. Thus, when they're linked to an application, they automatically share credentials or important variables needed to configure and use them. + +Following commands help you with that. Each can target a specfic application in the current folder, adding `[--alias, -a] ALIAS`. + +## published-config + +To configure exposed configuration, use: + +``` +clever published-config COMMAND +``` + +Available commands are `set`, `rm` (remove) or `import`. The latter reads data from `stdin` so use it as is: + +``` +clever published-config import < file.config +``` + +## service + +To list services dependencies, use: + +``` +clever service +``` + +You can filter results through these options. + +``` +[--only-apps] Only show app dependencies (default: false) +[--only-addons] Only show add-on dependencies (default: false) +[--show-all] Show all available add-ons and applications (default: false) +``` + +To create or delete services dependencies, use: + +``` +clever service COMMAND ADDON_OR_APP_ID +clever service COMMAND ADDON_OR_APP_NAME +``` + +Available commands are: + +``` +link-app Add an existing app as a dependency +unlink-app Remove an app from the dependencies +link-addon Link an existing add-on to this application +unlink-addon Unlink an add-on from this application +``` diff --git a/docs/log-drains.md b/docs/services-logs-drains.md similarity index 80% rename from docs/log-drains.md rename to docs/services-logs-drains.md index 97462938..06fca817 100644 --- a/docs/log-drains.md +++ b/docs/services-logs-drains.md @@ -1,29 +1,21 @@ +# Clever Cloud Logs Drains -# Logs Drains +You can use Clever Tools to control logs drains: -```sh -# create drain -clever drain create [--alias ] [--username ] [--password ] ``` - -```sh -# list drains clever drain [--alias ] -``` - -```sh -# remove drain +clever drain create [--alias ] [--username ] [--password ] clever drain remove [--alias ] ``` Where `DRAIN-TYPE` is one of: -- `TCPSyslog`: for TCP syslog endpoint; -- `UDPSyslog`: for UDP syslog endpoint; -- `HTTP`: for TCP syslog endpoint (note that this endpoint has optional username/passwordparameters as HTTP Basic Authentication); -- `ElasticSearch`: for ElasticSearch endpoint (note that this endpoint requires username/password parameters as HTTP Basic Authentication); -- `DatadogHTTP`: for Datadog endpoint (note that this endpoint needs your Datadog API Key). -- `NewRelicHTTP`: for NewRelic endpoint (note that this endpoint needs your NewRelic API Key). +- `TCPSyslog`: for TCP syslog endpoint +- `UDPSyslog`: for UDP syslog endpoint +- `HTTP`: for TCP syslog endpoint (note that this endpoint has optional username/passwordparameters as HTTP Basic Authentication) +- `ElasticSearch`: for ElasticSearch endpoint (note that this endpoint requires username/password parameters as HTTP Basic Authentication) +- `DatadogHTTP`: for Datadog endpoint (note that this endpoint needs your Datadog API Key) +- `NewRelicHTTP`: for NewRelic endpoint (note that this endpoint needs your NewRelic API Key) ## ElasticSearch logs drains @@ -35,14 +27,14 @@ Datadog has two zones, EU and COM. An account on one zone is not available on th To create a [Datadog](https://docs.datadoghq.com/api/?lang=python#send-logs-over-http) drain, you just need to use one of the following command depending on your zone: -```sh +``` # EU clever drain create DatadogHTTP "https://http-intake.logs.datadoghq.eu/v1/input/?ddsource=clevercloud&service=&host=" # US clever drain create DatadogHTTP "https://http-intake.logs.datadoghq.com/v1/input/?ddsource=clevercloud&service=&host=" ``` -Please note that the `host` query parameter is not mandatory: in the Datadog pipeline configuration, you can map `@source_host` which is the host provided by Clever Cloud in logs as `host` property. +The `host` query parameter is not mandatory: in the Datadog pipeline configuration, you can map `@source_host` which is the host provided by Clever Cloud in logs as `host` property. ## NewRelic logs drains @@ -50,6 +42,6 @@ NewRelic has two zones, EU and US. An account on one zone is not available on th To create a [NewRelic](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) drain, you just need to use: -```sh +``` clever drain create NewRelicHTTP "https://log-api.eu.newrelic.com/log/v1" --api-key ``` diff --git a/docs/services-notifications-webhooks.md b/docs/services-notifications-webhooks.md new file mode 100644 index 00000000..3c6d0979 --- /dev/null +++ b/docs/services-notifications-webhooks.md @@ -0,0 +1,64 @@ +# Clever Cloud services: notifications and hooks + +When events happen on Clever Cloud, during add-ons or applications lifecycle for example, you can send email notifications or trigger webhooks. For each of the following command, you can list all items and/or target a specific user/organization through these parameters: + +``` +[--org, -o, --owner] Organisation ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the `--org` option (default: false) +``` + +## notify-email + +You can send email notifications when an event occurs. To list them, use: + +``` +clever notify-email +``` + +To add a notification process to an application, use: + +``` +clever notify-email add --notify ||"ORGANISATION" NAME +``` + +Available options are: + +``` +[--event] TYPE Restrict notifications to specific event types +[--service] SERVICE_ID Restrict notifications to specific applications and add-ons +--notify ||"ORGANISATION" Notify a user, a specific email address or the whole organisation (multiple values allowed, comma separated) +``` + +To delete a notification process, use: + +``` +clever notify-email remove NOTIFICATION-ID +``` + +## webhooks + +You can trigger webhooks when an event occurs. To list them, use: + +``` +clever webhooks +``` + +To add a webhook to an application, use: + +``` +clever webhooks add NAME URL +``` + +You can set the format, restrict to a service or event types through these parameters: + +``` +[--format] FORMAT Format of the body sent to the webhook ('raw', 'slack', 'gitter', or 'flowdock') (default: raw) +[--event] TYPE Restrict notifications to specific event types +[--service] SERVICE_ID Restrict notifications to specific applications and add-ons +``` + +To delete a webhook, use: + +``` +clever webhooks remove NOTIFICATION-ID +``` diff --git a/docs/setup-systems.md b/docs/setup-systems.md index 7593577f..7d42d91f 100644 --- a/docs/setup-systems.md +++ b/docs/setup-systems.md @@ -1,12 +1,29 @@ # How to install Clever Tools + +Clever Cloud CLI is based on Node.js. We thought it to be easily available on any platform. Thus, you can download Clever Tools as [a npm package](https://www.npmjs.com/package/clever-tools), but also through package managers or as a binary on many systems: + +- [GNU/Linux](/docs/setup-systems.md#gnulinux) + - [Arch Linux (AUR)](/docs/setup-systems.md#arch-linux-aur) + - [CentOS/Fedora (.rpm)](/docs/setup-systems.md#centosfedora-rpm) + - [Debian/Ubuntu (.deb)](/docs/setup-systems.md#debianubuntu-deb) + - [Exherbo](/docs/setup-systems.md#exherbo) + - [Binary (.tar.gz)](/docs/setup-systems.md#other-distributions-targz) +- [macOS](/docs/setup-systems.md#macos) + - [Homebrew](/docs/setup-systems.md#homebrew) + - [Binary (.tar.gz)](/docs/setup-systems.md#binary-zip) +- [Windows](/docs/setup-systems.md#windows) + - [Chocolatey](/docs/setup-systems.md#chocolatey) + - [Binary (.zip)](/docs/setup-systems.md#binary-zip) +- [Docker](/docs/setup-systems.md#docker) +- [Nix](/docs/setup-systems.md#nix-package-manager) + ## GNU/Linux ### Arch Linux (AUR) -If you are using Arch Linux, the packages can be installed from AUR with this repo: [clever-tools-bin](https://aur.archlinux.org/packages/clever-tools-bin/). -If you don't know how to use this, you can run: +If you are using Arch Linux, the packages can be installed from AUR with this repo: [clever-tools-bin](https://aur.archlinux.org/packages/clever-tools-bin/). If you don't know how to use this, you can run: -```sh +``` git clone https://aur.archlinux.org/clever-tools-bin.git clever-tools cd clever-tools makepkg -si @@ -14,18 +31,9 @@ makepkg -si ### CentOS/Fedora (.rpm) ---- - -#### Warning - -We recently moved from Bintray to a self-hosted Nexus repository available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com). -If you were using Bintray to install our `.rpm` packages, you will need to remove the old `/etc/yum.repos.d/bintray-clevercloud-rpm.repo` before going further. - ---- - If you are using a GNU/Linux distribution that uses `.rpm` packages like CentOS or Fedora, you can run: -```sh +``` curl -s https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo > /etc/yum.repos.d/cc-nexus-rpm.repo yum update yum install clever-tools @@ -34,21 +42,13 @@ yum install clever-tools NOTES: * The `.rpm` packages are hosted on Clever Cloud's public Nexus instance available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com). +* If you want access to the beta channel, you will need to edit `/etc/yum.repos.d/cc-nexus-rpm.repo` and set `enabled=1` for the `[clever-tools-beta]`. ### Debian/Ubuntu (.deb) ---- - -#### Warning - -We recently moved from Bintray to a self-hosted Nexus repository available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com). -If you were using Bintray to install our `.deb` packages, you will need to edit your `/etc/apt/sources.list` and remove the old entry with `https://dl.bintray.com/clevercloud/deb` before going further. - ---- - If you are using a GNU/Linux distribution that uses `.deb` packages like Debian or Ubuntu, you can run: -```sh +``` curl -fsSL https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key | gpg --dearmor -o /usr/share/keyrings/cc-nexus-deb.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/cc-nexus-deb.gpg] https://nexus.clever-cloud.com/repository/deb stable main" | tee -a /etc/apt/sources.list apt-get update @@ -59,12 +59,17 @@ NOTES: * The `.deb` packages are hosted on Clever Cloud's public Nexus instance available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com). * Our PGP key is required to trust the repository. +* If you want access to the beta channel, you can use this in your `sources.list`: + +```sh +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/cc-nexus-deb.gpg] https://nexus.clever-cloud.com/repository/deb-beta beta main" | tee -a /etc/apt/sources.list +``` ### Exherbo If you are using Exherbo, you can run: -```sh +``` cave resolve repository/CleverCloud -zx1 cave resolve clever-tools-bin -zx ``` @@ -73,7 +78,7 @@ cave resolve clever-tools-bin -zx If you are using another GNU/Linux distribution, you can download a `.tar.gz` archive and extract the binary in your `PATH`: -```sh +``` curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_linux.tar.gz tar xvzf clever-tools-latest_linux.tar.gz cp clever-tools-latest_linux/clever ~/.local/bin/ @@ -82,6 +87,7 @@ cp clever-tools-latest_linux/clever ~/.local/bin/ NOTES: * The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_linux.tar.gz](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_linux.tar.gz). +* You can also retrieve any release (including beta) on this Cellar bucket by replacing `latest` (path and filename) with the version number you need. ## macOS @@ -89,7 +95,7 @@ NOTES: If you are using macOS and you have [homebrew](https://brew.sh) installed, you can run: -```sh +``` brew install CleverCloud/homebrew-tap/clever-tools ``` @@ -97,7 +103,7 @@ brew install CleverCloud/homebrew-tap/clever-tools If you are using macOS, but you don't have [Homebrew](https://brew.sh) installed, you can download a `.tar.gz` archive and extract the binary in your `PATH`: -```sh +``` curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_macos.tar.gz tar xvzf clever-tools-latest_macos.tar.gz cp clever-tools-latest_macos/clever ~/.local/bin/ @@ -106,23 +112,15 @@ cp clever-tools-latest_macos/clever ~/.local/bin/ NOTES: * The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_macos.tar.gz](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_macos.tar.gz). +* You can also retrieve any release (including beta) on this Cellar bucket by replacing `latest` (path and filename) with the version number you need. ## Windows ### Chocolatey ---- - -#### Warning - -We recently moved from Bintray to a self-hosted Nexus repository available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com). -If you were using Bintray to install our `.nupkg` packages, you will need to remove the old source. - ---- - If you are using Windows and you have [chocolatey](https://chocolatey.org) installed, you can run: -```bash +``` choco sources add -n=clevercloud -s='https://nexus.clever-cloud.com/repository/nupkg/' choco install clever-tools ``` @@ -134,12 +132,13 @@ If you are using Windows, but you don't have [chocolatey](https://chocolatey.org NOTES: * The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_win.zip](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_win.zip). +* You can also retrieve any release (including beta) on this Cellar bucket by replacing `latest` (path and filename) with the version number you need. ## Docker If you are using docker, you can use the image provided [here](https://hub.docker.com/r/clevercloud/clever-tools/). -```sh +``` docker pull clevercloud/clever-tools docker run --rm clever-tools ``` @@ -156,4 +155,4 @@ COPY --from=clevercloud/clever-tools /bin/clever /usr/local/bin/clever If you are using Nix, you will find a Nix derivation on Fretlink's GitHub repository: -* https://github.com/fretlink/clever-tools-nix +* https://github.com/fretlink/clever-tools-nix \ No newline at end of file