by Marius Lazar

通過馬里烏斯·拉扎爾(Marius Lazar)

我們如何使用CircleCI 2.0來構建Angular應用并將其部署到AWS S3 (How we used CircleCI 2.0 to build and deploy an Angular app to AWS S3)

In today’s world, continuous integration and deployment (CI & CD) is a very common practice and an important part in any application life cycle. If you want to avoid spending valuable time on tasks that you can actually automate, keep on reading.

在當今世界，持續集成和部署(CI＆CD)是非常常見的做法，并且在任何應用程序生命周期中都是重要的組成部分。 如果您想避免將寶貴的時間花在實際上可以自動化的任務上，請繼續閱讀。

In this tutorial, I’m going to walk you through the steps we have followed to integrate a CI & CD pipeline in the development process of one of our Angular apps using CircleCI 2.0 and AWS S3.

在本教程中，我將帶您逐步完成在使用CircleCI 2.0和AWS S3的Angular應用之一的開發過程中集成CI和CD管道的步驟。

要求 (Requirements)

Before you start this tutorial, I assume you have the following:

在開始本教程之前，我假設您具有以下條件：

• A CircleCI account
  CircleCI帳戶
• An AWS account with rights to create new users
  有權創建新用戶的AWS賬戶
• An AWS S3 Bucket
  一個AWS S3存儲桶
• A Bitbucket or Github repository with your project
  項目中的Bitbucket或Github存儲庫
• A cup of coffee — you know… keeps you warm and focused :)
  一杯咖啡-您知道……讓您保持溫暖和專注：)

設置CircleCI (Setting up CircleCI)

Let’s get to work. For setting up CircleCI, you need to create a new folder in your project root called .circleci (notice the dot) and add a config.yml file to it. Leave it empty for a second.

讓我們開始工作。 要設置CircleCI，您需要在項目根目錄中創建一個名為.circleci (注意點)的新文件夾，并向其中添加config.yml文件。 讓它空一秒鐘。

Go to the CircleCI interface and add your project by going to Projects tab > Add Project . CircleCI should have already found all your public repos. Select your project and press the Setup project button.

轉到CircleCI界面并通過轉到“ Projects tab > Add Proj項目”來添加您的項目。 CircleCI應該已經找到了您所有的公共存儲庫。 選擇您的項目，然后按“ he Setup proj項目”按鈕。

Select the options that fit you best (Linux/Platform 2.0/Node in our case), copy the sample config generated down on the page into your own config file, and push the changes to your repo. Now you can press the Start building button.

選擇最適合您的選項(在我們的例子中為Linux / Platform 2.0 / Node)，將頁面上向下生成的樣本配置復制到您自己的配置文件中，然后將更改推送到您的存儲庫中。 現在，您可以按Start building按鈕。

You can find a gist with the final configuration here.

您可以在此處找到具有最終配置的要點。

了解CircleCI配置文件 (Understanding the CircleCI configuration file)

The bread and butter of this tutorial is to understand how to make use of the CircleCI config file. It has 3 main components: a version, a list of jobs, and a list of workflows.

本教程的基本內容是了解如何利用CircleCI配置文件。 它具有3個主要組件：版本，作業列表和工作流程列表。

The version is pretty obvious. It’s the CircleCI version that we are going to use.

該版本非常明顯。 這是我們將要使用的CircleCI版本。

Then we have the list of jobs. You can think of a job like an independent environment for running a list of commands or steps. Common things that you can achieve within a job include:

然后，我們有了工作清單。 您可以將作業視為獨立的環境，以運行命令或步驟的列表。 您可以在工作中實現的常見事項包括：

• Installing the tools you need to run/build/test your project
  安裝運行/構建/測試項目所需的工具
• Executing bash commands
  執行bash命令
• Storing or restoring items from the CircleCI cache
  從CircleCI緩存中存儲或還原項目

Then we have the list of workflows. A workflow is a way to manage your jobs. Let’s say you need a job to run only on specific branches or at specific times, or you want some of the jobs to run in parallel and some in sequence. That’s what workflows are for.

