Add comments to describe build and deploy

Author: loginwashere

.semaphore/client-deploy-build.yml

@@ -51,15 +51,16 @@ blocks:
           commands:
             - cd src/client
 
+            # Copy production configs we linked using secrets
             - cp /home/semaphore/client-production.env .env
 
             # Restore dependencies from cache.
             # For more info on caching, see https://docs.semaphoreci.com/article/68-caching-dependencies
             - cache restore client-node-modules-$SEMAPHORE_GIT_BRANCH-$(checksum package-lock.json),client-node-modules-$SEMAPHORE_GIT_BRANCH,client-node-modules-master
 
             - npm run build
-            # Store the latest version of node modules in cache to reuse in
-            # further blocks:
+
+            # Store the latest version of client build in cache to reuse in further blocks:
             - cache store client-build-$SEMAPHORE_WORKFLOW_ID build
 
 # The deployment pipeline is defined to run on manual approval from the UI.

.semaphore/client-deploy.yml

@@ -32,6 +32,7 @@ blocks:
             # Restore build from cache.
             - cache restore client-build-$SEMAPHORE_WORKFLOW_ID
 
+            # Config ssh and git to push new build files into gh-pages branch of app repository
             - ssh-keyscan -H github.com >> ~/.ssh/known_hosts
             - chmod 600 ~/.ssh/id_rsa_semaphoreci_ghpages_deploy
             - ssh-add ~/.ssh/id_rsa_semaphoreci_ghpages_deploy
@@ -41,4 +42,5 @@ blocks:
 
             - npm run deploy
 
+            # Restore change to global git repository url rewrite to previous value
             - git config --global url."https://github.com/".insteadOf "[email protected]:"

.semaphore/secrets/client-production-env-secret.sample.yml

@@ -1,8 +1,19 @@
+# Copy this file into one without .sample part and then populate it with actual values.
+# Then you can create secret, by using command
+# `sem create -f path/to/this/file`
+# More info https://docs.semaphoreci.com/article/66-environment-variables-and-secrets
 apiVersion: v1alpha
 kind: Secret
 metadata:
+  # Use this name to create this secret manually
   name: client-production-env-secret
 data:
   files:
+    # Client production.env file doesn't exist by default, copy src/client/sample.env into src/client/production.env
+    # and populate with production values
+    # Then create secret - in the end it should be here - https://<put-your-namespace-here>.semaphoreci.com/secrets
     - path: client-production.env
-      content: PASTE_BASE64_ENCODED_CONTENT_HERE
+      # Could be created by
+      # - `base64 -w 0 /path/to/file` and put in
+      # - upload in https://<your-namesace>.semaphoreci.com/secrets
+      content: PASTE_BASE64_ENCODED_CONTENT_HERE

.semaphore/secrets/gc-k8s-secret.sample.yml

@@ -1,8 +1,26 @@
+# Copy this file into one without .sample part and then populate it with actual values.
+# Then you can create secret, by using command
+# `sem create -f path/to/this/file`
+# More info https://docs.semaphoreci.com/article/66-environment-variables-and-secrets
 apiVersion: v1alpha
 kind: Secret
 metadata:
+  # Use this name to create this secret manually
   name: gc-k8s-secret
 data:
   files:
+    # If you haven't set up k8s on google you need to do it first
+    # Start with https://cloud.google.com/kubernetes-engine/docs/quickstart
+    # Play with it and then you can use it with this project.
+    # Also check out https://docs.semaphoreci.com/article/119-ci-cd-for-microservices-on-kubernetes
+    # as example of k8s deploy.
+    # If you have admin of dev ops - contact them to obtain this config
+    # Also you could try to get this yourself in case you have permissions
+    # Run command
+    # `gcloud container clusters get-credentials [CLUSTER_NAME]`
+    # Then look for `.kube` folder and find config.yaml there.
     - path: .kube/gc-k8s.yaml
