정적 웹사이트를 위한 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 또는 Amazon S3(rust-lang AWS 계정 내)를, 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 challenge를 사용하십시오).
설명: 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

또한 앞서 생성한 IAM 사용자의 자격 증명으로 Travis CI 웹 UI에서 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