Skip to content

Commit d7c9559

Browse files
chmeliikchmeliik
authored
Improve development documentation (#2699)
* Docs: preview.env instructions The instructions present as comments in the preview.env file are not sufficient for a new member trying to set up their development environment for the first time. Add a section in the documentation that explains what needs to be set in preview.env and how to set up the prerequisites. Signed-off-by: Adam Cmiel <[email protected]> * Docs: how to verify that your dev cluster works Signed-off-by: Adam Cmiel <[email protected]> * Docs: how to test code changes Signed-off-by: Adam Cmiel <[email protected]> * preview.env: link the relevant documentation Signed-off-by: Adam Cmiel <[email protected]> * preview.env: mention not to set the PaC secret Signed-off-by: Adam Cmiel <[email protected]> * Document how to render the docs for your fork Signed-off-by: Adam Cmiel <[email protected]> --------- Signed-off-by: Adam Cmiel <[email protected]>
1 parent 96c2554 commit d7c9559

File tree

3 files changed

+210
-2
lines changed

3 files changed

+210
-2
lines changed

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
For the full documentation click [here](https://redhat-appstudio.github.io/infra-deployments/docs/introduction/about.html)
44

5+
When working on documentation updates, you may want to enable GitHub pages for your forked repository,
6+
see the [GitHub docs: Publishing from a branch](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch).
7+
The site will be available at `https://<username>.github.io/<repository>` (`https://<username>.github.io/infra-deployments` if you didn't rename yor fork).
8+
59
This repository is an initial set of Argo-CD-based deployments of StoneSoup components to a cluster, plus a script to bootstrap Argo CD onto that cluster (to drive these Argo-CD-based deployments, via OpenShift GitOps).
610

711
This repository is structured as a GitOps monorepo (e.g. the repository contains the K8s resources for *multiple* applications), using [Kustomize](https://kustomize.io/).

‎docs/development/deployment.md

+202-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@ Preview mode works in a feature branch, apply script which creates new preview b
3939

4040
Steps:
4141

42-
1. Copy `hack/preview-template.env` to `hack/preview.env` and update new file based on instructions. File `hack/preview.env` should never be included in commit.
42+
1. Copy `hack/preview-template.env` to `hack/preview.env` and update new file based on [instructions](#previewenv-instructions).
43+
File `hack/preview.env` should never be included in commit.
4344

4445
2. Work on your changes in a feature branch
4546

@@ -60,6 +61,206 @@ If you want to reset your environment you can run the `hack/util-update-app-of-a
6061

6162
Note running these scripts in a clone repo will have no effect as the repo will remain `https://github.com/redhat-appstudio/infra-deployments.git`
6263

64+
### preview.env instructions
65+
66+
I want a development deployment of StoneSoup where I can:
67+
68+
* Run simple builds
69+
* Onboard a repository to Pipelines as Code
70+
71+
What environment variables do I need to set in `preview.env` before I run the preview script?
72+
How to set up all the prerequisites?
73+
74+
| Variable | How to set up |
75+
| ----------------------------- | --------------------------------- |
76+
| `MY_GIT_FORK_REMOTE` | [Fork the repo](#fork-the-repo) |
77+
| `MY_GITHUB_ORG` | [GitHub setup](#github-setup) |
78+
| `MY_GITHUB_TOKEN` | [GitHub setup](#github-setup) |
79+
| `IMAGE_CONTROLLER_QUAY_ORG` | [Quay setup](#quay-setup) |
80+
| `IMAGE_CONTROLLER_QUAY_TOKEN` | [Quay setup](#quay-setup) |
81+
| `PAC_GITHUB_APP_PRIVATE_KEY` | [PaC setup](#pac-setup) |
82+
| `PAC_GITHUB_APP_ID` | [PaC setup](#pac-setup) |
83+
84+
#### Fork the repo
85+
86+
If you haven't done so yet, fork <https://github.com/redhat-appstudio/infra-deployments> and clone
87+
it locally. Copy [`hack/preview-template.env`][preview-template.env] to `hack/preview.env` - that's
88+
where you want to set all the environment variables.
89+
90+
The first one is `MY_GIT_FORK_REMOTE` - the name of the git remote which points to your fork.
91+
92+
```shell
93+
$ git remote -v
94+
origin [email protected]:<gh_username>/infra-deployments.git (fetch)
95+
origin [email protected]:<gh_username>/infra-deployments.git (push)
96+
upstream https://github.com/redhat-appstudio/infra-deployments.git (fetch)
97+
upstream https://github.com/redhat-appstudio/infra-deployments.git (push)
98+
```
99+
100+
Set the name of the git remote in `preview.env`:
101+
102+
```shell
103+
export MY_GIT_FORK_REMOTE=origin
104+
```
105+
106+
#### GitHub setup
107+
108+
Create a new organization, see the [GitHub docs: Creating a new organization from scratch][github-create-org].
109+
This is the organization where you will later install the Pipelines as Code application. When testing
110+
the PaC integration features of StoneSoup, you will need to use repositories from this organization
111+
(or fork existing repositories into this org).
112+
113+
Copy the organization name to `preview.env`. For example:
114+
115+
```shell
116+
export MY_GITHUB_ORG=<gh_username>-stonesoup
117+
```
118+
119+
Next, you will need an access token. See the [GitHub docs: Creating a personal access token][github-get-access-token].
120+
The token needs all the `repo` permissions and the `delete_repo` permission.
121+
122+
Copy the token value to `preview.env`:
123+
124+
```shell
125+
export MY_GITHUB_TOKEN=ghp_***
126+
```
127+
128+
#### Quay setup
129+
130+
Create a new [Quay.io](https://quay.io) organization. If you need a new email address for the organization,
131+
you can use the `+` trick - e.g. `<gmail_username>[email protected]`.
132+
133+
Copy the organization name to `preview.env`. For example:
134+
135+
```shell
136+
export IMAGE_CONTROLLER_QUAY_ORG=<quay_username>-stonesoup
137+
```
138+
139+
Next, you need to generate an access token for your Quay.io organization. See the instructions for
140+
`IMAGE_CONTROLLER_QUAY_TOKEN` in [preview.env][preview-template.env]. Once you have created the token,
141+
copy its value to `preview.env`:
142+
143+
```shell
144+
export IMAGE_CONTROLLER_QUAY_TOKEN=***
145+
```
146+
147+
#### PaC setup
148+
149+
Follow the [Pipelines as Code: Setup Manually][pac-setup-manual] instructions to create the GitHub application.
150+
You can create the application in your organization settings (<https://github.com/organizations/MY_STONESOUP_ORG/settings/apps>)
151+
or your personal settings (<https://github.com/settings/apps>). If you create the app under your organization,
152+
you can allow it `Only on this account`, otherwise you will have to allow `Any account`.
153+
154+
Compared to the Pipelines as Code documentation, you will want to set these fields differently:
155+
156+
* **GitHub Application Name**: use a unique name, e.g. `<gh_username>-stonesoup PaC`
157+
* **Webhook URL**: use a dummy url, e.g. <https://example.org>. The `preview.sh` script will fix the
158+
webhook url automatically.
159+
* **Webhook secret**: leave it empty, the `preview.sh` script will set the secret automatically.
160+
161+
Once you have created the GitHub app, copy its App ID to `preview.env`:
162+
163+
```shell
164+
export PAC_GITHUB_APP_ID=<number>
165+
```
166+
167+
Generate a private key for the application (in the GitHub UI; refer to the Pipelines as Code docs linked
168+
above). Encode the private key as base64 and copy it to `preview.env`:
169+
170+
```shell
171+
base64 --wrap=0 <path to downloaded key>
172+
```
173+
174+
```shell
175+
export PAC_GITHUB_APP_PRIVATE_KEY=<output of the command above>
176+
```
177+
178+
Finally, install the application for your organization. See the [GitHub docs: Installing your own
179+
GitHub App][github-install-app]. Select `All repositories` when installing to make sure it will have
180+
access to all the repos you're going to create/fork into your org in the future.
181+
182+
### Verifying your setup
183+
184+
**Simple build:**
185+
186+
* Fork <https://github.com/devfile-samples/devfile-sample-python-basic> into your GitHub organization.
187+
* Run `hack/build/build-via-appstudio.sh https://github.com/MY_STONESOUP_ORG/devfile-sample-python-basic`
188+
189+
The script will create a test application and a component for you:
190+
191+
```shell
192+
$ oc get application
193+
NAME AGE STATUS REASON
194+
test-application 74s True OK
195+
196+
$ oc get component
197+
NAME AGE STATUS REASON TYPE
198+
devfile-sample-python-basic 86s True OK Created
199+
```
200+
201+
Build-service should start a pipeline for your new component almost immediately:
202+
203+
```shell
204+
$ tkn pipelinerun list
205+
NAME STARTED DURATION STATUS
206+
devfile-sample-python-basic-jpg29 2 minutes ago --- Running
207+
```
208+
209+
You can also see the PipelineRun in the OpenShift console in your cluster.
210+
211+
**Pipelines as Code onboarding:**
212+
213+
```shell
214+
$ oc annotate component devfile-sample-python-basic build.appstudio.openshift.io/request=configure-pac
215+
component.appstudio.redhat.com/devfile-sample-python-basic annotated
216+
```
217+
218+
Build-service should create a new pull request in your forked devfile-sample-python-basic repository.
219+
220+
If your cluster is accessible on the public internet, commenting `/ok-to-test` on the pull request
221+
will trigger the on-pull-request PipelineRun. Merging the pull request will trigger the on-push PipelineRun.
222+
If your cluster is hidden behind a VPN, this won't work.
223+
224+
### Testing code changes
225+
226+
#### Deploying your versions of operators
227+
228+
First, you will need to build the container image (typically with `make docker-build` in the operator
229+
repository) and push the image to a publicly accessible container repository. Then, set the image
230+
reference for the corresponding service in `preview.env`. For example, to override the build-service
231+
image, set:
232+
233+
```shell
234+
export BUILD_SERVICE_IMAGE_REPO=quay.io/<quay_username>/build-service
235+
export BUILD_SERVICE_IMAGE_TAG=my-test-v1
236+
```
237+
238+
Then, run the `hack/preview.sh` script, which will deploy the overriden image.
239+
240+
To update the operator after you've made some more changes, build a new image and push it to the same
241+
repository with a new tag. Set the new tag in `preview.env` and run `hack/preview.sh` again.
242+
243+
#### Deploying your versions of CRDs
244+
245+
Find the reference to the upstream repository where your CRDs are located. For example, for build-service,
246+
it's in [components/build-service/base/kustomization.yaml][build-service-kustomization]:
247+
248+
```yaml
249+
resources:
250+
- allow-argocd-to-manage.yaml
251+
- https://github.com/redhat-appstudio/build-service/config/default?ref=99cebd0a67a6b25b8ccffb76522861f526c762de
252+
```
253+
254+
Replace this reference with a reference to your fork and the commit you would like to test. Create
255+
a new branch, commit the changes and run `hack/preview.sh`.
256+
63257
## Optional: OpenShift Local Post-Bootstrap Configuration
64258

65259
Even with 6 CPU cores, you will need to reduce the CPU resource requests for each StoneSoup application. Either run `./hack/reduce-gitops-cpu-requests.sh` which will set resources.requests.cpu values to 50m or use `kubectl edit argocd/openshift-gitops -n openshift-gitops` to reduce the values to some other value. More details are in the FAQ below.
260+
261+
[preview-template.env]: https://github.com/redhat-appstudio/infra-deployments/blob/main/hack/preview-template.env
262+
[github-create-org]: https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch
263+
[github-get-access-token]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic
264+
[github-install-app]: https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app
265+
[pac-setup-manual]: https://pipelinesascode.com/docs/install/github_apps/#setup-manually
266+
[build-service-kustomization]: https://github.com/redhat-appstudio/infra-deployments/blob/main/components/build-service/base/kustomization.yaml

‎hack/preview-template.env

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1+
# See https://redhat-appstudio.github.io/infra-deployments/docs/development/deployment.html#setting-preview-mode
2+
13
# Required
4+
25
## Git remote repo name where is your fork where to push the changes.
36
## List of remotes -> git remote -v
47
## Example value: origin
@@ -100,7 +103,7 @@ export DOCKER_IO_AUTH=""
100103
### pipelines-as-code-secret is created by preview.sh
101104
export PAC_GITHUB_APP_PRIVATE_KEY= # Base64 encoded private key of the GitHub APP
102105
export PAC_GITHUB_APP_ID= # Application ID
103-
export PAC_GITHUB_APP_WEBHOOK_SECRET= # Webhook secret of the GitHub APP
106+
export PAC_GITHUB_APP_WEBHOOK_SECRET= # Webhook secret of the GitHub APP, leave this empty to let preview.sh set it automatically
104107

105108
# GitHub webhook integration (alternative to the GitHub PaC application)
106109
# See https://pipelinesascode.com/docs/install/github_webhook/#setup-git-repository for the required token permissions

0 commit comments

Comments
 (0)