+      # Could be created by
+      # - `base64 -w 0 /path/to/file` and put in
+      # - upload in https://<your-namesace>.semaphoreci.com/secrets
       content: PASTE_BASE64_ENCODED_CONTENT_HERE

.semaphore/secrets/gcr-secret.sample.yml

@@ -1,13 +1,33 @@
+# Copy this file into one without .sample part and then populate it with actual values.
+# Then you can create secret, by using command
+# `sem create -f path/to/this/file`
+# More info https://docs.semaphoreci.com/article/66-environment-variables-and-secrets
 apiVersion: v1alpha
 kind: Secret
 metadata:
+  # Use this name to create this secret manually
   name: gcr-secret
 data:
+  # If you haven't set up k8s on google you need to do it first
+  # Start with https://cloud.google.com/kubernetes-engine/docs/quickstart
+  # Play with it and then you can use it with this project.
+  # Check out https://docs.semaphoreci.com/article/72-google-container-registry-gcr as an example.
+  # Also check out https://docs.semaphoreci.com/article/119-ci-cd-for-microservices-on-kubernetes
+  # as example of k8s deploy.
   env_vars:
+    # Id of your project
+    # More info here https://cloud.google.com/resource-manager/docs/creating-managing-projects?visit_id=636878590586351739-3388570778&rd=1#identifying_projects
     - name: GCP_PROJECT_ID
       value: "your-gcp-project-id"
+    # Default compute zone you've selected
+    # https://cloud.google.com/compute/docs/regions-zones/#available
     - name: GCP_PROJECT_DEFAULT_ZONE
       value: "europe-west1-b"
   files:
+    # You need to create service account and export json key file for it here https://console.cloud.google.com/iam-admin/serviceaccounts
+    # to use in this file.
     - path: .secrets.gcp.json
+      # Could be created by
+      # - `base64 -w 0 /path/to/file` and put in
+      # - upload in https://<your-namesace>.semaphoreci.com/secrets
       content: PASTE_BASE64_ENCODED_CONTENT_HERE

.semaphore/secrets/gh-pages-secret.sample.yml

@@ -1,13 +1,25 @@
+# Copy this file into one without .sample part and then populate it with actual values.
+# Then you can create secret, by using command
+# `sem create -f path/to/this/file`
+# More info https://docs.semaphoreci.com/article/66-environment-variables-and-secrets
 apiVersion: v1beta
 kind: Secret
 metadata:
+  # Use this name to create this secret manually
   name: gh-pages-secret
 data:
   env_vars:
+    # Username of github user used for deploy
     - name: GH_USERNAME
       value: "super secret github username"
+    # Email of github user used for deploy
     - name: GH_EMAIL
       value: "super secret github email"
   files:
+    # Generate ssh key https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
+    # Add it to account you will use to deploy to github here https://github.com/settings/keys
     - path: .ssh/id_rsa_semaphoreci_ghpages_deploy
+      # Could be created by
+      # - `base64 -w 0 /path/to/file` and put in
+      # - upload in https://<your-namesace>.semaphoreci.com/secrets
       content: PASTE_BASE64_ENCODED_CONTENT_HERE

.semaphore/secrets/server-ormconfig-production-secret.sample.yml

@@ -1,8 +1,21 @@
+# Copy this file into one without .sample part and then populate it with actual values.
+# Then you can create secret, by using command
+# `sem create -f path/to/this/file`
+# More info https://docs.semaphoreci.com/article/66-environment-variables-and-secrets
 apiVersion: v1beta
 kind: Secret
 metadata:
+  # Use this name to create this secret manually
   name: server-ormconfig-production
 data:
   files:
+  # Copy src/server/ormconfig.sample.json into ormconfig.production.json and populate with production values
+  # You will need production connection settings in this config file.
+  # In this eample heroku postgres database addon is used.
+  # You will need to create heroku app and then add addon https://elements.heroku.com/addons/heroku-postgresql
+  # Then you will be able to view database connection settings like described here https://devcenter.heroku.com/articles/heroku-postgresql#external-connections-ingress
   - path: ormconfig.production.json