然后，我們獲得了工作流程列表。 工作流是管理工作的一種方式。 假設您需要一個作業僅在特定分支或特定時間運行，或者您希望某些作業并行運行，而某些則依次運行。 那就是工作流程的目的。

A basic CircleCI config structure:

CircleCI基本配置結構：

In our case we have two jobs: the build job and the deploy job. I will describe each of them in the following sections, but for now, let’s see what attributes we are going to use for each of the jobs:

在我們的例子中，我們有兩個工作： 構建工作和部署工作 。 我將在以下各節中對它們中的每一個進行描述，但是現在，讓我們看看我們將對每個作業使用哪些屬性：

• The docker attribute — specify a Docker image used to create the container of the environment. CircleCI comes with a list of pre-built images that you can find here

  docker屬性-指定用于創建環境容器的Docker映像。 CircleCI帶有預建圖像列表，您可以在此處找到

• The working_directory attribute— the current directory which will be the place where all the steps will run

  working_directory屬性-當前目錄，將在其中運行所有步驟

• The steps attribute — a list of steps (commands) that you want to run in the current job

  steps屬性-您要在當前作業中運行的步驟(命令)的列表

There are a few types of steps that we are going to use in our configuration:

我們將在配置中使用幾種類型的步驟：

• The checkout step — used to checkout the code from the current branch into the working directory

  檢出步驟-用于將代碼從當前分支檢出到工作目錄中

• The run step — used to execute a bash command. You can specify a descriptive name which you are going to see in the CircleCI interface

  運行步驟-用于執行bash命令。 您可以指定一個描述性名稱，該名稱將在CircleCI界面中顯示

• The save_cache step — used to store a cache of a file or a directory in the CircleCI storage. A common use case is to install the npm dependencies only once and then cache the node_modules folder using a hash of the package.json file as the cache key

  save_cache步驟—用于在CircleCI存儲中存儲文件或目錄的緩存。 一個常見的用例是只安裝npm依賴項一次，然后使用package.json文件的哈希作為緩存鍵來緩存node_modules文件夾

• The restore_cache step — used to restore a cached item using the cache key

  restore_cache步驟-用于使用緩存鍵還原緩存的項目

Each job has access to some predefined environment variables. You can check the full list here. You can also set up environment variables from the CircleCI interface or as a job attribute, but in this tutorial we are only going to use the following environment variables:

每個作業都可以訪問一些預定義的環境變量。 您可以在此處查看完整列表。 您也可以從CircleCI界面或作為作業屬性來設置環境變量，但是在本教程中，我們將僅使用以下環境變量：

• CIRCLE_BRANCH — represents the current branch
  CIRCLE_BRANCH —代表當前分支
• CIRCLE_SHA1 — represents a hash of the current commit
  CIRCLE_SHA1 —表示當前提交的哈希

配置CI管道 (Configuring the CI pipeline)

The CI pipeline will be responsible for building, linting, and testing the source code. All three processes will be aggregated into a single job called the build job.

CI管道將負責構建，整理和測試源代碼。 所有這三個過程將匯總到一個稱為構建作業的作業中 。

You can have a quick look at the final build job below, but I’m going to take each step separately so we can learn a bit more about what’s happening there.

您可以快速瀏覽下面的最終構建作業，但是我將分別進行每個步驟，以便我們可以了解有關那里發生的事情的更多信息。

We start by checking out the code from the current branch

我們首先從當前分支中簽出代碼

# Checkout the code from the branch into the working_directory- checkout

2. We log the current branch for debugging purposes

2.我們記錄當前分支以進行調試

# Log the current branch- run: name: Show current branch command: echo ${CIRCLE_BRANCH}

3. We restore the node_modules folder from the cache if it exists. You can have a peak at step 5 to see how it was saved.

3.如果存在，我們將從緩存中還原node_modules文件夾。 您可以在第5步看到一個峰，以了解它是如何保存的。

