From cc86eb75639074d361750effdddfa74cc716b172 Mon Sep 17 00:00:00 2001 From: Justin Kotalik Date: Mon, 16 Mar 2020 18:56:56 -0700 Subject: [PATCH] Docs for tye commands (#114) Adds docs for - tye init - tye run - tye deploy Somewhat follows the style of docs for dotnet commands. --- docs/commandline/tye-deploy.md | 66 ++++++++++++++++++++++++++++++ docs/commandline/tye-init.md | 66 ++++++++++++++++++++++++++++++ docs/commandline/tye-run.md | 72 +++++++++++++++++++++++++++++++++ docs/commandline/tye.md | 34 ++++++++++++++++ docs/frontend_backend_deploy.md | 2 +- docs/frontend_backend_run.md | 4 +- 6 files changed, 241 insertions(+), 3 deletions(-) create mode 100644 docs/commandline/tye-deploy.md create mode 100644 docs/commandline/tye-init.md create mode 100644 docs/commandline/tye-run.md create mode 100644 docs/commandline/tye.md diff --git a/docs/commandline/tye-deploy.md b/docs/commandline/tye-deploy.md new file mode 100644 index 00000000..1d081057 --- /dev/null +++ b/docs/commandline/tye-deploy.md @@ -0,0 +1,66 @@ +# tye deploy + +## Name + +`tye deploy` - Deploys the application to Kubernetes. + +## Synopsis + +```text +tye deploy [-?|-h|--help] [-i|--interactive] [-v|--verbosity ] [-f|--force] [] +``` + +## Description + +The `tye deploy` command will deploy an application to Kubernetes. `tye deploy` by default will: + +- Create a docker image for each project in your application. +- Push each docker image to your container registry. +- Generate a Kubernetes Deployment and Service for each project. +- Apply the generated Deployment and Service to your current Kubernetes context. + +## Arguments + +`PATH` + +The path to either a file or directory to execute `tye deploy` on. Can either be a yaml, sln, or project file, however it is recommend to have a tye.yaml file for `tye deploy`. + +If a directory path is specified, `tye deploy` will default to using these files, in the following order: + +- `tye.yaml` +- `*.sln` +- `*.csproj/*.fsproj` + +## Options + +- `-i|--interactive` + + Does an interactive deployment that will accept input for values that are required by default. + +- `-v|--verbosity ` + + The verbosity of logs emitted by `tye deploy`. Defaults to Info. + +- `-f|--force` + + Override validation and forces deployment. + +## Examples + +- Deploy an application from the current directory: + + ```text + tye deploy + ``` + +- Deploy an application with interactive input: + + ```text + tye run --interactive + ``` + +- Deploy an application, increasing log verbosity to Debug. + + ```text + tye deploy --verbosity Debug + ``` diff --git a/docs/commandline/tye-init.md b/docs/commandline/tye-init.md new file mode 100644 index 00000000..f2ad751b --- /dev/null +++ b/docs/commandline/tye-init.md @@ -0,0 +1,66 @@ +# tye init + +## Name + +`tye init` - Scaffolds a tye.yaml file representing the application. + +## Synopsis + +```text +tye init [-?|-h|--help] [-f|--force] [] +``` + +## Description + +The `tye init` command scaffolds a `tye.yaml` file to allow customizing different aspects of `tye run` and `tye deploy`. + +`tye init` will by default scaffold each project(s) in an application. For example, if there was a solution file (sln) that contained two csproj files, the `tye.yaml` contents would look like: + +```yaml +name: application +services: +- name: project1 + project: project1.csproj +- name: project2 + project: project2/project2.csproj +``` + +See [the tye.yaml schema](../schema.md) to learn more about customizations that can be made to the `tye.yaml` file. + +## Arguments + +`PATH` + +The path to either a file or directory to run `tye init` on. Can either be a yaml, sln, or project file. + +## Options + +- `-f|--force` + + If a `tye.yaml` file is already present, overwrites it with a newly scaffolded `tye.yaml`. + +## Examples + +- Scaffold a `tye.yaml` in the current directory: + + ```text + tye init + ``` + +- Scaffold a `tye.yaml` from a path to a directory: + + ```text + tye init PATH_TO_DIRECTORY + ``` + +- Scaffold a `tye.yaml` from a project file (*.csproj, *.fsproj): + + ```text + tye init project.csproj + ``` + +- Scaffold a `tye.yaml` from a solution file (sln): + + ```text + tye init app.sln + ``` diff --git a/docs/commandline/tye-run.md b/docs/commandline/tye-run.md new file mode 100644 index 00000000..07d46ad4 --- /dev/null +++ b/docs/commandline/tye-run.md @@ -0,0 +1,72 @@ +# tye run + +## Name + +`tye run` - Runs the application. + +## Synopsis + +```text +tye run [-?|-h|--help] [--no-build] [--port ] [--dtrace] [--debug][-f|--force] [] +``` + +## Description + +The `tye run` command will run an application locally. `tye run` by default will: + +- Start all services/projects in the application. +- Start a dashboard at to view all services running in the application. + +## Arguments + +`PATH` + +The path to either a file or directory to run `tye run` on. Can either be a yaml, sln, or project file. + +If a directory path is specified, `tye run` will default to using these files, in the following order: + +- `tye.yaml` +- `*.sln` +- `*.csproj/*.fsproj` + +## Options + +- `--no-build` + + Does not build projects before running. + +- `--port ` + + The port to run the dashboard on. Defaults to port 8000 if not specified. + +- `--logs` + + Write structured application logs to the specified log providers. Supported providers are console, elastic (Elasticsearch), ai (ApplicationInsights), seq. + +- `--dtrace ` + + Write distributed traces to the specified providers. Supported providers are zipkin. + +- `--debug` + + Waits for debugger attach in all services. + +## Examples + +- Run an application in the current directory: + + ```text + tye run + ``` + +- Run an application where the dashboard is hosted on another port: + + ```text + tye run --port 5050 + ``` + +- Run an application and wait for all projects to debug attach: + + ```text + tye run --debug + ``` diff --git a/docs/commandline/tye.md b/docs/commandline/tye.md new file mode 100644 index 00000000..19a6deeb --- /dev/null +++ b/docs/commandline/tye.md @@ -0,0 +1,34 @@ +# tye command + +## Name + +`tye` - The base tye command. + +## Synopsis + +To get more information about the available commands: + +```text + +tye [-?|-h|--help] [--version] +``` + +## Description + +The `tye` command provides commands for working with a multi-project application. + +For example, [`tye run`](tye-run.md) runs an application. Each command defines its own options and arguments. All commands support the `--help` option for printing out brief documentation about how to use the command. + +## Options + +- **`--version`** + + Prints out the version of tye in use. + +## tye commands + +| Command | Function | +| --------------------------------------------- | ------------------------------------------------------------------- | +| [tye init](tye-init.md) | Scaffolds a tye.yaml file representing the application. | +| [tye run](tye-run.md) | Runs an application. | +| [tye deploy](tye-deploy.md) | Deploys an application. | diff --git a/docs/frontend_backend_deploy.md b/docs/frontend_backend_deploy.md index 4e16dde0..0ded8201 100644 --- a/docs/frontend_backend_deploy.md +++ b/docs/frontend_backend_deploy.md @@ -2,7 +2,7 @@ This tutorial assumes that you have completed the [Frontend Backend Run Sample](frontend_backend_run.md) -> :bulb: `tye` will use your current credentials for pushing Docker images and accessing kubernetes clusters. If you have configured kubectl with a context already, that's what `tye deploy` is going to use! +> :bulb: `tye` will use your current credentials for pushing Docker images and accessing kubernetes clusters. If you have configured kubectl with a context already, that's what [`tye deploy`](commandline/tye-deploy.md) is going to use! Before we deploy, make sure you have the following ready... diff --git a/docs/frontend_backend_run.md b/docs/frontend_backend_run.md index f8b75d90..4bd805f0 100644 --- a/docs/frontend_backend_run.md +++ b/docs/frontend_backend_run.md @@ -1,6 +1,6 @@ # Frontend Backend sample with tye run -This tutorial will demonstrate how to use `tye run` to run a multi-project application. If you haven't so already, follow the [Getting Started Instructions](getting_started.md) to install tye. +This tutorial will demonstrate how to use [`tye run`](commandline/tye-run.md) to run a multi-project application. If you haven't so already, follow the [Getting Started Instructions](getting_started.md) to install tye. ## Running a single application with tye run @@ -210,4 +210,4 @@ Now that we have two applications running, let's make them communicate. By defau ## Next Steps -Now that you are able to run a multi-project application with `tye run`, move on to the [Frontend Backend Deploy Sample](frontend_backed_deploy.md) to learn how to deploy this application to Kubernetes. +Now that you are able to run a multi-project application with [`tye run`](commandline/tye-run.md), move on to the [Frontend Backend Deploy Sample](frontend_backed_deploy.md) to learn how to deploy this application to Kubernetes.