+    # Could be created by
+    # - `base64 -w 0 /path/to/file` and put in
+    # - upload in https://<your-namesace>.semaphoreci.com/secrets
     content: PASTE_BASE64_ENCODED_CONTENT_HERE

.semaphore/secrets/server-production-env-secret.sample.yml

@@ -1,8 +1,19 @@
+# Copy this file into one without .sample part and then populate it with actual values.
+# Then you can create secret, by using command
+# `sem create -f path/to/this/file`
+# More info https://docs.semaphoreci.com/article/66-environment-variables-and-secrets
 apiVersion: v1beta
 kind: Secret
 metadata:
+  # Use this name to create this secret manually
   name: server-production-env
 data:
   files:
+  # Server production.env file doesn't exist by default, copy src/server/sample.env into src/server/production.env
+  # and populate with production values
+  # Then create secret - in the end it should be here - https://<put-your-namespace-here>.semaphoreci.com/secrets
   - path: server-production.env
-    content: PASTE_BASE64_ENCODED_CONTENT_HERE
+    # Could be created by
+    # - `base64 -w 0 /path/to/file` and put in
+    # - upload in https://<your-namesace>.semaphoreci.com/secrets
+    content: PASTE_BASE64_ENCODED_CONTENT_HERE

.semaphore/server-docker-build.yml

@@ -20,6 +20,7 @@ blocks:
         - name: server-production-env
       prologue:
         commands:
+          # Lets configure gcloud to push docker image into container registry
           # Authenticate using the file injected from the secret
           - gcloud auth activate-service-account --key-file=.secrets.gcp.json
           # Don't forget -q to silence confirmation prompts
@@ -32,6 +33,7 @@ blocks:
         commands:
           - cd src/server
 
+          # Copy production configs we linked using secrets
           - cp /home/semaphore/ormconfig.production.json ormconfig.json
           - cp /home/semaphore/server-production.env production.env
 

README.md

@@ -11,7 +11,9 @@ project](https://docs.semaphoreci.com/article/63-your-first-project).
 
 The CI pipeline will look like this:
 
-![CI pipeline on Semaphore](images/ci-pipeline.png)
+![CI pipeline on Semaphore](images/ci-pipeline-client.png)
+
+![CI pipeline on Semaphore](images/ci-pipeline-server.png)
 
 The example pipeline contains 4 blocks:
 
@@ -25,6 +27,23 @@ The example pipeline contains 4 blocks:
     - Runs E2E tests through cypress on client.
     - Runs E2E tests through jest on server.
 
+Then, if all checks are ok, we move to build pipeline. It consists of one block
+
+ - Build
+   - Build client- build client app using create-react-app sctipts
+   - Build server - build container and push it into google repository
+
+Then, after we've built our apps we move to deploy pipeline.
+It  also consists of one block for client and of two for server.
+As you can see deploy pipelines of client and server depend only on their own build step
+and therefore could be run in parallel.
+
+ - Deploy
+   - Deploy client - commit and push build into gh-pages branch to deploy on Github
+   - Deploy server
+      - Deploy server to k8s, pdate k8s deployment using deployment config
+      - Tag container if all went well
+
 ## Local project setup
 
 This project requires a PostgreSQL database. If you don't have one you can
@@ -56,6 +75,12 @@ Steps described in server [README](src/server/README.md)
 
 Steps described in client [README](src/client/README.md)
 
+## Deploy configuration
+
+Check out `.semaphore/` folder - steps described there have helpful comments to help you figure out what commands are doing.
+Also check out `.semaphore/secrets` folder. To configure deploy you need to create and populate all those secrets.
+Copy each secret file into file without `.sample` in filename and populate it. All of them have useful description comments to help you out.
+
 ## License
 
 Copyright (c) 2019 Rendered Text