6. 설치 후 작업

관리자를 만들고, Sandboxed Compiles와 데이터 지속성을 확인하고, Windows에서 Ayakaleaf Pro를 계속 실행합니다.

​

관리자와 첫 번째 프로젝트 만들기

Windows 브라우저에서 http://localhost:8080/launchpad를 열고 첫 번째 관리자 계정을 만든 다음 로그인하세요. 그런 다음 Linux 가이드의 6. 설치 후 작업을 따르되, 예시 URL에서는 포트 8080을 사용하세요.

​

컴파일 확인

로그인 페이지가 작동한다고 해서 별도의 컴파일러 컨테이너가 WSL 데이터 디렉터리에 접근할 수 있다는 것이 증명되지는 않습니다. 빈 프로젝트를 만들고 pdfLaTeX로 다음 main.tex를 컴파일하세요.

\documentclass{article}
\begin{document}
Ayakaleaf Pro on Windows WSL 2.
\end{document}

PDF 미리보기에 텍스트가 표시되어야 합니다. basic 이미지를 사용한다면 필요에 따라 프로젝트 설정에서 TeX Live 2026 Basic을 선택하세요.

XeLaTeX를 선택하고 다음을 테스트하세요.

\documentclass{article}
\usepackage{fontspec}
\begin{document}
Ayakaleaf WSL XeLaTeX sandbox.
\end{document}

두 예시 모두 basic에서 작동합니다. 중국어 문서의 경우 XeLaTeX로 다음을 테스트하기 전에 full처럼 ctex와 필요한 글꼴이 포함된 이미지를 사용하세요. basic에는 이들이 포함되어 있지 않습니다.

\documentclass{ctexart}
\begin{document}
你好，Ayakaleaf Pro。
\end{document}

샌드박스가 사용되는지 확인하려면 컴파일하는 동안 Ubuntu에서 다음을 실행하세요.

docker ps -a --filter ancestor=ghcr.io/ayaka-notes/texlive-basic:2026.1
bin/logs -f clsi

필터에는 선택한 이미지 이름을 사용하세요. 짧은 컴파일은 docker ps가 실행되기 전에 끝날 수 있으며, -a를 사용하면 정리되기 전까지 중지된 컨테이너도 표시됩니다. 컴파일러 컨테이너는 해당 이미지와 Toolkit의 WSL 데이터 디렉터리에서 오는 /compile 바인드 마운트를 사용해야 합니다. 애플리케이션 로그만으로는 PDF 확인을 대신할 수 없습니다.

​

데이터 지속성 확인

Ubuntu의 Toolkit 디렉터리에서 다음을 실행하세요.

bin/stop
bin/start

애플리케이션이 준비될 때까지 기다린 다음 Windows에서 프로젝트를 다시 열고 다시 컴파일하세요. 계정, 소스, 프로젝트 파일이 그대로 남아 있어야 합니다. 기본 실제 데이터는 Ubuntu 안의 ~/ayakaleaf-toolkit/data/에 있습니다. config/와 data/를 모두 보관하세요. Ubuntu 배포판을 제거하거나 등록 취소하면 이들이 삭제될 수 있습니다.

​

인스턴스 가용성 유지

인스턴스를 계속 실행하려면 세 가지가 필요합니다. Windows가 절전 상태로 들어가지 않고, Docker Desktop이 실행되며, 컨테이너가 엔진과 함께 다시 시작되어야 합니다.

Docker Desktop Settings → General에서 Start Docker Desktop when you sign in to your computer를 켜세요. Docker Desktop 설정을 참조하세요. 이 설정은 로그인 전이 아니라 로그인 후에 Docker를 시작합니다. Windows를 다시 시작한 후에는 로그인하고, Docker Desktop이 시작을 마칠 때까지 기다린 다음, Ubuntu를 열어 docker ps와 사이트를 확인하세요.

Docker Desktop의 Resource Saver는 Windows 절전과 별개입니다. 일반적으로 실행 중인 컨테이너가 없을 때만 활성화되며, 실행 중인 애플리케이션, MongoDB, Redis가 이 유휴 상태를 막습니다. WSL 2에서는 공유 WSL VM을 종료하는 대신 Docker 엔진을 일시 중지합니다. 사용자에게 서비스하는 동안 Docker Desktop을 수동으로 Pause하지 마세요. 이 스택을 계속 실행하기 위해 Resource Saver를 비활성화할 필요는 없습니다. Docker의 Resource Saver 문서를 참조하세요.

Toolkit 서비스는 restart: always를 사용합니다. Ubuntu에서 실제 설정을 확인하세요.

docker inspect sharelatex mongo redis --format '{{.Name}} restart={{.HostConfig.RestartPolicy.Name}}'