# Restore local dependencies from cache- restore_cache: keys: - v1-dependencies-{{ checksum "package.json" }} - v1-dependencies-

You notice that we are using two cache keys. A key is a pattern to search for a cached item. The first one is specific to the current package.json file and the second one is more generic and matches all previously cached node_modules folders.

您會注意到我們正在使用兩個緩存鍵。 密鑰是用于搜索緩存項目的模式。 第一個特定于當前package.json文件，第二個更通用，并且匹配所有先前緩存的node_modules文件夾。

In case the very specific cache doesn’t exist, we are going to look for any previously cached node_modules folder and restore that instead. This is useful when only some of our dependencies have been updated, because we don’t need to download and install the whole list of dependencies. We are only going to do that for the updated packages and restore the unchanged ones from the cache.

如果不存在非常特定的緩存，我們將查找以前緩存的任何node_modules文件夾，并將其還原。 當僅更新了一些依賴項時，這很有用，因為我們不需要下載并安裝整個依賴項列表。 我們只會對更新的軟件包執行此操作，并從緩存中還原未更改的軟件包。

4. We install the project dependencies. If those dependencies have already been restored from the cache, this step will be very quick. Otherwise it can take up to a few minutes. That’s why caching is important. Saves you time and money.

4.我們安裝項目依賴項。 如果這些依賴關系已經從緩存中恢復，則此步驟將非常快。 否則可能需要幾分鐘。 這就是為什么緩存很重要。 為您節省時間和金錢。

# Install project dependencies- run: name: Install local dependencies command: npm install

5. We cache the node_modules folder in case it doesn’t exist. Keep in mind that a cache is immutable, so it will not be overwritten if it already exists.

5.如果不存在node_modules文件夾，我們將對其進行緩存。 請記住，緩存是不可變的，因此如果緩存已經存在，則不會被覆蓋 。

# Cache local dependencies if they don't exist- save_cache: key: v1-dependencies-{{ checksum "package.json" }} paths: - node_modules

A new cache will be generated with the folders/files specified in the paths attribute every time something is changed in the package.json file. The key of the cache is generated using the checksum function, which will output a base64 encoded hash of the package.json file’s content.

每當package.json文件中的內容發生更改時，都會使用paths屬性中指定的文件夾/文件生成一個新的緩存。 緩存的密鑰使用校驗和函數生成，該函數將輸出package.json文件內容的base64編碼哈希。

One commonly used technique is to prefix your cache key with a version number, so whenever you want to regenerate your caches, you can just change the version number.

一種常用的技術是在緩存密鑰之前添加版本號，因此，每當您要重新生成緩存時，都可以更改版本號。

6. We run the lint and test commands. It’s probably worth noticing that if any of the steps fail, the whole build will fail.

6.我們運行lint和測試命令。 可能值得注意的是，如果任何步驟失敗，整個構建都會失敗。

# Lint the source code- run: name: Linting command: npm run lint# Test the source code- run: name: Testing command: npm run test

7. We run the build command. Notice that we are going to use a multi-line command with each line running in the same shell, so we start the command with the pipe (|) character.

7.我們運行build命令。 注意，我們將使用多行命令，并且每行都在同一shell中運行，因此我們以豎線(|)字符啟動該命令。

We check the current branch name and run the corresponding npm script to build the project. We do this because we have different configurations based on the environment. The resulting files will be saved into the dist folder.

我們檢查當前分支名稱，并運行相應的npm腳本來構建項目。 我們這樣做是因為我們根據環境有不同的配置。 生成的文件將保存到dist文件夾中。

# Build project with different configuration based on# the current branch- run: name: Building command: | if [ "${CIRCLE_BRANCH}" == "staging" ]; then npm run build-qa elif [ "${CIRCLE_BRANCH}" == "master" ]; then npm run build-prod else npm run build-dev fi

