정적 웹사이트를 위한 Rust 인프라 호스팅

Rust 인프라 팀은 모든 Rust 팀이 이용할 수 있는 정적 웹사이트 호스팅을 제공합니다. 이 문서는 웹사이트가 충족해야 하는 요구 사항과 웹사이트를 설정하는 방법을 설명합니다.

웹사이트 호스팅 요구 사항

웹사이트는 Rust 팀이 관리하거나 프로젝트와 공식적으로 연계되어 있어야 합니다. 인프라 팀은 자원이 한정되어 있어 커뮤니티 프로젝트에는 호스팅을 제공할 수 없습니다.
웹사이트의 콘텐츠와 빌드 도구는 rust-lang 또는 rust-lang-nursery 조직의 GitHub 저장소에 호스팅되어야 합니다. 인프라 팀은 언제든지(예를 들어 호스팅을 옮겨야 하는 경우) 웹사이트 콘텐츠를 다시 빌드할 수 있어야 하며, 인프라 팀이 관리하는 조직 내 GitHub 저장소에 호스팅하는 것이 이를 보장하는 가장 좋은 방법입니다. 모든 저장소가 공개되어 있기를 바라지만, 필수 요건은 아닙니다.
웹사이트는 CI 서비스로 빌드하고 배포해야 합니다. 저희는 인프라에서 정적 웹사이트를 호스팅하기 위한 자체 도구를 갖추고 있으며, 현재 이 도구는 Travis CI 및 Azure Pipelines와 함께 동작합니다. 다른 CI 서비스가 필요하다면 미리 문의해 주십시오. 원하시는 제공자에 맞게 도구를 조정해 드리겠습니다.
웹사이트는 Mozilla Observatory에서 A+ 등급을 받아야 합니다. 브라우저에는 HTTP 응답 헤더를 통해서만 켜고 끌 수 있는 여러 보안 기능이 있으며, 이 기능들은 사용자의 개인 정보 보호를 강화하고 익스플로잇이 동작하지 못하도록 막습니다. Observatory에서 A+ 등급을 받았다는 것은 중요한 헤더가 모두 올바르게 설정되어 있다는 뜻입니다.
웹사이트는 인프라 팀이 검증한 플랫폼에 호스팅되어야 합니다. 호스팅으로는 GitHub Pages 또는 (rust-lang AWS 계정의) Amazon S3를, CDN으로는 CloudFront를 권장합니다. 다른 플랫폼이 필요하더라도 저희가 안전하고 신뢰할 수 있다고 판단하는 플랫폼이라면 괜찮습니다.

정적 웹사이트 구성

일부 호스팅 제공자의 제약을 피하기 위해 저희는 CloudFront에서 추가 사용자 정의 동작을 사용할 수 있도록 설정해 두었습니다. 이러한 동작은 생성된 웹사이트 콘텐츠의 루트에 있는 website_config.json 파일을 통해 구성합니다.

인프라 팀이 정적 웹사이트를 호스팅하기 위한 요구 사항 중 하나는 Mozilla Observatory에서 A+ 등급을 받는 것이며, 이를 위해서는 사용자 정의 헤더를 설정해야 합니다. 사용자 정의 헤더를 설정하려면 website_config.json에 headers 섹션을 추가해야 합니다. 다음 예시에는 Observatory에서 B 등급을 받는 데 필요한 헤더가 모두 포함되어 있습니다(A+ 등급을 받으려면 Content Security Policy가 필요합니다):

{
    "headers": {
        "Strict-Transport-Security": "max-age=63072000",
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "X-XSS-Protection": "1; mode=block",
        "Referrer-Policy": "no-referrer, strict-origin-when-cross-origin"
    }
}

GitHub Pages 리디렉션 문제 해결하기

GitHub Pages는 CloudFront 뒤에 있으면서 리디렉션을 발행해야 할 때 이상하게 동작하는 이슈가 있습니다. 실제 도메인 이름을 알지 못하므로 올바른 프로토콜과 도메인 대신 http://org-name.github.io/repo-name을 리디렉션의 기준으로 사용합니다. 이 동작을 막으려면 website_config.json에 github_pages_origin 키를 추가하고, 그 값으로 오리진 기본 URL(프로토콜 제외)을 지정해야 합니다:

{
    "github_pages_origin": "org-name.github.io/repo-name"
}

배포 가이드

이 배포 단계는 저희 AWS 계정에 대한 접근 권한이 필요하므로 인프라 팀 구성원이 수행하도록 되어 있습니다.

AWS 구성하기

CloudFront 웹 배포를 생성하고 다음 속성을 설정하십시오:

