docs(operations): nginx 설정 예시를 지우고 호스트가 지킬 조건만 남긴다
문제: docs/operations/release-cache-rollback.md에 nginx 설정이 통째로 있다(보안 헤더 snippet과 server 블록, 「Example: nginx on a single server」 절). CI는 그것을 돌리지 않고, 호스트 설정은 개발 repo의 일이 아니다(소유자 2026-11-07). ci-quality-gates.md의 runner 요구 절에도 호스트를 바꾸는 절차(AppArmor profile 본문, sysctl 명령)가 있다. 고른 방법: - nginx 절을 지우고 같은 문서에 「운영 환경이 지켜야 할 조건」 19개를 문장으로 쓴다. 조건마다 재는 쪽을 적었다: FE-GATE-019가 잰다(live 모드, 값은 config/hosting/*.json) / 아무도 재지 않는다. 백엔드와 같은 절 이름·같은 언어(한국어)다. - 지운 설정을 한 줄씩 대조했다. snippet 6줄 → 6(값), always → 7; listen 443 ssl·server_name·인증서 → 1; http2 → 2; gzip·gzip_types → 10, gzip_vary → 11; root current와 원자적 symlink 전환 → 17; index.html → 3·6; try_files fallback → 4·6; config.json· release-manifest.json → 5·6; 공유 /assets/·기간으로 지우기 → 18; 없는 청크 404 → 12; immutable → 8; service-worker.js → 14·15; .map 404 → 16; Cache-Control에 always 없음 → 13; 기본 base path / → 1; mime.types에 맡긴 Content-Type → 3·5·9·14. 롤백 때 동작은 19. - static-delivery.md의 "nginx example" 문장은 이 절을 가리키게 고친다. - ci-quality-gates.md: runner 요구(바이너리, systemd, cgroup, 비특권 user namespace)는 게이트가 runner에 요구하는 조건이라 남긴다. 고치는 방법 목록과 AppArmor profile 본문만 지우고 "고치는 방법은 scripts/check-system-test-prerequisites.ts가 실패할 때 출력한다"로 바꾼다. 그 스크립트가 같은 세 방법을 출력한다. 버린 대안: nginx 설정을 project-infra나 cicd-platform으로 복사하기. 아무도 시험하지 않는 복사본이 다른 repo에 생긴다(백엔드도 지웠다). 위험·한계: 아무도 재지 않는 부분이 있는 조건이 11개다(7, 8의 나머지 파일, 10의 나머지 청크와 CSS·JSON·SVG, 11, 12, 13, 15, 16의 호스트 쪽, 17의 전환 도중, 18, 19의 호스트 쪽). 지운 nginx 예시도 CI가 돌리지 않았으니 재지 않는 범위는 넓어지지 않았다. AppArmor profile 본문은 이 repo에서 없어진다. 필요하면 runner를 만드는 쪽 인프라 repo가 갖는다. 검증: git grep -n '^```nginx' 0줄. desktop(이 커밋 30a379f 트리, 로그 ~/l1-layout-cleanup-logs/): verify:documentation PASS_SCOPED(새 절의 경로·script 이름·FE-GATE ID와 static-delivery.md의 링크 포함), test:unit 3091 tests 통과. Refs: design-docs repo-structure/04-frontend-layout.md 4절 I-3·I-4·I-11
This commit is contained in:
@@ -56,7 +56,7 @@ Serve JavaScript compressed (gzip, brotli or zstd). The bundle budget counts
|
||||
gzip bytes; uncompressed, the initial JavaScript is about three times larger.
|
||||
Both premises are declared in `config/hosting/cache-policy.json`
|
||||
(`transport.alpnProtocols`, `hashedAsset.contentEncodings`), and the live probe
|
||||
of FE-GATE-019 fails a host that does not meet them (review 1103/13-02). The
|
||||
nginx example in
|
||||
[`release-cache-rollback.md`](../operations/release-cache-rollback.md) turns
|
||||
both on.
|
||||
of FE-GATE-019 fails a host that does not meet them (review 1103/13-02). Every
|
||||
condition the host has to meet, and what checks each one, is in 「운영 환경이
|
||||
지켜야 할 조건」 in
|
||||
[`release-cache-rollback.md`](../operations/release-cache-rollback.md#운영-환경이-지켜야-할-조건).
|
||||
|
||||
@@ -218,26 +218,9 @@ sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로
|
||||
namespaces"와 bwrap의 stderr, 위 sysctl 값, 고치는 방법을 적고 exit 1로
|
||||
멈춘다. 전에는 이 검사가 PASS를 낸 뒤 provider 테스트가 bwrap 원문 오류로
|
||||
실패했다(2026-11-05 desktop에서 114건 중 18건).
|
||||
- 고치는 방법은 셋 중 하나다. 호스트의 보안 설정을 바꾸는 일이므로 호스트
|
||||
소유자가 고른다.
|
||||
1. `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor profile을 둔다. Ubuntu
|
||||
문서가 안내하는 형태는 아래와 같다. `/etc/apparmor.d/bwrap`에 두고
|
||||
`sudo apparmor_parser -r /etc/apparmor.d/bwrap`으로 읽게 한다.
|
||||
2. 직접 관리하는 호스트라면 sysctl
|
||||
`kernel.apparmor_restrict_unprivileged_userns=0`으로 제한을 끈다. 이 설정이
|
||||
없는 커널에서는 `kernel.unprivileged_userns_clone=1`이 같은 역할이다.
|
||||
3. 비특권 user namespace를 허용하는 다른 runner에서 FE-GATE-013과 provider
|
||||
job을 돌린다.
|
||||
|
||||
```text
|
||||
abi <abi/4.0>,
|
||||
include <tunables/global>
|
||||
|
||||
profile bwrap /usr/bin/bwrap flags=(unconfined) {
|
||||
userns,
|
||||
include if exists <local/bwrap>
|
||||
}
|
||||
```
|
||||
- 고치는 방법은 `scripts/check-system-test-prerequisites.ts`가 실패할 때
|
||||
출력한다. 호스트의 보안 설정을 바꾸는 일이므로 호스트 소유자가 고른다.
|
||||
호스트를 바꾸는 설정 파일과 명령은 runner를 만드는 쪽의 인프라 repo가 갖는다.
|
||||
|
||||
각 provider는 고유한 collected user scope에서 실행된다. Supervisor는 실행 전에
|
||||
실제 cgroup membership과 `memory.max=1073741824`, `memory.swap.max=0`,
|
||||
|
||||
@@ -112,83 +112,6 @@ declaration in `config/hosting/cache-policy.json` in the same change that
|
||||
groups its initial chunks ("초기 청크 수와 HTTP/1.1" in
|
||||
[`performance-evidence.md`](performance-evidence.md)).
|
||||
|
||||
### Example: nginx on a single server
|
||||
|
||||
Written by hand for the default base path `/`; nothing in CI runs it. The live
|
||||
probe above is what checks the host. `add_header` in a `location` replaces the
|
||||
ones inherited from `server`, so the security headers
|
||||
(`config/hosting/security-headers.json`) are an include repeated in each block.
|
||||
|
||||
```nginx
|
||||
# /etc/nginx/snippets/frontend-security-headers.conf
|
||||
add_header Content-Security-Policy "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests" always;
|
||||
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
|
||||
add_header X-Frame-Options "DENY" always;
|
||||
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
|
||||
```
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
# nginx 1.25.1 and later; before it, `listen 443 ssl http2;`.
|
||||
http2 on;
|
||||
server_name app.example.com;
|
||||
# ssl_certificate / ssl_certificate_key ...
|
||||
|
||||
# The bundle budget counts gzip bytes, and FE-GATE-019 fails an
|
||||
# uncompressed entry script (cache-policy.json `hashedAsset`). nginx
|
||||
# compresses only text/html unless gzip_types names the rest.
|
||||
gzip on;
|
||||
gzip_vary on;
|
||||
gzip_types text/javascript application/javascript application/json text/css image/svg+xml;
|
||||
|
||||
# The active release directory. Switch it with an atomic symlink rename.
|
||||
root /srv/frontend/current;
|
||||
|
||||
# index.html, and every app route through the fallback below.
|
||||
location = /index.html {
|
||||
add_header Cache-Control "no-cache";
|
||||
include snippets/frontend-security-headers.conf;
|
||||
}
|
||||
location / {
|
||||
try_files $uri /index.html;
|
||||
include snippets/frontend-security-headers.conf;
|
||||
}
|
||||
|
||||
location = /config.json {
|
||||
add_header Cache-Control "no-store";
|
||||
include snippets/frontend-security-headers.conf;
|
||||
}
|
||||
location = /release-manifest.json {
|
||||
add_header Cache-Control "no-store";
|
||||
include snippets/frontend-security-headers.conf;
|
||||
}
|
||||
|
||||
# Hashed files of every retained release in one directory (names never
|
||||
# collide). Prune by age, not on switch. A missing chunk is a 404, never
|
||||
# index.html: an old tab has to see the failure to reload once (FE-RB-002).
|
||||
location /assets/ {
|
||||
root /srv/frontend/shared;
|
||||
add_header Cache-Control "public, max-age=31536000, immutable";
|
||||
try_files $uri =404;
|
||||
}
|
||||
|
||||
# Only when the build ships a worker (cache-policy.json `serviceWorker`).
|
||||
location = /service-worker.js {
|
||||
add_header Cache-Control "no-cache";
|
||||
try_files $uri =404;
|
||||
}
|
||||
|
||||
location ~ \.map$ {
|
||||
return 404;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`Cache-Control` has no `always`, so a 404 is never stored as immutable.
|
||||
|
||||
FE-GATE-019 is therefore a production-stage gate (`production_gate` job,
|
||||
`PROD_PROMOTION_READY`). It runs after `promotion` and after the `deployment`
|
||||
job. That job is the project's deployment slot and is empty in this
|
||||
@@ -204,6 +127,79 @@ active (the rolling window modeled in `tests/release/release-fixture.ts`).
|
||||
Size it to the longest session the product supports; a tab older than that
|
||||
depends on the reload-once recovery (FE-RB-002).
|
||||
|
||||
## 운영 환경이 지켜야 할 조건
|
||||
|
||||
이 repo는 호스트 설정 파일(nginx 등)을 두지 않는다(2026-11-07 소유자 결정). 그 파일은
|
||||
서비스를 배포하는 쪽의 인프라 repo가 갖는다. 그 호스트가 지켜야 할 조건은 아래다. 값의
|
||||
정본은 `config/hosting/cache-policy.json`과 `config/hosting/security-headers.json`이다.
|
||||
|
||||
조건마다 끝에 누가 재는지 적었다.
|
||||
|
||||
- **FE-GATE-019가 잰다**: `verify:hosting-headers`의 live 모드가 배포된 호스트에 요청해
|
||||
확인한다. 배포 슬롯이 이 release를 배포했을 때만 돈다. 슬롯이 비면 호스트를 재지 않고
|
||||
`UNVERIFIED`로 끝난다(위 단락).
|
||||
- **아무도 재지 않는다**: 계약 파일에도 검사에도 없다. 호스트를 맡은 쪽이 직접 확인한다.
|
||||
|
||||
**주소와 연결**
|
||||
|
||||
1. 앱은 HTTPS origin의 루트(`/`)에서 내보낸다. 인증서가 유효하고, 어느 surface도 그
|
||||
origin 밖으로 redirect하지 않는다. — FE-GATE-019가 잰다. `HOSTING_BASE_URL`은 경로 없는
|
||||
HTTPS 루트 URL이어야 하고, surface마다 최종 origin을 본다.
|
||||
2. TLS에서 HTTP/2를 맺는다(ALPN `h2`). — FE-GATE-019가 잰다(`transport.alpnProtocols`).
|
||||
|
||||
**surface별 응답** (surface: probe가 요청하는 경로 하나)
|
||||
|
||||
3. `index.html`은 `Cache-Control: no-cache`와 `text/html`로 준다. — FE-GATE-019가
|
||||
`/`로 잰다(`surfaces.index`).
|
||||
4. 빌드에 파일이 없는 모든 앱 경로(새로 고침, 북마크, 공유 링크)에는 200으로 그 release의
|
||||
`index.html`을 3과 같은 헤더로 준다(SPA fallback). — FE-GATE-019가 잰다
|
||||
(`surfaces.appRoute`, `/__probe/deep-link`).
|
||||
5. `config.json`과 `release-manifest.json`은 `Cache-Control: no-store`와
|
||||
`application/json`으로 준다. — FE-GATE-019가 잰다(`surfaces.runtimeConfig`,
|
||||
`surfaces.releaseManifest`).
|
||||
6. 3~5의 응답에는 `config/hosting/security-headers.json`의 헤더를 모두 그 값 그대로
|
||||
붙인다. — FE-GATE-019가 잰다(`securityHeaders`가 참인 surface).
|
||||
7. 오류 응답(404, 5xx)에도 6의 보안 헤더를 붙인다. — 아무도 재지 않는다. probe는 200
|
||||
응답만 본다.
|
||||
8. `assets/` 아래 hashed 파일은
|
||||
`Cache-Control: public, max-age=31536000, immutable`로 준다. — 진입 스크립트 하나는
|
||||
FE-GATE-019가 잰다(`surfaces.hashedAsset`). 나머지 파일의 `Cache-Control`은 아무도 재지
|
||||
않는다.
|
||||
9. hashed 파일은 redirect 없이 200으로, 확장자에 맞는 `Content-Type`으로 준다. —
|
||||
FE-GATE-019가 확장자마다 첫 파일 하나를 잰다(위 단락, `CACHEABLE_ASSET_CONTENT_TYPES`).
|
||||
10. JavaScript는 압축해서 보낸다(`br`, `gzip`, `zstd` 중 하나). 번들 예산이 gzip 크기를
|
||||
센다. — 진입 스크립트는 FE-GATE-019가 잰다(`hashedAsset.contentEncodings`). 나머지
|
||||
청크는 아무도 재지 않는다. CSS·JSON·SVG 압축은 예산이 기대지 않고, 아무도 재지 않는다.
|
||||
11. 압축한 응답에는 `Vary: Accept-Encoding`을 붙인다. 공유 캐시가 압축한 본문을 압축을 받지
|
||||
못하는 클라이언트에 주지 않게 한다. — 아무도 재지 않는다.
|
||||
12. 없는 hashed 파일을 요청하면 404로 답한다. `index.html`로 대신 답하지 않는다. 옛 탭은
|
||||
그 실패를 봐야 한 번 새로 고친다(FE-RB-002). — 아무도 재지 않는다.
|
||||
13. 404 같은 오류 응답에는 `immutable` 캐시 헤더를 붙이지 않는다. 붙이면 브라우저와 CDN이
|
||||
그 실패를 hashed 파일처럼 오래 저장한다. — 아무도 재지 않는다.
|
||||
14. 빌드가 Service Worker를 실으면 `/service-worker.js`는 redirect 없이 200,
|
||||
`Cache-Control: no-cache`, JavaScript `Content-Type`으로 준다. — FE-GATE-019가 잰다
|
||||
(`surfaces.serviceWorker`).
|
||||
15. 빌드가 worker를 싣지 않으면 `/service-worker.js`는 404로 답한다. SPA fallback이
|
||||
`index.html`로 대신 답하지 않는다(아래 「Service Worker steps」 4). — 아무도 재지 않는다.
|
||||
worker가 없는 빌드에서는 probe가 이 경로를 요청하지 않는다.
|
||||
16. 소스맵을 공개하지 않는다. — release의 `dist`에 `.map`이 없는지는 FE-GATE-019가
|
||||
잰다(`surfaces.sourceMap`). 호스트가 `.map` 요청을 404로 막는지는 아무도 재지 않는다.
|
||||
|
||||
**배포와 롤백**
|
||||
|
||||
17. release 묶음(`index.html`, `config.json`, `release-manifest.json`,
|
||||
`service-worker.js`)을 한 번에 바꾼다. 옛 파일과 새 파일이 섞여 보이는 순간이 없다. —
|
||||
바꾼 뒤 `release-manifest.json`·`config.json`·`index.html`이 이 release의 것인지는
|
||||
FE-GATE-019가 잰다. 바꾸는 도중에 섞이지 않는지는 아무도 재지 않는다.
|
||||
18. 지난 release의 hashed 파일을 release를 바꿀 때 지우지 않는다. 이름이 겹치지 않으므로 한
|
||||
곳에 모아 둘 수 있고, 보관 기간(위 단락)이 지난 것만 지운다. — 호스트에서는 아무도
|
||||
재지 않는다. 템플릿 안의 호스트 모형(`tests/release/release-fixture.ts`)은
|
||||
`tests/release/old-asset-reachability.test.ts`가 시험한다.
|
||||
19. 롤백은 지난 release의 묶음(17)을 그대로 다시 내보낸다. 옛 commit을 다시 빌드하거나
|
||||
HTML만 바꾸지 않는다(맨 위 단락). 18 덕분에 그 release의 hashed 파일은 남아 있다. —
|
||||
되돌릴 release의 묶음과 파일은 바꾸기 전에 `drill:runbook -- FE-RB-005`가 확인한다.
|
||||
호스트에서 바꾼 결과는 아무도 재지 않는다. 그 drill은 `UNVERIFIED`로 끝난다(위 단락).
|
||||
|
||||
## Service Worker steps (only when the static selection is not `null`)
|
||||
|
||||
The worker is part of the release tuple: `service-worker.js` comes from the
|
||||
|
||||
Reference in New Issue
Block a user