From 7e3224b8470e9c7dca83f56978b1a2175eee5393 Mon Sep 17 00:00:00 2001 From: Grayson Adkins Date: Mon, 15 Aug 2022 21:47:00 -0500 Subject: [PATCH 1/6] adding cli reference --- docs/guides/git-integrations.md | 16 ---- docs/references/cli/config.md | 1 + docs/references/cli/connect.md | 1 + docs/references/cli/help.md | 1 + docs/references/cli/login.md | 1 + docs/references/cli/logout.md | 1 + docs/references/cli/preview.md | 160 ++++++++++++++++++++++++++++++++ docs/references/cli/project.md | 1 + docs/references/cli/uffizzi.md | 18 ++++ docs/references/cli/version.md | 1 + mkdocs.yml | 16 +++- 11 files changed, 197 insertions(+), 20 deletions(-) delete mode 100644 docs/guides/git-integrations.md create mode 100644 docs/references/cli/config.md create mode 100644 docs/references/cli/connect.md create mode 100644 docs/references/cli/help.md create mode 100644 docs/references/cli/login.md create mode 100644 docs/references/cli/logout.md create mode 100644 docs/references/cli/preview.md create mode 100644 docs/references/cli/project.md create mode 100644 docs/references/cli/uffizzi.md create mode 100644 docs/references/cli/version.md diff --git a/docs/guides/git-integrations.md b/docs/guides/git-integrations.md deleted file mode 100644 index 1c2d1df..0000000 --- a/docs/guides/git-integrations.md +++ /dev/null @@ -1,16 +0,0 @@ -Uffizzi's GitHub integration provides an easy way for you to preview code changes made to your GitHub repositories. To configure this integration, you will need to install the Uffizzi app in your GitHub account, then grant Uffizzi read-only access to the repositories you want to preview. Follow these simple steps to install the Uffizzi app in your GitHub account: - -1. Log into [app.uffizzi.com](https://app.uffizzi.com) -2. Navigate to **Settings** -> **Integrations** -3. Select the **CONFIGURE** button next to GitHub -4. A pop-up window will appear asking you to authenticate with GitHub -5. Once authenticated, select which repositories you want Uffizzi to have access to -6. Save your selection - -Your Uffizzi account should now have access to the repositories you selected. Repositories that are visible to Uffizzi can be referenced in your compose spec. For more information on using the GitHub build context for compose, see the [Uffizzi Compose file reference](../references/compose-spec.md). - -Additionally, Uffizzi's GitHub integration will configure webhooks for your repositories so that when your repository changes Uffizzi will recognize the change and apply accordingly. - -Auto-deploying new commits- For existing Preview Deployments any new commits to the relevant repositories will be built and the Deployment will be updated automatically. This is the default configuration in `docker-compose.uffizzi.yml`, if you want to turn this feature off you can set [`x-uffizzi-auto-deploy-updates: false`](https://docs.uffizzi.com/references/compose-spec/#x-uffizzi-auto-deploy-updates). - ->**Note:** Any changes made to your configuration in `docker-compose.uffizzi.yml` will be recognized and will be applied to any future Preview Deployments - these changes will not impact existing Preview Deployments. diff --git a/docs/references/cli/config.md b/docs/references/cli/config.md new file mode 100644 index 0000000..9c2476e --- /dev/null +++ b/docs/references/cli/config.md @@ -0,0 +1 @@ +# `uffizzi config` \ No newline at end of file diff --git a/docs/references/cli/connect.md b/docs/references/cli/connect.md new file mode 100644 index 0000000..5349429 --- /dev/null +++ b/docs/references/cli/connect.md @@ -0,0 +1 @@ +# `uffizzi connect` \ No newline at end of file diff --git a/docs/references/cli/help.md b/docs/references/cli/help.md new file mode 100644 index 0000000..39f8da5 --- /dev/null +++ b/docs/references/cli/help.md @@ -0,0 +1 @@ +# `uffizzi help` \ No newline at end of file diff --git a/docs/references/cli/login.md b/docs/references/cli/login.md new file mode 100644 index 0000000..be0594a --- /dev/null +++ b/docs/references/cli/login.md @@ -0,0 +1 @@ +# `uffizzi login` \ No newline at end of file diff --git a/docs/references/cli/logout.md b/docs/references/cli/logout.md new file mode 100644 index 0000000..6ee08df --- /dev/null +++ b/docs/references/cli/logout.md @@ -0,0 +1 @@ +# `uffizzi logout` \ No newline at end of file diff --git a/docs/references/cli/preview.md b/docs/references/cli/preview.md new file mode 100644 index 0000000..fbb6f5a --- /dev/null +++ b/docs/references/cli/preview.md @@ -0,0 +1,160 @@ +# `uffizzi preview` + +## Usage + +``` +$ uffizzi preview COMMAND +``` + +## Description + +Manage Uffizzi previews + +## Child commands + +| **Command** | **Description** | +|-------------------------------------------------|------------------------------| +| [uffizzi preview create](preview.md#create) | Create a preview | +| [uffizzi preview delete](preview.md#delete) | Delete a preview | +| [uffizzi preview describe](preview.md#describe) | Display details of a preview | +| [uffizzi preview list](preview.md#list) | list all previews | + + +## `uffizzi preview create` + +### Usage + +``` +$ uffizzi preview create [POSITIONAL_ARGUMENTS] [UFFIZZI_WIDE_FLAG ...] +``` + +### Description + +Creates a new preview. If no COMPOSE_FILE is specified, the preview is created with the project´s default compose file. + +This command can fail for the following reasons: + +- The project does not have a default compose file set. Run `$ uffizzi compose --help` for details. +- The alternate compose file is invalid. + +### Positional arguments + +`[COMPOSE_FILE]` - An alternate compose file to the default compose. + +You can pass a compose file to this command to create an ad hoc preview of an alternate compose configuration. The file passed via this argument does not replace the default compose file for the project. Alternate compose files share the same lifecyle as the previews they create: when the preview is deleted, the alternate compose is deleted by the Uffizzi API. + +### Uffizzi wide flags + +The flage `--project` is available to all commands. Run `$ uffizzi help` for details. + +### Examples + +To create a preview with the project´s default compose file, run: + +``` +$ uffizzi preview create +``` + +To create a preview with an alternate compose file, run: + +``` +$ uffizzi preview create docker-compose.uffizzi.alt.yml +``` + +## `uffizzi preview delete` + +### Usage + +``` +$ uffizzi preview delete [POSITIONAL_ARGUMENTS] [UFFIZZI_WIDE_FLAG ...] +``` + +### Description + +Deletes a preview with the given preview ID. This command can fail for the following reasons: + +- The preview specified does not exist. +- The preview specified belongs to a different project. + +### Positional arguments + +`[PREVIEW_ID]` - ID for the preview you want to delete. + +### Uffizzi wide flags + +The flage `--project` is available to all commands. Run `$ uffizzi help` for details. + +### Examples + +The following command deletes the preview with ID `deployment-213`: + +``` +$ uffizzi preview delete deployment-213 +``` + +## `uffizzi preview describe` + +### Usage + +``` +$ uffizzi preview describe [POSITIONAL_ARGUMENTS] [UFFIZZI_WIDE_FLAG ...] +``` + +### Description + +Shows metadata for a project given a valid preview ID. This command can fail for the following reasons: + +- The preview specified does not exist. +- The preview specified belongs to a different project. + +### Positional arguments + +`[PREVIEW_ID]` - ID for the preview you want to describe. + +### Uffizzi wide flags + +The flage `--project` is available to all commands. Run `$ uffizzi help` for details. + +### Examples + +To list all previews in the default project, run: + +``` +$ uffizzi preview list +``` + +To list all previews in a project with name `my_project`, run: + +``` +$ uffizzi preview list --project="my_project" +``` + + +## `uffizzi preview list` + +### Usage + +``` +$ uffizzi preview list [UFFIZZI_WIDE_FLAG ...] +``` + +### Description + +Lists all previews for a project, including `active`, `building`, `deploying` and `failed` previews. + +### Uffizzi wide flags +The flage `--project` is available to all commands. Run `$ uffizzi help` for details. + +### Examples + +To list all previews in the default project, run: + +``` +$ uffizzi preview list +``` + +To list all previews in a project with name `my_project`, run: + +``` +$ uffizzi preview list --project="my_project" +``` diff --git a/docs/references/cli/project.md b/docs/references/cli/project.md new file mode 100644 index 0000000..0b64d37 --- /dev/null +++ b/docs/references/cli/project.md @@ -0,0 +1 @@ +# `uffizzi project` \ No newline at end of file diff --git a/docs/references/cli/uffizzi.md b/docs/references/cli/uffizzi.md new file mode 100644 index 0000000..a2839dc --- /dev/null +++ b/docs/references/cli/uffizzi.md @@ -0,0 +1,18 @@ +# Uffizzi command-line reference + +## `uffizzi` + +The base command for the Uffizzi CLI. + +### Child commands + +| **Command** | **Description** | +|-----------------------------------------|--------------------------------------------------------------| +| [uffizzi config](config.md) | Configure the Uffizzi CLI | +| [uffizzi connect](connect.md) | Grant a Uffizzi user account access to external services | +| [uffizzi help](help.md) | Show Uffizzi documentation | +| [uffizzi login](login.md) | Log in to a Uffizzi user account | +| [uffizzi logout](logout.md) | Log out of a Uffizzi user account | +| [uffizzi preview]() | Manage Uffizzi previews and view logs | +| [uffizzi project](project.md) | Manage Uffizzi project resources | +| [uffizzi version](version.md) | Print version information for Uffizzi CLI | diff --git a/docs/references/cli/version.md b/docs/references/cli/version.md new file mode 100644 index 0000000..e6ba372 --- /dev/null +++ b/docs/references/cli/version.md @@ -0,0 +1 @@ +# `uffizzi version` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5968969..e8fe1b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,7 +25,6 @@ theme: - content.code.annotate - navigation.instant - navigation.tracking - - navigation.tabs - navigation.sections - navigation.expand - navigation.indexes @@ -106,7 +105,6 @@ nav: - UFFIZZI_URL: uffizzi-url.md - Guides: - Configure password-protected environments: guides/password-protected.md - - Configure GitHub: guides/git-integrations.md - Connect to your container registry (Uffizzi CI): guides/container-registry-integrations.md - Add environment variables: guides/environment-variables.md - Add secrets: guides/secrets.md @@ -114,8 +112,18 @@ nav: - Configure role-based access: guides/rbac.md - Configure SSO: guides/single-sign-on.md - Networking and architecture: guides/networking.md - - References: - - Uffizzi Compose file reference: references/compose-spec.md + - Docker Compose for Uffizzi: + - Compose file reference: references/compose-spec.md + - Command-line reference: + - uffizzi (base command): references/cli/uffizzi.md + - uffizzi config: references/cli/config.md + - uffizzi connect: references/cli/connect.md + - uffizzi help: references/cli/help.md + - uffizzi login: references/cli/login.md + - uffizzi logout: references/cli/logout.md + - uffizzi preview: references/cli/preview.md + - uffizzi project: references/cli/project.md + - uffizzi version: references/cli/version.md - Uffizzi environment variables: references/uffizzi-environment-variables.md - Example Uffizzi Compose: references/example-compose.md - Use Cases: From ea71013f1a50ce4049ab866842c89547604119d7 Mon Sep 17 00:00:00 2001 From: Grayson Adkins Date: Mon, 15 Aug 2022 21:49:30 -0500 Subject: [PATCH 2/6] added link to preview cmd --- docs/references/cli/uffizzi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/cli/uffizzi.md b/docs/references/cli/uffizzi.md index a2839dc..19713db 100644 --- a/docs/references/cli/uffizzi.md +++ b/docs/references/cli/uffizzi.md @@ -13,6 +13,6 @@ The base command for the Uffizzi CLI. | [uffizzi help](help.md) | Show Uffizzi documentation | | [uffizzi login](login.md) | Log in to a Uffizzi user account | | [uffizzi logout](logout.md) | Log out of a Uffizzi user account | -| [uffizzi preview]() | Manage Uffizzi previews and view logs | +| [uffizzi preview](preview.md) | Manage Uffizzi previews and view logs | | [uffizzi project](project.md) | Manage Uffizzi project resources | | [uffizzi version](version.md) | Print version information for Uffizzi CLI | From d2d07386d42040c2b8bdda8c9c06cb6540f17dea Mon Sep 17 00:00:00 2001 From: Grayson Adkins Date: Mon, 15 Aug 2022 21:51:31 -0500 Subject: [PATCH 3/6] added formatting --- docs/references/cli/preview.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/references/cli/preview.md b/docs/references/cli/preview.md index fbb6f5a..f4471f7 100644 --- a/docs/references/cli/preview.md +++ b/docs/references/cli/preview.md @@ -30,9 +30,7 @@ $ uffizzi preview create [POSITIONAL_ARGUMENTS] [UFFIZZI_WIDE_FLAG ...] ### Description -Creates a new preview. If no COMPOSE_FILE is specified, the preview is created with the project´s default compose file. - -This command can fail for the following reasons: +Creates a new preview. If no `COMPOSE_FILE` is specified, the preview is created with the project´s default compose file. This command can fail for the following reasons: - The project does not have a default compose file set. Run `$ uffizzi compose --help` for details. - The alternate compose file is invalid. From 43507c325096e1a8c9b9be7c5b7532460867124a Mon Sep 17 00:00:00 2001 From: Grayson Adkins Date: Mon, 15 Aug 2022 21:53:01 -0500 Subject: [PATCH 4/6] fixed typo --- docs/references/cli/preview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/references/cli/preview.md b/docs/references/cli/preview.md index f4471f7..708eb6a 100644 --- a/docs/references/cli/preview.md +++ b/docs/references/cli/preview.md @@ -43,7 +43,7 @@ You can pass a compose file to this command to create an ad hoc preview of an al ### Uffizzi wide flags -The flage `--project` is available to all commands. Run `$ uffizzi help` for details. +The flag `--project` is available to all commands. Run `$ uffizzi help` for details. ### Examples @@ -80,7 +80,7 @@ Deletes a preview with the given preview ID. This command can fail for the follo ### Uffizzi wide flags -The flage `--project` is available to all commands. Run `$ uffizzi help` for details. +The flag `--project` is available to all commands. Run `$ uffizzi help` for details. ### Examples @@ -111,7 +111,7 @@ Shows metadata for a project given a valid preview ID. This command can fail for ### Uffizzi wide flags -The flage `--project` is available to all commands. Run `$ uffizzi help` for details. +The flag `--project` is available to all commands. Run `$ uffizzi help` for details. ### Examples @@ -141,7 +141,7 @@ $ uffizzi preview list [UFFIZZI_WIDE_FLAG ...] Lists all previews for a project, including `active`, `building`, `deploying` and `failed` previews. ### Uffizzi wide flags -The flage `--project` is available to all commands. Run `$ uffizzi help` for details. +The flag `--project` is available to all commands. Run `$ uffizzi help` for details. ### Examples From 7843363c412a9275d73299bd4cbf407a2ef60493 Mon Sep 17 00:00:00 2001 From: Grayson Adkins Date: Mon, 15 Aug 2022 21:55:30 -0500 Subject: [PATCH 5/6] updated describe examples --- docs/references/cli/preview.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/references/cli/preview.md b/docs/references/cli/preview.md index 708eb6a..f7a3d75 100644 --- a/docs/references/cli/preview.md +++ b/docs/references/cli/preview.md @@ -115,19 +115,13 @@ The flag `--project` is available to all commands. Run `$ uffizzi help` for deta ### Examples -To list all previews in the default project, run: +The following command prints metadata for the preview with ID +`deployment-213`: ``` -$ uffizzi preview list +$ uffizzi preview describe deployment-213_project ``` -To list all previews in a project with name `my_project`, run: - -``` -$ uffizzi preview list --project="my_project" -``` - - ## `uffizzi preview list` ### Usage From 5294e29469d40c81a6c4a22e526fe78f5c2c4462 Mon Sep 17 00:00:00 2001 From: Grayson Adkins Date: Mon, 15 Aug 2022 21:57:45 -0500 Subject: [PATCH 6/6] improved example --- docs/references/cli/preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/cli/preview.md b/docs/references/cli/preview.md index f7a3d75..e1581af 100644 --- a/docs/references/cli/preview.md +++ b/docs/references/cli/preview.md @@ -119,7 +119,7 @@ The following command prints metadata for the preview with ID `deployment-213`: ``` -$ uffizzi preview describe deployment-213_project +$ uffizzi preview describe deployment-213 ``` ## `uffizzi preview list`