원본 도메인 이름: rust-lang.github.io/repo-name
Origin Protocol Policy: HTTPS Only
Viewer Protocol Policy: Redirect HTTP to HTTPS
Lambda Function Association:
- Viewer Response: arn:aws:lambda:us-east-1:890664054962:function:static-websites:4
대체 도메인 이름: your-subdomain-name.rust-lang.org
SSL 인증서: 사용자 지정 SSL 인증서
- 해당 서브도메인 이름의 인증서를 ACM을 통해 요청해야 합니다(인증서 검증에는 DNS 챌린지를 사용하십시오).
설명: your-subdomain-name.rust-lang.org

배포가 전파될 때까지 기다린 후 해당 배포의 .cloudfront.net 도메인 이름을 기록해 두십시오.

해당 도메인의 Route 53 호스팅 영역으로 이동하여 새 레코드 세트를 생성하십시오:

이름: your-subdomain-name(사용할 서브도메인 이름)
유형: CNAME
값: 앞서 확인한 .cloudfront.net 도메인 이름

웹사이트 변경 사항을 배포하는 데 사용하는 CI 제공자가 허용 목록에 등록된 자동 작업을 수행할 수 있도록 AWS IAM 사용자를 생성하십시오. 사용자 이름으로 ci--ORG-NAME--REPO-NAME(예: ci--rust-lang--rust)을 사용하고, 프로그래밍 방식 액세스를 허용한 뒤 ci-static-websites IAM 그룹에 추가하십시오. 그런 다음 액세스 키 ID와 비밀 액세스 키는 나중에 필요하므로 기록해 두십시오.

배포 키 추가하기

웹사이트를 배포할 때는 GitHub 토큰(세분화된 접근 범위 지정을 지원하지 않으므로)이 아니라 저장소마다 고유하며 쓰기 권한이 있는 배포 키를 사용합니다. 배포 키를 설정하려면 해당 저장소의 관리자여야 하며, simpleinfra 저장소를 클론한 후 다음 명령을 실행하십시오:

$ cargo run --bin setup-deploy-keys rust-lang/repo-name

이 명령을 실행하려면 GITHUB_TOKEN(여기에서 생성할 수 있습니다)과 TRAVIS_TOKEN(여기에서 확인할 수 있습니다)이 있어야 합니다. 이 명령은 새 키를 생성하여 GitHub에 업로드하고, 저장소가 Travis CI에서 활성화되어 있으면 해당 키를 사용하도록 Travis CI를 구성합니다.

Travis CI 구성하기

웹사이트를 실제로 배포하려면 .travis.yml에 다음 코드 조각을 추가해야 합니다(RUSTINFRA_DEPLOY_DIR 및 RUSTINFRA_CLOUDFRONT_DISTRIBUTION의 내용은 알맞게 바꾸십시오):

env:
  RUSTINFRA_DEPLOY_DIR: path/to/be/deployed
  RUSTINFRA_CLOUDFRONT_DISTRIBUTION: ABCDEFGHIJKLMN
import:
  - rust-lang/simpleinfra:travis-configs/static-websites.yml

또한 Travis CI 웹 UI에서 앞서 생성한 IAM 사용자의 자격 증명으로 AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY 환경 변수의 값을 설정해야 합니다. 비밀 액세스 키는 빌드 로그에서 반드시 숨겨야 하며, 액세스 키 ID는 공개적으로 보이도록 두어야 합니다.

Azure Pipelines 구성하기

웹사이트를 실제로 배포하려면 파이프라인 YAML 파일의 맨 위에 다음 코드 조각을 추가해야 합니다:

resources:
  repositories:
    - repository: rustinfra
      type: github
      name: rust-lang/simpleinfra
      endpoint: rust-lang

그런 다음 배포를 실행하려는 위치에 다음 단계를 추가하면 됩니다(deploy_dir 및 cloudfront_distribution의 내용은 알맞게 바꾸십시오):

- template: azure-configs/static-websites.yml@rustinfra
  parameters:
    deploy_dir: path/to/output
    # Optional, only needed if GitHub pages is behind CloudFront
    cloudfront_distribution: AAAAAAAAAAAAAA

또한 파이프라인에 다음 환경 변수를 설정해야 합니다:

GITHUB_DEPLOY_KEY: 앞서 배포 키를 추가할 때 출력된 값(비공개)
AWS_ACCESS_KEY_ID: CloudFront 무효화 권한이 있는 IAM 사용자의 액세스 키 ID(공개)
AWS_SECRET_ACCESS_KEY: CloudFront 무효화 권한이 있는 IAM 사용자의 액세스 키(비공개)

Rust Forge