Skip to content
This repository was archived by the owner on Nov 5, 2024. It is now read-only.

Commit f2dd9ba

Browse files
gtrivedi88gtrivedi88
authored
Merge pull request #91 from jseseCCS/HACDOCS-423
HACDOCS-423: Adding new Import code content to upstream docs
2 parents 11d01af + 95a10d5 commit f2dd9ba

File tree

2 files changed

+222
-1
lines changed

2 files changed

+222
-1
lines changed

‎docs/modules/ROOT/nav-how-to-guides.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
* xref:how-to-guides/how-to-guide-landing-page.adoc[How-to guides]
2+
** xref:how-to-guides/Import-code/proc_importing_code.adoc[Importing and configuring code]
23
** xref:how-to-guides/proc_upgrade_build_pipeline.adoc[Upgrading the build pipeline]
34
** Testing your application
45
*** xref:how-to-guides/testing_applications/con_test-overview.adoc[Overview of {ProductName} Test components]
@@ -20,7 +21,7 @@ Commenting these out per HACDOCS-425 and -414
2021
////
2122
2223
////
23-
I'm commenting out this xref for now because Burr said this page is currently unsupported. --Christian (csears@redhat.com), 2/16/2023
24+
Commenting out this xref for now because Burr said this page is currently unsupported. --Christian (csears@redhat.com), 2/16/2023
2425
** xref:cli/proc_release_application.adoc[Releasing an application]
2526
** xref:how-to-guides/proc_managed_services_onboarding.adoc[CLI: Managed services team onboarding]
2627
////

