From 490f8d775e656f9d713e3cc5642d71130ed56d4c Mon Sep 17 00:00:00 2001 From: nghialv Date: Wed, 27 Apr 2022 16:49:38 +0900 Subject: [PATCH 1/5] Refactor docs for contributor --- .../control-plane-development.md | 42 ------------------- .../contribution-guidelines/development.md | 42 +++++++++++++++++-- .../piped-development.md | 25 ----------- web/README.md | 2 +- 4 files changed, 40 insertions(+), 71 deletions(-) delete mode 100644 docs/content/en/docs-dev/contribution-guidelines/control-plane-development.md delete mode 100644 docs/content/en/docs-dev/contribution-guidelines/piped-development.md diff --git a/docs/content/en/docs-dev/contribution-guidelines/control-plane-development.md b/docs/content/en/docs-dev/contribution-guidelines/control-plane-development.md deleted file mode 100644 index 6f54b18ef0..0000000000 --- a/docs/content/en/docs-dev/contribution-guidelines/control-plane-development.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Control Plane development" -linkTitle: "Control Plane development" -weight: 5 -description: > - This page describes where to find Control Plane source code and how to run it locally for debugging. ---- - -## Source code structure - -- [cmd/pipecd](https://github.com/pipe-cd/pipecd/tree/master/cmd/pipecd): entrypoint for binary of Control Plane server. -- [pkg/app/server](https://github.com/pipe-cd/pipecd/tree/master/pkg/app/server): contains source code for Control Plane api. -- [web](https://github.com/pipe-cd/pipecd/tree/master/web): contains source code for the web console. -- [pkg](https://github.com/pipe-cd/pipecd/tree/master/pkg): contains shared source code for all components of both `Piped` and `Control Plane`. - -## How to run Control Plane locally - -### Prerequisites -- Installing [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) - -### Start running a Kubernetes cluster - -``` console -make kind-up -``` - -Once it is no longer used, run `make kind-down` to delete it. - -### Installing Control Plane into the local cluster - -``` console -make run/pipecd -``` - -Once all components are running up, use `kubectl port-forward` to expose the installed Control Plane on your localhost: - -``` console -kubectl -n pipecd port-forward svc/pipecd 8080 -``` - -Point your web browser to [http://localhost:8080](http://localhost:8080) to login with the configured static admin account: project = `quickstart`, -username = `hello-pipecd`, password = `hello-pipecd`. diff --git a/docs/content/en/docs-dev/contribution-guidelines/development.md b/docs/content/en/docs-dev/contribution-guidelines/development.md index ba0871ee02..5f96c46f1e 100644 --- a/docs/content/en/docs-dev/contribution-guidelines/development.md +++ b/docs/content/en/docs-dev/contribution-guidelines/development.md @@ -10,6 +10,7 @@ description: > - [Go 1.17](https://go.dev/) - [Docker Decktop](https://www.docker.com/products/docker-desktop/) +- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) (If you want to run Control Plane locally) ## Repositories - [pipecd](https://github.com/pipe-cd/pipecd): contains all source code and documentation of PipeCD project. @@ -24,15 +25,50 @@ description: > - `make test/web`: runs all unit tests of web. - `make test/integration`: runs integration tests. -- `make run/pipecd`: runs Control Plane locally. -- `make run/piped`: runs Piped Agent locally. -- `make run/web`: runs frontend locally. - `make run/site`: runs PipeCD site locally (requires [hugo](https://github.com/gohugoio/hugo) with `_extended` version `0.92.1` or later to be installed). - `make gen/code`: generate Go and Typescript code from protos and mock configs. You need to run it if you modified any proto or mock definition files. For the full list of available commands, please see the Makefile at the root of repository. +## How to run Piped agent locally + +1. Prepare the piped configuration file `piped-config.yaml` + +2. Ensure that your `kube-context` is connecting to the right kubernetes cluster + +2. Run the following command to start running `piped` + + ``` console + make run/piped CONFIG_FILE=piped-config.yaml + ``` + +## How to run Control Plane locally + +1. Start running a Kubernetes cluster + + ``` console + make kind-up + ``` + + Once it is no longer used, run `make kind-down` to delete it. + +2. Installing Control Plane into the local cluster + + ``` console + make run/pipecd + ``` + + Once all components are running up, use `kubectl port-forward` to expose the installed Control Plane on your localhost: + + ``` console + kubectl -n pipecd port-forward svc/pipecd 8080 + ``` + +3. Accessing web console of the local Control Plane + + Point your web browser to [http://localhost:8080](http://localhost:8080) to login with the configured static admin account: project = `quickstart`, username = `hello-pipecd`, password = `hello-pipecd`. + ## Docs and workaround with docs PipeCD official site contains multiple versions of documentation, all placed under the `/docs/content/en` directory, which are: diff --git a/docs/content/en/docs-dev/contribution-guidelines/piped-development.md b/docs/content/en/docs-dev/contribution-guidelines/piped-development.md deleted file mode 100644 index b1417fc81e..0000000000 --- a/docs/content/en/docs-dev/contribution-guidelines/piped-development.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Piped development" -linkTitle: "Piped development" -weight: 4 -description: > - This page describes where to find piped source code and how to run it locally for debugging. ---- - -## Source code structure - -- [pkg/app/piped](https://github.com/pipe-cd/pipecd/tree/master/pkg/app/piped): contains source code for only `piped`. -- [cmd/piped](https://github.com/pipe-cd/pipecd/tree/master/cmd/piped): entrypoint for `piped` binary. -- [pkg](https://github.com/pipe-cd/pipecd/tree/master/pkg): contains shared source code for all components of both `Piped` and `Control Plane`. - -## How to run it locally - -1. Prepare the piped configuration file `piped-config.yaml` - -2. Ensure that your `kube-context` is connecting to the right kubernetes cluster - -2. Run the following command to start running `piped` - -``` console -make run/piped CONFIG_FILE=piped-config.yaml -``` diff --git a/web/README.md b/web/README.md index 7c27f9f3fb..f4eddae060 100644 --- a/web/README.md +++ b/web/README.md @@ -32,7 +32,7 @@ src We use `msw` for mocking API, so you can see UI without running API server. ```bash -make web-dev +make run/web ``` The app will be available at http://localhost:9090. From 5c129c96c1f8a948495792bc8f8403ec7e1877c3 Mon Sep 17 00:00:00 2001 From: Le Van Nghia Date: Fri, 6 May 2022 10:33:56 +0900 Subject: [PATCH 2/5] Update docs/content/en/docs-dev/contribution-guidelines/development.md Co-authored-by: Khanh Tran <32532742+khanhtc1202@users.noreply.github.com> --- docs/content/en/docs-dev/contribution-guidelines/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs-dev/contribution-guidelines/development.md b/docs/content/en/docs-dev/contribution-guidelines/development.md index 5f96c46f1e..de2d606d0d 100644 --- a/docs/content/en/docs-dev/contribution-guidelines/development.md +++ b/docs/content/en/docs-dev/contribution-guidelines/development.md @@ -53,7 +53,7 @@ For the full list of available commands, please see the Makefile at the root of Once it is no longer used, run `make kind-down` to delete it. -2. Installing Control Plane into the local cluster +2. Install Control Plane into the local cluster ``` console make run/pipecd From a4653e2528627364fdbf93f0a998d8fa2a872c5c Mon Sep 17 00:00:00 2001 From: Le Van Nghia Date: Fri, 6 May 2022 10:34:03 +0900 Subject: [PATCH 3/5] Update docs/content/en/docs-dev/contribution-guidelines/development.md Co-authored-by: Khanh Tran <32532742+khanhtc1202@users.noreply.github.com> --- docs/content/en/docs-dev/contribution-guidelines/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs-dev/contribution-guidelines/development.md b/docs/content/en/docs-dev/contribution-guidelines/development.md index de2d606d0d..920c235321 100644 --- a/docs/content/en/docs-dev/contribution-guidelines/development.md +++ b/docs/content/en/docs-dev/contribution-guidelines/development.md @@ -65,7 +65,7 @@ For the full list of available commands, please see the Makefile at the root of kubectl -n pipecd port-forward svc/pipecd 8080 ``` -3. Accessing web console of the local Control Plane +3. Access to the local Control Plane web console Point your web browser to [http://localhost:8080](http://localhost:8080) to login with the configured static admin account: project = `quickstart`, username = `hello-pipecd`, password = `hello-pipecd`. From 3edd93463b575e1894e473883c12f87fc85be51c Mon Sep 17 00:00:00 2001 From: Le Van Nghia Date: Fri, 6 May 2022 10:34:20 +0900 Subject: [PATCH 4/5] Update docs/content/en/docs-dev/contribution-guidelines/development.md Co-authored-by: Khanh Tran <32532742+khanhtc1202@users.noreply.github.com> --- docs/content/en/docs-dev/contribution-guidelines/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs-dev/contribution-guidelines/development.md b/docs/content/en/docs-dev/contribution-guidelines/development.md index 920c235321..33215ddb30 100644 --- a/docs/content/en/docs-dev/contribution-guidelines/development.md +++ b/docs/content/en/docs-dev/contribution-guidelines/development.md @@ -37,7 +37,7 @@ For the full list of available commands, please see the Makefile at the root of 2. Ensure that your `kube-context` is connecting to the right kubernetes cluster -2. Run the following command to start running `piped` +3. Run the following command to start running `piped` ``` console make run/piped CONFIG_FILE=piped-config.yaml From e564386353377e3479c014e8ca69c2eafa061a8b Mon Sep 17 00:00:00 2001 From: nghialv Date: Fri, 6 May 2022 10:37:23 +0900 Subject: [PATCH 5/5] Reorder the sections --- .../contribution-guidelines/development.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/content/en/docs-dev/contribution-guidelines/development.md b/docs/content/en/docs-dev/contribution-guidelines/development.md index 33215ddb30..4636198ac1 100644 --- a/docs/content/en/docs-dev/contribution-guidelines/development.md +++ b/docs/content/en/docs-dev/contribution-guidelines/development.md @@ -31,18 +31,6 @@ description: > For the full list of available commands, please see the Makefile at the root of repository. -## How to run Piped agent locally - -1. Prepare the piped configuration file `piped-config.yaml` - -2. Ensure that your `kube-context` is connecting to the right kubernetes cluster - -3. Run the following command to start running `piped` - - ``` console - make run/piped CONFIG_FILE=piped-config.yaml - ``` - ## How to run Control Plane locally 1. Start running a Kubernetes cluster @@ -69,6 +57,18 @@ For the full list of available commands, please see the Makefile at the root of Point your web browser to [http://localhost:8080](http://localhost:8080) to login with the configured static admin account: project = `quickstart`, username = `hello-pipecd`, password = `hello-pipecd`. +## How to run Piped agent locally + +1. Prepare the piped configuration file `piped-config.yaml` + +2. Ensure that your `kube-context` is connecting to the right kubernetes cluster + +3. Run the following command to start running `piped` + + ``` console + make run/piped CONFIG_FILE=piped-config.yaml + ``` + ## Docs and workaround with docs PipeCD official site contains multiple versions of documentation, all placed under the `/docs/content/en` directory, which are: