refactor: 문서 사람처럼 작성하기

This commit is contained in:
donghyeon-ka
2026-09-22 16:24:58 +09:00
parent 1549e62b5e
commit f3bed70991
158 changed files with 4381 additions and 832 deletions
@@ -1,7 +1,7 @@
---
kind: REFERENCE
slug: a-config-file-does-not-mean-the-same-thing-on-two-distros
title: 같은 설정 파일이 두 배포판에서 같은 뜻이 아니다 — 옮기기 전에 세 가지를 본다
title: 배포판이 다르면 같은 설정 파일도 그대로 옮기지 않는다
topic: lab-environment-build
topicName: 실험대 환경 구성
project: virtualization
@@ -18,9 +18,9 @@ source:
- final/document.md#209-nginx-keycloak-lab-conf-스티키-스위치와-신뢰-경계
---
# 같은 설정 파일이 두 배포판에서 같은 뜻이 아니다 — 옮기기 전에 세 가지를 본다
# 배포판이 다르면 같은 설정 파일도 그대로 옮기지 않는다
설정 파일을 배포판이 다른 기계로 옮기기 전에 셋을 본다. 그 지시어가 대상의 판올림에 있는가, 패키지가 기본으로 켜 둔 것과 충돌하지 않는가, 그 배포판이 그 관례를 갖고 있는가. 이 실험대의 함정 셋이 전부 여기 걸렸다.
설정 파일을 다른 배포판으로 옮길 때는 해당 지시어를 그 버전에서 지원하는지, 패키지 기본 설정과 충돌하지 않는지, 같은 디렉터리 구조와 패키징 관례를 사용하는지 확인한다. 이 실험대에서도 같은 파일을 그대로 옮겼을 때 이 세 조건에서 차이가 발생했다.
## 같은 파일명이 같은 기능을 뜻하지 않는 이유
@@ -32,7 +32,7 @@ source:
### 1. 그 지시어가 대상의 판올림에 있는가
`http2 on;` 은 nginx 1.25.1 이상이다. Arch 에서 쓰던 설정을 Debian 12 게스트로 그대로 옮기면 `unknown directive "http2"` 가 나면서 설정 전체가 죽는다.
`http2 on;`은 nginx 1.25.1 이상에서 사용하는 지시어다. 이를 지원하지 않는 Debian 12의 nginx에 같은 설정을 적용하면 `unknown directive "http2"` 오류가 발생하고 설정 검사가 실패한다.
없다는 것을 확인하는 데서 멈추면 규칙이 답을 내지 않는다. 양쪽에서 도는 형태가 무엇인지까지 찾는다. `listen 443 ssl http2;` 형태는 1.22 와 1.30 양쪽에서 다 돈다.
@@ -14,7 +14,7 @@ source:
# 단계별 구축 문서는 작성 시점이 아니라 실행 순서로 검증한다
구축 가이드는 1단계의 환경에서 시작해 실행 순서로 검증한다. 단계마다 그 시점에 리소스가 이미 있는지와 그 명령을 어느 기계에서 치는지를 따로 본다. 기반 7단계 가이드를 순서대로 따라가자 결함 여섯이 나왔고, 틀린 명령은 하나도 없었다.
구축 문서는 빈 환경에서 첫 단계부터 순서대로 실행해 봐야 한다. 각 단계에서 필요한 리소스가 이미 만들어져 있는지, 명령을 어느 머신에서 실행해야 하는지까지 함께 확인한다. 이 실험대의 7단계 가이드는 명령 자체의 문법 오류보다 실행 순서와 실행 위치에서 여섯 가지 문제가 드러났다.
## 문장이 맞아도 순서가 틀릴 수 있다