8. Finally, we save the dist folder into the cache so we can restore it later in the deploy job. We are using both CIRCLE_BRANCH and CIRCLE_SHA1 environment variables to generate a unique cache key which doesn’t already exists in the cache.

8.最后，我們將dist文件夾保存到緩存中，以便稍后可以在部署作業中將其還原。 我們同時使用CIRCLE_BRANCH和CIRCLE_SHA1環境變量來生成唯一的緩存鍵，該鍵在緩存中尚不存在。

Notice that we are not in a shell command, so we need to take those variables from the .Environment variable.

注意，我們不在shell命令中，因此我們需要從.Environment變量中獲取這些變量。

# Cache the dist folder for the deploy job- save_cache: key: v1-dist-{{ .Environment.CIRCLE_BRANCH }}-{{ .Environment.CIRCLE_SHA1 }} paths: - dist

As a side note, we first tried installing angular-cli globally and cached it for later use, but it would take up to 30s to finish the installation even when it was cached. So we decided to create a few npm scripts to run ng commands using the local angular-cli.

附帶說明一下，我們首先嘗試在全局范圍內安裝angular-cli并將其緩存以備后用，但是即使已緩存，它也可能需要30秒鐘才能完成安裝。 因此，我們決定創建一些npm腳本來使用本地angular-cli運行ng命令。

"scripts": { "ng": "ng", "start": "ng serve --env=local", "build": "ng build", "test": "ng test", "lint": "ng lint", "e2e": "ng e2e", "build-dev": "ng build --target=development --environment=dev", "build-qa": "ng build --target=production --environment=qa", "build-prod": "ng build --prod"}

And that’s it! We now have a working CI pipeline. You should be able to save this into your own config file, push it to your repo, and check if everything is working as you expect.

就是這樣！ 現在，我們有一條有效的CI管道。 您應該能夠將其保存到自己的配置文件中，將其推送到您的倉庫中，并檢查一切是否按預期工作。

In case you are wondering, you don’t need any workflow in place to run a job. By default, each job will fire when you push a change.

如果您想知道，則不需要任何工作流程即可運行作業。 默認情況下，當您推送更改時，每個作業都會觸發。

配置CD管道 (Configuring the CD pipeline)

The CD pipeline will be responsible for deploying the distribution files resulting from the build job to an AWS S3 bucket. Guess what? We are going to call this the deploy job.

CD管道將負責將構建作業產生的分發文件部署到AWS S3存儲桶。 你猜怎么了？ 我們將其稱為部署工作 。

Before we can continue, we have to give CircleCI permissions to access the AWS S3 Bucket.

在繼續之前，我們必須授予CircleCI權限以訪問AWS S3存儲桶。

First, we are going to create a new IAM user in the AWS Management Console. Go to Services > IAM > Users > Add User . Give it a name and select the Programmatic access box for the Access type.

首先，我們將在AWS管理控制臺中創建一個新的IAM用戶。 轉到Services > IAM > Users >添加用戶。 給它起一個名字，并為“訪問”類型選擇“程序訪問”框。

Go Next . We now have to go give the user some permissions. In our case, we only need the circleci user to be able to Read/Write an AWS S3 Bucket. Find and select the AmazonS3FullAccess policy, then press theCreate user button.

轉到Next 。 現在，我們必須給用戶一些權限。 在我們的情況下，我們僅需要circleci用戶即可讀取/寫入AWS S3存儲桶。 查找并選擇AmazonS3FullAccess策略，然后按Create user按鈕。

On the next page, you will have an Access key ID and a Secret access key for the new user. Keep this page open and go to the CircleCI interface. Get into the project settings and search for AWS Permissions. You will need to use the previously generated keys in here.

在下一頁上，您將為新用戶提供一個訪問密鑰ID和一個秘密訪問密鑰 。 保持此頁面打開并轉到CircleCI界面。 進入項目設置并搜索AWS Permissions 。 您將需要在此處使用先前生成的密鑰。

Once you’ve done that, we can continue with our deploy job.

完成此操作后，我們可以繼續進行部署工作。