각 서비스는 always를 보고해야 합니다. Docker가 실행되면 새로 bin/up을 실행하지 않아도 기존 컨테이너를 다시 시작할 수 있습니다. 수동으로 중지한 컨테이너는 직접 시작하거나 엔진을 다시 시작할 때까지 중지된 상태로 유지되며, always를 사용하면 엔진이 다시 시작될 때 컨테이너도 다시 시작될 수 있습니다. Docker의 재시작 정책 동작을 참조하세요.

작업	Ayakaleaf에 미치는 영향
bin/up -d 이후 Ubuntu 터미널 닫기	컨테이너는 분리 모드로 실행되며, 터미널이 컨테이너를 관리하지 않습니다. Docker Desktop과 WSL 환경을 계속 사용할 수 있게 유지하세요
Docker Dashboard 창 닫기	창을 닫아도 Docker Desktop은 시스템 트레이에서 계속 실행됩니다
Quit Docker Desktop 선택	엔진이 중지되고 사이트를 사용할 수 없게 됩니다. 복구하려면 Docker Desktop을 다시 여세요
wsl --shutdown 실행	모든 WSL 배포판이 중지되고 Docker WSL 백엔드가 중단됩니다. Docker Desktop을 다시 시작하고 Ubuntu를 다시 여세요
Windows 절전, 최대 절전 모드 또는 종료	서비스를 사용할 수 없습니다. 화면만 켜 두거나 꺼 두는 것으로는 달라지지 않습니다
bin/stop 실행	데이터를 유지한 채 인스턴스를 중지합니다. 재개하려면 bin/start를 사용하세요

AC 전원에서 장시간 사용하려면 Windows 11 설정 → 시스템 → 전원 및 배터리 → 화면, 절전 및 최대 절전 모드 시간 제한을 여세요(일부 버전에서는 전원 또는 화면 및 절전으로 표시됨). 전원 연결 시 절전 시간 제한을 안 함으로 설정하고, 자동 최대 절전 모드가 구성되어 있다면 비활성화하세요. 디스플레이는 여전히 꺼질 수 있습니다. 노트북의 덮개 동작은 별도의 설정이며, 유휴 절전 시간 제한이 안 함이더라도 덮개를 닫으면 절전 상태가 될 수 있습니다. Windows 전원 설정을 참조하세요.

사이트를 사용하는 동안 일상적인 정리 작업으로 wsl --shutdown을 실행하지 마세요. WSL 설정 변경에 필요하다면 먼저 인스턴스를 중지하고 중단을 계획하세요. 이러한 설정을 사용하면 Windows에서 인스턴스를 계속 실행할 수 있습니다. 로그아웃과 무인 재부팅에도 유지되어야 하는 공유 서비스에는 Linux 가이드를 권장합니다.

​

Docker Desktop 재시작 후 복구 확인

작업을 저장하고 진행 중인 컴파일이 끝나도록 한 후, Docker Desktop의 문제 해결 메뉴에서 Restart Docker Desktop을 선택하세요. 엔진이 준비될 때까지 기다린 다음 Ubuntu에서 확인하세요.

docker ps
curl -I http://localhost:8080/launchpad

Windows에서 기존 프로젝트를 열고 다시 컴파일하세요. 계정과 소스가 여전히 존재하는지 확인하세요.

bin/stop으로 인스턴스를 의도적으로 중지했다면 bin/start를 사용하세요. Docker는 실행 중인데 서비스가 실패한다면 구성을 다시 만들지 말고 해당 서비스의 로그를 읽어 보세요. Windows 업데이트, Docker 업데이트, 정전은 여전히 24시간 설치를 중단시킬 수 있습니다. 백업을 유지하고 계획된 유지 관리 후에는 복구를 확인하세요.

​

일상적인 사용

Windows에서 Docker Desktop을 시작하세요. Ubuntu를 여세요.

cd "$HOME/ayakaleaf-toolkit"

작업	명령
기존 컨테이너 시작	bin/start
데이터를 유지한 채 컨테이너 중지	bin/stop
구성 변경 사항 적용	bin/up -d
상태 확인	bin/docker-compose ps
시작 로그 읽기	bin/docker-compose logs --tail=100 sharelatex
MongoDB 로그 읽기	bin/docker-compose logs --tail=100 mongo
컴파일러 로그 읽기	bin/logs -f clsi

bin/start는 구성 수정 사항을 적용하지 않습니다. config/를 변경한 후에는 bin/up -d를 사용하세요. WSL 배포판을 업그레이드, 이동 또는 제거하기 전에는 데이터 및 백업을 따르세요. 데이터베이스가 쓰는 동안 실제 MongoDB 파일을 복사하는 것은 일관된 백업이 아닙니다.

로컬 사용 시에는 127.0.0.1을 유지하세요. 다른 컴퓨터에 서비스하려면 의도적인 수신 주소, 사이트 URL, Windows 방화벽/네트워크 구성, HTTPS도 필요합니다. OVERLEAF_SITE_URL만 변경해서는 포트가 게시되지 않습니다.

문제가 있다면 문제 해결을 참조하세요.