명령어
Docker 이미지와 단독 실행 바이너리는 같은 빌드를 구동합니다. 이 문서는 그 둘 모두에 대한 참고서입니다. 무엇을 실행할 수 있고, 무엇을 전달할 수 있으며, 환경에서 무엇을 읽는지를 다룹니다.
작업 디렉터리
Wikven은 디렉터리 하나를 기준으로 동작하고, 나머지는 모두 거기서 파생됩니다:
<workdir>/src- 여러분의 위키텍스트, 이미지,
.wikven.yaml. 읽기만 하며, 번역 도우미를 쓸 때를 빼고는 쓰지 않습니다. <workdir>/dist- 빌드된 사이트. 빌드가 시작될 때마다 비워집니다.
<workdir>/.cache- 일회용 데이터베이스와 MediaWiki의 임시 공간. 여러분의 사이트에 속하는 것은 없으며, 빌드 사이에 지워도 됩니다.
Docker 이미지는 작업 디렉터리가 /workspace이고, 그래서 빌드가 src와 dist를 그 아래에 마운트합니다. 바이너리는 현재 디렉터리를 씁니다. 어느 쪽이든 WIKVEN_WORKDIR이 이를 덮어씁니다.
build
src/를 dist/로 빌드합니다. 이미지의 기본 명령이므로 Docker 쪽은 인자가 필요 없습니다:
wikven build
docker run --rm \
-v "$(pwd)/src:/workspace/src" \
-v "$(pwd)/dist:/workspace/dist" \
ghcr.io/chaotic-ground/wikven
옵션은 없습니다. 빌드에 알려 줄 수 있는 것은 모두 .wikven.yaml 파일에 있습니다. 실패한 빌드는 0이 아닌 값으로 끝나며 어느 문서나 단계에서 실패했는지 알려 줍니다.
serve
이미 빌드된 dist/를 로컬 미리보기용으로 8080 포트에서 제공합니다. 빌드는 하지 않으므로 build를 먼저 실행하십시오.
이것은 빌드 결과를 자기 컴퓨터에서 들여다보기 위한 것이지 사이트를 발행하는 수단이 아닙니다. 두 제품 모두 기본값으로 모든 인터페이스를 듣고, 그중 하나는 PHP 자신의 웹 서버인데 그 매뉴얼은 "공개 네트워크에서 사용해서는 안 된다", "실서비스 용도가 아니다"라고 적고 있습니다. 독자 앞에 사이트를 내놓으려면 대신 호스트에 dist/를 발행하십시오.
wikven serve
wikven serve --listen 127.0.0.1:3000
docker run --rm -p 8080:8080 \
-v "$(pwd)/dist:/workspace/dist" \
ghcr.io/chaotic-ground/wikven serve
--listen은 바이너리만 받습니다. 컨테이너는 안에서 항상 8080을 듣고, 바깥 포트는 Docker 자신의 -p로 정합니다.
두 제품은 각자 이미 가진 서버로 제공하며, 그 둘은 같은 서버가 아닙니다. 이미지는 HTTP 서버가 들어 있지 않은 PHP 런타임이고, 그 선택이 1.5GB 대신 873MB를 만듭니다. 그래서 PHP 자신이 들고 다니는 서버로 제공합니다. 바이너리는 PHP를 품은 웹 서버인 FrankenPHP이므로, 자기를 이루는 그 서버로 제공합니다.
둘은 같은 주소에 답하고, 둘 다 내보낸 파일만 제공하며 그 밖의 것은 제공하지 않습니다. 파일에 대해 말하는 내용은 양쪽 다 표준을 지키며, 표준은 같은 것을 달리 말할 여지를 남겨 둡니다. 그러니 어느 쪽 미리보기든 곧 발행할 그 사이트를 보여 줍니다.
스타일시트가 한쪽에서는 text/css; charset=UTF-8로, 다른 쪽에서는 text/css; charset=utf-8로 옵니다. HTTP는 charset을 대소문자 구분 없이 읽으므로 둘은 같은 인코딩을 가리킵니다.
translate
번역하기 뒤에 있는 네 가지 도우미입니다. 소스 트리를 대상으로 동작하며 아무것도 빌드하지 않고 끝납니다.
두 제품 모두에 있습니다. 이미지는 마운트된 소스 트리를, 바이너리는 작업 디렉터리를 대상으로 실행하며, 아래 두 형태의 차이는 그것뿐입니다.
translate mark- 소스 문서에서 아직 표시되지 않은 단위에
<!--T:n-->표시자를 넣습니다. 이미 있는 번호는 유지하므로 다시 실행해도 안전합니다. translate scaffold <언어>- 번역해 넣을 골격으로, 모든 원본 단위에 대해 빈 표시자를
<Page>/<언어>.wikitext에 씁니다. 이미 번역한 것은 유지합니다. translate stamp- 당신이 읽은 번역 하나에 대해, 그 단위들이 어느 원본 판을 보고 쓰였는지 기록합니다.
translate check- 망가진 원본 문서와, 오래되었거나 빠진 번역을 보고합니다. 아무것도 쓰지 않습니다.
mark와 scaffold는 파일 하나를 받거나, 소스 디렉터리 아래 모든 문서를 대상으로 하는 --all을 받습니다. 이 둘이 쓰는 내용은 원본에서 유도되므로, 트리를 훑는 것이 파일을 지목하는 것보다 더 말하는 바가 없습니다. stamp는 파일 하나만 받고 --all이 없습니다. 이것이 쓰는 것은 도구가 유도할 수 있는 무엇이 아니라 당신의 읽기이고, 트리 전체를 한 번에 읽는 사람은 없기 때문입니다. check는 둘 다 받지 않고, 언제나 찾을 수 있는 모든 문서를 읽습니다. mark, scaffold, stamp는 소스에 씁니다. Docker에서는 쓰기 가능하게 마운트하고, 바이너리는 그 자리에서 바로 고칩니다. check는 읽기만 합니다.
wikven translate mark --all
wikven translate scaffold ko "Getting Started.wikitext"
wikven translate check --gate
docker run --rm -v "$(pwd)/src:/workspace/src" \
ghcr.io/chaotic-ground/wikven translate mark --all
docker run --rm -v "$(pwd)/src:/workspace/src" \
ghcr.io/chaotic-ground/wikven translate scaffold ko "Getting Started.wikitext"
docker run --rm -v "$(pwd)/src:/workspace/src:ro" \
ghcr.io/chaotic-ground/wikven translate check --gate
check는 두 가지를 더 받습니다:
--gate- 원본 문서가 망가졌을 때 0이 아닌 값으로 끝냅니다. 오래되었거나 빠진 번역은 어느 쪽이든 보고되지만 실행을 실패시키지는 않습니다. 번역은 영어 문서를 고친 사람의 몫이 아니기 때문입니다.
--path-prefix <접두사>- 보고되는 파일 이름 앞에 접두사를 붙여, 컨테이너 안의 경로가 아니라 저장소의 경로로 읽히게 합니다.
환경 변수
WIKVEN_WORKDIR- 위에서 설명한 작업 디렉터리. 이미지에서는
/workspace, 바이너리에서는 현재 디렉터리가 기본값입니다. SOURCE_DATE_EPOCH- 빌드가 자기 내용이 쓰였다고 밝힐 유닉스 시각으로, reproducible-builds 관례를 따릅니다. 빌드는 시계를 그 값에 얼린 채 실행되므로 출력의 모든 시각이 일정합니다. 설정하지 않으면 고정된 날짜를 씁니다. 매번 움직이는 날짜보다 틀렸더라도 움직이지 않는 쪽이 감당하기 쉽기 때문입니다. bake 액션은 빌드 중인 커밋의 시각으로 설정합니다.
WIKVEN_FETCH_DIRWikvenRepositories가 고정한 확장 기능과 스킨을 어디에 두어 둘지. 컨테이너는 자기가 받아온 사본과 함께 버려지므로 다음 빌드가 같은 호스트에 같은 태그를 다시 요청합니다. 실행보다 오래 남는 디렉터리를 — 도커에서는 마운트를 — 지정하면 빌드가 거기 있는 것을 다시 쓰고, 고정이 옮겨진 것만 새로 받아옵니다. bake 액션은 이 일을 대신 해 줍니다.WIKVEN_BUILD_JOBS- 스킨 렌더링을 몇 개까지 나란히 돌릴지. 설정하지 않으면 쓸 수 있는 프로세서 하나당 하나씩 쓰는데, 호스트가 아니라 컨테이너에 허용된 몫을 따릅니다. 나란히 돌릴 렌더링이 있는 것은 스킨을 둘 이상으로 빌드한 사이트뿐입니다. 메모리가 부족한 기계이거나 로그를 순서대로 보고 싶다면
1로 두어 빌드를 차례대로 진행시키십시오.
셋이 더 있는데, 모두 손으로 설정해서 쓸 일은 없습니다. 그중 둘은 빌드가 스킨 하나의 렌더링을 실행하려고 스스로에게 설정하는 것들입니다. WIKVEN_BUILD_SKIN은 그 스킨의 이름이고, WIKVEN_BUILD_DB_DIR은 그 렌더링이 쓸 데이터베이스 사본의 위치입니다. 렌더링들이 나란히 돌아가는데 SQLite는 한 번에 하나만 쓸 수 있기 때문입니다. WIKVEN_BUILD_DB_DIR은 WIKVEN_BUILD_SKIN이 설정되어 있을 때만 읽히고, 그 WIKVEN_BUILD_SKIN을 손으로 설정하면 빌드가 아무것도 채워지지 않은 위키를 렌더링하는 과정이 되어 빈 사이트를 씁니다. 나머지 하나는 WIKVEN_RUNTIME으로, 독립 실행 바이너리가 자신이 실행하는 모든 명령에 설정합니다. 바이너리가 무엇으로 컴파일되었는지를 담으며, 빌드는 그것을 자신이 쓰는 라이선스 문서에 올립니다.
GitHub Actions
복합 액션 둘이 GitHub Actions 러너에서 이미지를 실행하므로, 워크플로에 docker 명령을 직접 적을 일이 없습니다. bake 액션은 소스 트리를 굽는데, 워크플로에서 사이트를 게시하는 방법이 그것입니다. 완전한 워크플로는 배포하기에 있습니다. check-translations 액션은 풀 리퀘스트에서 translate check를 실행해 발견한 것을 보고하며, 번역하기가 그것을 설명합니다. 각 액션이 받는 입력과 기본값은 액션 자신의 action.yml에 설명되어 있으며, 위 링크가 그 파일을 엽니다.