Same as previously, you have the final deploy job below. But I’m going to discuss each step separately, even though they are pretty straight-forward this time.

與之前相同，您將在下面完成最終的部署工作。 但是我將分別討論每個步驟，即使這次它們很簡單。

We start by logging the branch name for debugging purposes.

我們首先記錄分支名稱以進行調試。

# Log the current branch- run: name: Show current branch command: echo ${CIRCLE_BRANCH}

2. We restore the cached dist folder saved on the build job.

2.我們還原保存在構建作業中的緩存的dist文件夾。

# Restore cache from the build job which contains the# dist folder that needs to be deployed- restore_cache: key: v1-dist-{{ .Environment.CIRCLE_BRANCH }}-{{ .Environment.CIRCLE_SHA1 }}

3. We install the aws cli using sudo rights.

3.我們使用sudo權限安裝aws cli。

# Install AWS cli- run: name: Install aws cli command: sudo apt-get -y -qq install awscli

4. We run the deploy command which is going to deploy the code from the dist folder to the AWS S3 Bucket corresponding to the current environment. We have again a multi-line command, so we need to start with the pipe (|) character.

4.我們運行deploy命令，該命令會將dist文件夾中的代碼部署到與當前環境相對應的AWS S3存儲桶。 我們再次有一個多行命令，因此我們需要以豎線(|)開頭。

# Deploy to the S3 bucket corresponding to the current branch- run: name: Deploy to S3 command: | if [ "${CIRCLE_BRANCH}" == "develop" ]; then aws s3 sync dist s3://project-dev/ --delete elif [ "${CIRCLE_BRANCH}" == "staging" ]; then aws s3 sync dist s3://project-qa/ --delete elif [ "${CIRCLE_BRANCH}" == "master" ]; then aws s3 sync dist s3://project/ --delete fi

The signature for deploying to an AWS S3 Bucket using the aws cli is as follows:

使用aws cli部署到AWS S3存儲桶的簽名如下：

aws s3 sync <% path-to-folder %> s3://<% bucket-name %>/ --delete

The delete flag will clear the bucket before deploying any files.

刪除標志將在部署任何文件之前清除存儲桶。

One more thing. Or maybe two… We have encountered 2 errors after we had this configuration in place. Maybe they are not applicable in your case, but I will still give you a short summary.

還有一件事。 也許是兩個……適當配置此配置后，我們遇到了2個錯誤。 也許它們不適用于您的情況，但是我還是給您一個簡短的摘要。

The region of the S3 Bucket was not specified.

未指定S3存儲桶的區域。

A client error (PermanentRedirect) occurred when calling the ListObjects operation: The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint.調用ListObjects操作時發生客戶端錯誤(PermanentRedirect)：嘗試訪問的存儲桶必須使用指定的端點進行尋址。 請將所有將來的請求發送到此端點。

To solve this error, we had to add the bucket region to the deploy command:

要解決此錯誤，我們必須將bucket區域添加到deploy命令：

aws --region eu-west-2 s3 sync <% path %> s3://<% bucket-name %>/

2. The authorization to the S3 Bucket was using an old protocol which is not supported by the current bucket.

2.對S3存儲桶的授權使用的是舊協議，當前存儲桶不支持該協議。

A client error (InvalidRequest) occurred when calling the ListObjects operation: The authorization mechanism you have provided is not supported. Please use AWS4-HMAC-SHA256.調用ListObjects操作時發生客戶端錯誤(InvalidRequest)：不支持您提供的授權機制。 請使用AWS4-HMAC-SHA256。

To solve this error, we had to set the authorization mechanism for authenticating an AWS S3 Request to use the Signature Version 4 before running the deploy step:

為了解決此錯誤，我們必須在運行部署步驟之前設置用于對使用簽名版本4的AWS S3請求進行身份驗證的授權機制：

# Set the signature version for the S3 auth- run: name: Setting Signature Version 4 for S3 Request Authentication command: aws configure set default.s3.signature_version s3v4

