golang buildspec example

examples/golang_webapp_example/README.md

@@ -0,0 +1,91 @@
+# Build Spec File Example using golang web application and Creating an executable file
+
+This is an example of a golang web application and creating an executable file. With the [OCI DevOps service](https://www.oracle.com/devops/devops-service/) and this project, you'll be able to build this application,store the executable file in [OCI Artifact Registry.](https://docs.oracle.com/en-us/iaas/artifacts/using/overview.htm)
+
+
+## Building the application locally
+
+### Download the repo
+The first step to get started is to download the repository to your local workspace
+
+```shell
+git clone git@github.com:dlcbld/BuildSpecSampleFiles.git
+cd examples/golang_webapp_example
+```
+
+### Install and run the application
+
+1. Install golang on your system: https://golang.org/
+2. Set the environment path variables
+    ```export PATH="/usr/local/go/bin:$PATH"```
+    ```export GOPATH="/usr/local/go"```
+    ```export PATH="$GOPATH/bin:$PATH"```
+3. Check that path is set properly by displaying version:
+    ```go version```
+4. Build the golang web application: 
+
+   ```go build -o golangWebApp main.go```
+5. Run the app:
+    ```./golangWebApp```
+
+## Building the application in OCI DevOps
+Now that you've seen you can locally build this app, let's try this out through OCI DevOps Build service.
+### Create External Connection to your Git repository 
+1. Create a [DevOps Project](https://docs.oracle.com/en-us/iaas/Content/devops/using/devops_projects.htm) or use and an existing project. 
+2. In your DevOps project, create an External Connection to your GitHub repository which holds your application.
+   - Create a Personal Access Token (PAT): https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
+   - In the OCI Console, Go to Identity & Security -> Vault and create a [Vault]( https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Concepts/keyoverview.htm) in compartment of your own choice.
+   - Create a Master Key that will be used to encrypt the PATs. 
+   - Select Secrets from under Resources and create a secret using PAT obtained from GitHub account.
+   - Make a note of the OCID of the secret.
+   - Now, go to the desired project and select External Connection from the resources.
+   - Select type as GitHub and provide OCID of the secret under Personal Access Token.
+   - Finally, allow Build Pipeline (dynamic group with DevOps Resources) to use a PAT secret by writing a policy in the root compartment as: ``` Allow dynamic-group dg-with-devops-resources to manage secret-family in tenancy```
+### Setup your Build Pipeline
+Create a new Build Pipeline to build, test and deliver artifacts from your GitHub Repository.
+### Managed Build stage
+In your Build Pipeline, first add a Managed Build stage
+1. The Build Spec File Path is the relative location in your repo of the build_spec.yaml . Leave the default, for this example.
+2. For the Primary Code Repository follow the below steps
+    - Select connection type as GitHub
+    - Select the external connection you created above
+    - Give the URL to the repo which contains your application.
+    - Select main branch.
+
+### Create a Artifact Registry repository
+Create a [Artifact Registry repository](https://docs.oracle.com/en-us/iaas/artifacts/using/manage-repos.htm#create-repo).
+
+### Create a DevOps Artifact for your artifact repository
+Create a DevOps Artifact to point to the Artifact Registry repository location you just created above. Enter the information for the Artifact location:
+1. Name: `myGoAppArtifact`
+<img src="create_artifact_go.png" />
+2. Type: General Artifact
+3. Artifact source: Artifact registry Repository
+    Select your Artifact Registry repository created in previous step.
+    <img src="select_artifact_go.png" />
+4. Artifact Location: Set custom location
+5. Path: `REGION/TENANCY-NAMESPACE/myGoWebAppArtifact`
+6. Replace parameters: Yes
+
+Required policies must be added in the root compartment for the Artifact Registry repository and DevOps Artifact resource.
+1. Provide access to Generic Artifactory to deliver artifacts : ```Allow dynamic-group dg-with-devops-resources to manage repos in tenancy```
+2. Provide access to read deploy artifacts in deliver artifact stage : ```Allow dynamic-group dg-with-devops-resources to manage devops-family in tenancy```
+
+### Add a Deliver Artifacts stage
+Let's add a **Deliver Artifacts** stage to your Build Pipeline to deliver the `golangWebApp` executable file to an OCI repository.
+The Deliver Artifacts stage **maps** the ouput Artifacts from the Managed Build stage with the version to deliver to a DevOps Artifact resource, and then to the OCI repository.
+Add a **Deliver Artifacts** stage to your Build Pipeline after the **Managed Build** stage. To configure this stage:
+1. In your Deliver Artifacts stage, choose `Select Artifact`
+2. From the list of artifacts select the `myGoAppArtifact` artifact that you created above.
+<img src="deliver_artifact_go.png" />
+3. In the next section, you'll assign the image outputArtifact from the `build_spec.yaml` to the DevOps project artifact. For the "Build config/result Artifact name" enter: `goWebAppArtifact`
+
+
+### Run your Build in OCI DevOps
+
+#### From your Build Pipeline, choose `Manual Run`
+Use the Manual Run button to start a Build Run
+
+Manual Run will use the Primary Code Repository, will start the Build Pipeline, first running the Managed Build stage, followed by the Deliver Artifacts stage.
+
+After the Build Pipeline execution is complete, we can view the executable file stored in the OCI Artifact Registry, which can then be downloaded to local workspace. 

examples/golang_webapp_example/build_spec.yaml

@@ -0,0 +1,28 @@
+version: 0.1
+component: build
+timeoutInSeconds: 6000
+runAs: root
+shell: bash
+env:
+  exportedVariables:
+    - version
+steps:
+  - type: Command
+    name: "Build golang app"
+    timeoutInSeconds: 6000
+    command: |
+      wget -nv https://dl.google.com/go/go1.16.5.linux-amd64.tar.gz
+      tar -C /usr/local -xzf go1.16.5.linux-amd64.tar.gz
+      rm -rf go1.16.5.linux-amd64.tar.gz
+      export PATH="/usr/local/go/bin:$PATH"
+      export GOPATH="/usr/local/go"
+      export PATH="$GOPATH/bin:$PATH"
+      go version
+      go build -o golangWebApp main.go
+      ls -a
+      echo "build finished.."
+
+outputArtifacts:
+  - name: goWebAppArtifact
+    type: BINARY
+    location: golangWebApp

examples/golang_webapp_example/main.go

@@ -0,0 +1,46 @@
+package main
+import (
+   "net/http"
+   "fmt"
+   "time"
+   "html/template"
+)
+
+//Create a struct that holds information to be displayed in our HTML file
+type Welcome struct {
+   Name string
+   Time string
+}
+
+//Go application entrypoint
+func main() {
+   //Instantiate a Welcome struct object and pass in some random information. 
+   //We shall get the name of the user as a query parameter from the URL
+   welcome := Welcome{"Dharmesh", time.Now().Format(time.Stamp)}
+
+   //We tell Go exactly where we can find our html file. We ask Go to parse the html file (Notice
+   // the relative path). We wrap it in a call to template.Must() which handles any errors and halts if there are fatal errors
+
+   templates := template.Must(template.ParseFiles("template/welcome-template.html"))
+
+
+
+   //This method takes in the URL path "/" and a function that takes in a response writer, and a http request.
+   http.HandleFunc("/" , func(w http.ResponseWriter, r *http.Request) {
+
+      //Takes the name from the URL query e.g ?name=Martin, will set welcome.Name = Martin.
+      if name := r.FormValue("name"); name != "" {
+         welcome.Name = name;
+      }
+      //If errors show an internal server error message
+      //I also pass the welcome struct to the welcome-template.html file.
+      if err := templates.ExecuteTemplate(w, "welcome-template.html", welcome); err != nil {
+         http.Error(w, err.Error(), http.StatusInternalServerError)
+      }
+   })
+
+   //Start the web server, set the port to listen to 8080. Without a path it assumes localhost
+   //Print any errors from starting the webserver using fmt
+   fmt.Println("Listening");
+   fmt.Println(http.ListenAndServe(":8080", nil));
+}

examples/golang_webapp_example/template/welcome-template.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+   <head>
+         <meta charset="UTF-8">
+         <link rel="stylesheet" href="/static/stylesheets/welcome-template.css">
+
+         <!-- The welcome struct (shown in the main.go code) is received within the HTML and we just need to use the . operator and retrieve the information we want -->
+         <title>Welcome {{.Name}}</title>
+   </head>
+   <body>
+      <div class="welcome center">Welcome {{.Name}}, it is {{.Time}}</div>
+   </body>
+</html>
+

examples/nodejs_example/README.md

@@ -0,0 +1,82 @@
+# Build Spec File Example using nodeJS web application and Creating an executable file
+
+This is an example of a nodejs web application and creating an executable file. With the [OCI DevOps service](https://www.oracle.com/devops/devops-service/) and this project, you'll be able to build this application,store the executable file in [OCI Artifact Registry.](https://docs.oracle.com/en-us/iaas/artifacts/using/overview.htm)
+
+
+## Building the application locally
+
+### Download the repo
+The first step to get started is to download the repository to your local workspace
+
+```shell
+git clone git@github.com:dlcbld/BuildSpecSampleFiles.git
+cd examples/nodejs_example
+```
+
+### Install and run the application
+
+1. Install nodejs on your system: 
+    ```yum install -y oracle-nodejs-release-el7 oracle-release-el7```
+2. Check that path is set properly by displaying version:
+    ```npm -version```
+3. Install the pkg library
+    ```npm install --global pkg```
+4. Package the nodejs web application file alongwith necessary modules using following command: 
+
+   ```pkg app.js```
+5. Run the app:
+    ```./app-macos```
+
+## Building the application in OCI DevOps
+Now that you've seen you can locally build this app, let's try this out through OCI DevOps Build service.
+### Create External Connection to your Git repository 
+1. Create a [DevOps Project](https://docs.oracle.com/en-us/iaas/Content/devops/using/devops_projects.htm) or use and an existing project. 
+2. In your DevOps project, create an External Connection to your GitHub repository which holds your application.
+   - Create a Personal Access Token (PAT): https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
+   - In the OCI Console, Go to Identity & Security -> Vault and create a [Vault]( https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Concepts/keyoverview.htm) in compartment of your own choice.
+   - Create a Master Key that will be used to encrypt the PATs. 
+   - Select Secrets from under Resources and create a secret using PAT obtained from GitHub account.
+   - Make a note of the OCID of the secret.
+   - Now, go to the desired project and select External Connection from the resources.
+   - Select type as GitHub and provide OCID of the secret under Personal Access Token.
+   - Finally, allow Build Service (dynamic group with DevOps Resources) to use a PAT secret by writing a policy in the root compartment as: ``` Allow dynamic-group dg-with-devops-resources to manage secret-family in tenancy```
+### Setup your Build Pipeline
+Create a new Build Pipeline to build, test and deliver artifacts from your GitHub Repository.
+### Managed Build stage
+In your Build Pipeline, first add a Managed Build stage
+1. The Build Spec File Path is the relative location in your repo of the build_spec.yaml . Leave the default, for this example.
+2. For the Primary Code Repository follow the below steps
+    - Select connection type as GitHub
+    - Select the external connection you created above
+    - Give the URL to the repo which contains your application.
+    - Select main branch.
+
+### Create a Artifact Registry repository
+Create a [Artifact Registry repository](https://docs.oracle.com/en-us/iaas/artifacts/using/manage-repos.htm#create-repo).
+
+### Create a DevOps Artifact for your artifact repository
+Create a DevOps Artifact to point to the Artifact Registry repository location you just created above. Enter the information for the Artifact location:
+1. Name: `myNodeJSAppArtifact`
+2. Type: General Artifact
+3. Artifact source: Artifact registry Repository
+    Select your Artifact Registry repository created in previous step.
+4. Artifact Location: Set custom location
+4. Path: `REGION/TENANCY-NAMESPACE/myNodeJSAppArtifact`
+1. Replace parameters: Yes
+### Add a Deliver Artifacts stage
+Let's add a **Deliver Artifacts** stage to your Build Pipeline to deliver the `app-macos` executable file to an OCI repository.
+The Deliver Artifacts stage **maps** the ouput Artifacts from the Managed Build stage with the version to deliver to a DevOps Artifact resource, and then to the OCI repository.
+Add a **Deliver Artifacts** stage to your Build Pipeline after the **Managed Build** stage. To configure this stage:
+1. In your Deliver Artifacts stage, choose `Select Artifact`
+2. From the list of artifacts select the `myNodeJSAppArtifact` artifact that you created above
+3. In the next section, you'll assign the  container image outputArtifact from the `build_spec.yaml` to the DevOps project artifact. For the "Build config/result Artifact name" enter: `NodeJSAppArtifact`
+
+
+### Run your Build in OCI DevOps
+
+#### From your Build Pipeline, choose `Manual Run`
+Use the Manual Run button to start a Build Run
+
+Manual Run will use the Primary Code Repository, will start the Build Pipeline, first running the Managed Build stage, followed by the Deliver Artifacts stage.
+
+After the Build Pipeline execution is complete, we can view the executable file stored in the OCI Artifact Registry, which can then be downloaded to local workspace. 

examples/nodejs_example/app.js

@@ -0,0 +1,14 @@
+const http = require('http');
+
+const hostname = '127.0.0.1';
+const port = 3000;
+
+const server = http.createServer((req, res) => {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/plain');
+  res.end('Hello World');
+});
+
+server.listen(port, hostname, () => {
+  console.log(`Server running at http://${hostname}:${port}/`);
+});

examples/nodejs_example/build_spec.yaml

@@ -0,0 +1,24 @@
+version: 0.1
+component: build
+timeoutInSeconds: 600
+runAs: root
+shell: bash
+env:
+  exportedVariables:
+    - version
+steps:
+  - type: Command
+    name: "Build NodeJS app"
+    timeoutInSeconds: 600
+    command: |
+      yum install -y oracle-nodejs-release-el7 oracle-release-el7
+      npm -version
+      npm install --global pkg
+      pkg app.js
+      ls -la
+      echo "build finished.."
+
+outputArtifacts:
+  - name: NodeJSAppArtifact
+    type: BINARY
+    location: app-macos