‎docs/modules/ROOT/pages/how-to-guides/Import-code/proc_importing_code.adoc‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
//[id="proc_importing_code_{context}"]
2+
3+
= Importing and configuring code
4+
5+
[role="_abstract"]
6+
After you click **Create an application**, the **Grab some code** page opens. From here, choose one of the following source code options to begin building your application:
7+
8+
* **Bring in your own code**
9+
* **Start with a sample**
10+
11+
== Using a code sample
12+
13+
. Optional: In the code sample **Search** field, begin typing the name of the code you want to work with. If {ProductName} has code samples in that language stack, the code sample results filter accordingly.
14+
. When you see a language stack or framework that you want to work with, click **Import sample**.
15+
* Optional: If you click **Open Git repository**, a new tab opens to the GitHub repository for the code framework you chose.
16+
* When you click **Import sample**, {ProductName} creates and deploys a new application with the sample code you chose. Check out the open **Overview** tab to monitor your continuous integration/continuous deployment (CI/CD) activity.
17+
18+
[NOTE]
19+
====
20+
When you create an application from a code sample, {ProductName} names your application for you.
21+
====
22+
23+
== Importing code from your GitHub repository
24+
25+
To use your own code to build your application, complete the following steps:
26+
27+
. Enter the link to your repository in the **Git repository URL** field. Note that this should be a public repository. {ProductName} verifies your URL right away. You don’t even have to press **Enter**.
28+
. Optional: Add a **Git reference** to point to code in a specific branch, tag, or commit that you want to use to build your application.
29+
. Optional: Indicate a **Context directory** to specify the subdirectory for the source code you want to use.
30+
31+
[NOTE]
32+
====
33+
Make sure this path is correct. You might get an error if your build context folder is your root directory but your Dockerfile is in a subdirectory of that folder. If you have a Dockerfile, you can check its path in the **Build & deploy configuration** section.
34+
====
35+
[start=4]
36+
. Click **Import code**.
37+
38+
[IMPORTANT]
39+
====
40+
If you want to use a custom pipeline build, or to grant access to and install the {ProductName} GitHub app on the repository you indicated, you must have the necessary GitHub permissions. If you don't own that repository, or if you don't have the necessary GitHub permissions, you must fork that repository and then specify the new fork URL to add a new component.
41+
====
42+
43+
////
44+
[TIP]
45+
====
46+
If {ProductName} can’t access your Git repository, see <<Granting App Studio access to your Git repository>> for help.
47+
====
48+
////
49+
50+
{ProductName} scans and analyzes your Git repository to determine how many components to add to your application and which runtime to use. The types of files in your repository, and also your Git directory file hierarchy, determine the number and type of components to add. For example, {ProductName} looks for devfiles and Dockerfiles, and also language-specific build configuration files like pom.xml for Java or package.json for Node.js.
51+
52+
{ProductName} can build applications that are written in the following language stacks and frameworks:
53+
54+
[cols=2*,options="header"]
55+
|===
56+
|Language
57+
|Framework
58+
59+
|Java
60+
|Spring Boot, Quarkus
61+
62+
|JavaScript
63+
|Node.js, Express
64+
65+
|Python
66+
|Flask
67+
68+
|Go
69+
|N/A
70+
|===
71+
72+
////
73+
From JSese: May 15, 2023, Commenting out per Matt Reid and Christian V. Support for private repos is post-Summit.
74+
[discrete]
75+
== Granting App Studio access to your Git repository
76+
77+
If {ProductName} can’t access your Git repository, the following message displays: “We can’t access your repository, probably because it’s either private or the URL is incorrect.” If your repository is private, choose one of the following two ways to allow {ProductName} to interact with your repository:
78+
79+
[discrete]
80+
=== Granting App Studio access to your Git repository through GitHub OAuth
81+
82+
. Under **Authorization**, click **Sign in**. **GitHub Authorize OAuth** opens in a new tab.
83+
. Click **Authorize _redhat-appstudio_**.
84+
85+
[discrete]
86+
=== Granting App Studio access to your Git repository with a token
87+
88+
. Under **Authorization**, click **Use a token instead**. The **Authenticate with API token** modal opens.
89+
. Enter your **Username**.
90+
. Enter an **API token**.
91+
. Click **Connect**.
92+
////
93+
94+
.What's next
95+
**Configure your components for deployment** opens. From here, configure your components before you deploy them. You can also review or change any values that {ProductName} populated for you. When you're finished here, you're one click away from creating your application.
96+
97+
//[id="proc_reviewing_configging_components_{context}"]
98+
99+
== Reviewing and configuring components
100+
101+
[role="_abstract"]
102+
If you imported your own code, from the **Review and configure for deployment** view, make sure to define, review, or change your application and component settings before you finish importing. You can rename a component here, too.
103+
104+
. Make sure that **Component name** is correct. Click the GitHub link under this field if you want to check your repository URL.
105+
. Confirm that {ProductName} detected the right **Runtime**. If so, you should notice that the suggested deployment options are appropriate. If you want to change your runtime, expand the menu next to your runtime name and make a selection.
106+
107+
[IMPORTANT]
108+
====
109+
If you change the runtime, your component builds and deploys using the runtime devfile instead of the repository devfile or Dockerfile.
110+
====
111+
112+
In the **Build & deploy configuration** section, look over these fields:
113+
114+
[start=3]
115+
. **Target port**: Is it correct? If not, click in the field to modify it.
116+
. **Dockerfile**: If you specified **Dockerfile** as your runtime, make sure {ProductName} detected the right one. Click in the field if you need to modify it.
117+
//Don't worry! {ProductName} hides this field if you chose a different runtime.
118+
. **Default build pipeline**: To specify how to trigger rebuilds, toggle to choose either the default build pipeline or a custom one.
119+
.. **Default build pipeline**: This runs faster because it makes only critical image checks. Consider starting here to make sure {ProductName} can successfully build and deploy your component.
120+
.. **Custom build pipeline**: This is triggered when you make commits to your source code repository. This pipeline runs more checks and security scans than the default pipeline, but it takes a bit more time because it's more thorough. **NOTE:** To use a custom pipeline, you must be the owner of your repository so that you can authorize the installation of our application in your GitHub instance and then grant the app access to your repository. If someone else owns your repository, fork it, then go back to the **Add components** page and start again.
121+
. **CPU**, **Memory**, and **Instances**: Choose how many of each of these you want for your application, and in what unit, depending on your deployment requirements. **Instances** refers to the number of instances of your system image.
122+
. In the **Environment variables** section, enter a variable name and value to customize how {ProductName} deploys your application.
123+
124+
When you’re satisfied with your component configuration settings, click **Create application**.
125+
126+
[NOTE]
127+
====
128+
After you create your application, you can adjust your configuration settings anytime you want from the **Application** view.
129+
====
130+
131+
== Resolving issues with importing code
132+
133+
[role="_abstract"]
134+
When you import code, {ProductName} analyzes your repository to determine the right runtime to use to build and deploy your application. In some cases, however, {ProductName} is unable to find the right runtime, and this can cause your code import to fail. These are the most common causes of issues with importing code to {ProductName}:
135+
136+
* **Your repository contains a Dockerfile in an unexpected directory.**
137+
+
138+
If {ProductName} finds a Dockerfile in your repository, it determines that a Dockerfile runtime is the most suitable for building and deploying you application. However, if the Dockerfile is not saved in one of the following expected locations, an error in determining the right runtime for your components can occur:
139+
+
140+
[#expected Dockerfile locations]
141+
.Expected Dockerfile locations
142+
** Dockerfile
143+
** docker/Dockerfile
144+
** .docker/Dockerfile/build/Dockerfile
145+
** Containerfile
146+
** docker/Containerfile
147+
** .docker/Containerfile/build/Containerfile
148+
+
149+
**Solutions**
150+
+
151+
** On the **Review and configure for deployment** page, make sure **Runtime** is set to **Dockerfile**, then verify that you saved your Dockerfile in one of the expected directories.
152+
** In the **Build & deploy configuration** section, in the **Dockerfile** field, confirm that the file path is correct.
153+
+
154+
[TIP]
155+
====
156+
Test your Dockerfile in a local environment first to make sure it's valid.
157+
====
158+
159+
[#repository requirements]
160+
* **Your repository does not contain a Dockerfile or devfile.**
161+
+
162+
If your code import fails because your repository is missing either a Dockerfile or devfile, check one of the following readme files for guidance, depending on the runtime you want to build and deploy with. These readme files provide details like required ports, file locations, commands, and more.
163+
+
164+
**Solutions**
165+
+
166+
** https://github.com/devfile-samples/devfile-sample-go-basic.git[Go]
167+
** https://github.com/nodeshift-starters/devfile-sample.git[Node.js]
168+
** https://github.com/devfile-samples/devfile-sample-python-basic.git[Python]
169+
** https://github.com/devfile-samples/devfile-sample-code-with-quarkus.git[Quarkus]
170+
** https://github.com/devfile-samples/devfile-sample-java-springboot-basic.git[Spring Boot]
171+
172+
* **Your repository contains a devfile, a Dockerfile, and a Kubernetes YAML file.**
173+
+
174+
{ProductName} looks for a devfile to get custom instructions for building and deploying your application. If your devfile references both a Dockerfile and a Kubernetes YAML file, your code import could fail if those two resources are not accessible at the file locations your devfile points to.
175+
+
176+
**Solutions**
177+
+
178+
** Make sure that your `devfile.yaml` points to the correct directories for both your Dockerfile and your Kubernetes YAML file.
179+
** Make sure that neither of these resources is in a private repository that requires access authentication.
180+
** Make sure that your devfile is in one of these expected locations:
181+
+
182+
[#expected devfile locations]
183+
.Expected devfile locations
184+
*** devfile.yaml
185+
*** .devfile.yaml
186+
*** .devfile/devfile.yaml
187+
*** .devfile/.devfile.yaml
188+
189+
* **Your repository does not fit within the predefined {ProductName} supported runtime list.**
190+
+
191+
Some repositories require custom build or deployment instructions; for example, a deployment that includes a Kubernetes resource other than a YAML file.
192+
+
193+
**Solutions**
194+
+
195+
[#custom build and deployment instructions]
196+
** **Configure a custom build.** Include a Dockerfile that can build your application, then save it to one of the <<expected Dockerfile locations>>. **Note:** If your build is custom but your deployment is not, you do not have to include a `devfile.yaml` file in your repository.
197+
** **Configure a custom deployment.** Include the following files in your repository to provide {ProductName} with custom deployment instructions:
198+
*** A standard Kubernetes YAML file
199+
*** A custom-build Dockerfile
200+
*** A devfile that points to your Kubernetes YAML file and Dockerfile. **Note:** Make sure that your devfile is in one of the <<expected devfile locations>>.
201+
+
202+
[TIP]
203+
====
204+
For more information about devfile contents requirements, see the "What is outerloop?" section of link:https://devfile.io/docs/2.2.0/innerloop-vs-outerloop[Devfile.io: Innerloop versus outerloop].
205+
====
206+
207+
* **{ProductName} couldn't detect a port number.**
208+
+
209+
{ProductName} detects your application port number when it's looking for your repository components.
210+
+
211+
**Solution:** From the **Review and configure for deployment** view, in the **Build & deploy configuration** section, make sure your target port number is correct.
212+
213+
* **{ProductName} couldn't detect the appropriate runtime.**
214+
+
215+
**Solution:** Select a predefined runtime type from the **Review and configure for deployment** view. Make sure you meet all of the {ProductName} <<repository requirements>> for the runtime you select, or configure your own <<custom build and deployment instructions>>.
216+
217+
[role="_additional-resources"]
218+
.Additional resources
219+
For information about importing and configuring code to {ProductName} using the CLI, see link:https://redhat-appstudio.github.io/docs.stonesoup.io/Documentation/main/getting-started/getting_started_in_cli/#getting-started-in-the-cli[Getting started in the CLI
220+
].

0 commit comments

Comments
 (0)