That’s it! We now have a working CD pipeline. Only one small problem… It will run on every push. So let’s configure a workflow to solve this.

而已！ 現在，我們有一個正在運行的CD管道。 只有一個小問題…它會在每次推送時運行。 因此，讓我們配置一個工作流程來解決此問題。

將CI和CD作業放入工作流程 (Putting the CI & CD jobs into a workflow)

In our case, we want to run the build job on every commit and the deploy job only when we commit to develop, staging, or the master branch. A workflow, by default, is triggered by pushing to any branch.

在我們的例子中，我們只希望在提交開發，暫存或master分支時才在每次提交和部署作業上運行構建作業。 默認情況下，工作流程是通過推送到任何分支來觸發的。

We actually wanted the build job to run only when we make a Pull Request (PR), and this is possible by going into the Advance Settings of your CircleCI project and turning on the Only build pull requests option.

實際上，我們實際上希望構建作業僅在發出“拉取請求”(PR)時運行，這可以通過進入CircleCI項目的“高級設置”并打開“ Only build pull requests 選項。

But the problem comes when you need to run the workflow on PR and also on develop, staging, and master branches. We couldn’t find how to make this work. But if you have any suggestions, please leave me a comment!

但是問題出在需要在PR以及開發，登臺和主分支上運行工作流時。 我們找不到如何使這項工作。 但是，如果您有任何建議，請給我評論！

Back to our workflow config. It is pretty self-explanatory:

返回我們的工作流程配置。 這是不言自明的：

You can see that we have defined the build_and_deploy workflow which contains… the build and deploy jobs. The build job has no restrictions, so it will run whenever the workflow runs.

您可以看到我們已經定義了build_and_deploy工作流，其中包含……構建和部署作業。 構建作業沒有任何限制，因此它將在工作流程運行時運行。

On the other hand, the deploy job has a require property for the build job which means that it will only run if the build job is successful. It also has a filter attribute which is used to select the branches that it will run on.

另一方面，部署作業具有構建作業的require屬性，這意味著它將僅在構建作業成功時運行。 它還具有一個filter屬性，該屬性用于選擇將在其上運行的分支。

With this configuration in place, we have limited the execution of the deploy job to the develop, staging, and master branches only when the build job is successful, which is exactly what we wanted.

有了此配置，僅當構建作業成功時，我們才將部署作業的執行限制在開發，登臺和主分支上，這正是我們想要的。

That’s pretty much it. A gist with the entire configuration can be found here.

就是這樣。 完整配置的要點可以在這里找到。

獎勵功能 (Bonus feature)

If you are like us and you would like know what’s happening with your project, you will be glad to hear that there is a CircleCI app for Slack which can be configure to give you real time alerts when a build succeeds or fails. It’s nice to have.

如果您像我們一樣，并且想知道項目的進展，您將很高興聽到有一個用于Slack的CircleCI應用程序，可以將其配置為在構建成功或失敗時向您發出實時警報。 真高興。

最后的想法 (Final thoughts)

I know it can be intimidating, but don’t be afraid to integrate a CI & CD pipeline into your project. It will take a bit of time until you get the configuration right, but it’s worth it!

我知道這可能令人生畏，但不要害怕將CI和CD管道集成到您的項目中。 正確配置之前需要花費一些時間，但這是值得的！

If you think this article was helpful for you, please recommend and share!

如果您認為本文對您有所幫助，請推薦并分享！

Thanks for reading! If you have any comments or questions, please reach out to me! I’m always glad to help :)

謝謝閱讀！ 如果您有任何意見或疑問，請與我聯系！ 我總是很樂意為您提供幫助:)

翻譯自: https://www.freecodecamp.org/news/our-journey-for-using-circleci-2-0-to-build-and-deploy-an-angular-app-to-aws-s3-8e7ea3f51503/

總結

以上是生活随笔為你收集整理的我们如何使用CircleCI 2.0来构建Angular应用并将其部署到AWS S3的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。