Docker에서 LiteFS 시작하기 (Getting Started with LiteFS in Docker)
이 가이드는 Docker를 사용해 LiteFS 클러스터를 구성하고 실행하는 과정을 안내해 드려요. 이 가이드를 참고해 거의 그대로 Linux 서버에서도 LiteFS를 실행할 수 있어요. 앱을 Fly.io에서 실행할 계획이라면 Fly.io에서 LiteFS 시작하기를 대신 확인해 보세요.
출처: 문서
본문
개요
이 가이드는 Docker를 사용해 LiteFS 클러스터를 구성하고 실행하는 과정을 안내해 드려요. 거의 그대로 Linux 서버에서 LiteFS를 실행할 때도 이 가이드를 참고할 수 있어요. 앱을 Fly.io에서 실행할 계획이라면 Fly.io에서 LiteFS 시작하기를 대신 확인해 주세요.
로컬에서 실행할 수 있는 docker-compose 설정을 포함한 완전하고 실제로 작동하는 LiteFS 앱 예제는 litefs-example 저장소에서 확인할 수 있어요.
Dockerfile에 LiteFS 추가
의존성
litefs 바이너리는 자체적으로 완결적이지만, LiteFS가 로컬 파일 시스템을
마운트할 수 있도록 fuse3 라이브러리를 설치해야 해요. Consul에 연결한다면
ca-certificates도 필요하고, 거의 확실히 sqlite를 설치하고 싶을 거예요.
설치는 패키지 관리자에 따라 다르지만, alpine 기반 또는 debian 기반 이미지용으로
Dockerfile에 추가할 수 있는 줄은 다음과 같아요:
# for alpine-based images
RUN apk add ca-certificates fuse3 sqlite
# for debian/ubuntu-based images
RUN apt-get update -y && apt-get install -y ca-certificates fuse3 sqlite3
LiteFS 설치
LiteFS는 애플리케이션과 함께 컨테이너 안에서 실행되도록 만들어졌어요. 공식 Docker 이미지에서 litefs 바이너리를 복사해 가져올 수 있어요:
COPY --from=flyio/litefs:0.5 /usr/local/bin/litefs /usr/local/bin/litefs
Docker에서 USER 명령으로 사용자를 바꾸는 대신 LiteFS를 root로 실행하는 것이 좋아요. 애플리케이션을 다른 사용자로 실행해야 한다면 su 명령을 사용해 애플리케이션을 비-root 사용자로 실행하세요.
예제는 litefs-example 저장소의 the example Dockerfile을 확인하세요.
LiteFS 설정
LiteFS의 대부분의 설정 옵션은 litefs.yml이라는 YAML 설정 파일로 지정돼요. 이 파일은 일반적으로 /etc/litefs.yml에 두지만 -config 플래그로 경로를 바꿀 수 있어요.
litefs.yml 파일이 어떻게 생겼는지 완전한 예제를 확인할 수 있어요.
파일 시스템
먼저 LiteFS가 파일 시스템을 어디에 마운트하고 내부 데이터를 어디에 저장할지 알려주는 두 필드를 설정해 보세요.
# This directory is where your application will access the database.
fuse:
dir: "/litefs"
# This directory is where LiteFS will store internal data.
# You must place this directory on a persistent volume.
data:
dir: "/var/lib/litefs"
리스(Lease) 설정
LiteFS는 특정 시점에 단 하나의 노드만 primary가 될 수 있게 해요. primary 노드는 데이터베이스에 데이터를 쓸 수 있는 유일한 노드예요. 다른 노드는 replica라고 하며 읽기 전용 복사본을 제공해요.
primary는 분산 리스를 사용해 결정돼요. 이 가이드에서는 구성이 간단한 static lease를 사용할 거예요.
primary 노드와 replica 노드에는 약간 다른 두 가지 설정이 필요해요.
특히 primary 노드 구성에는 lease.candidate: true를, replica 노드 구성에는
lease.candidate: false를 사용하세요.
primary 노드의 litefs.yml 파일 예시는 다음과 같아요:
lease:
# Required. Must be either "consul" or "static".
type: "static"
# Required. The URL for the primary node's LiteFS API.
# Note: replace `primary` with the appropriate hostname for your primary node!
advertise-url: "http://primary:20202"
# Specifies whether the node can become the primary. If using
# "static" leasing, this should be set to true on the primary
# and false on the replicas.
# Note: update this to `false` on the replica nodes!
candidate: true
replica 노드 구성은 lease.candidate를 false로 설정한 것만 빼고 동일해야 해요.
LiteFS 실행
LiteFS를 시작하는 데 사용하는 주 명령은 litefs mount 명령이에요. 이 명령은 FUSE 파일 시스템을 마운트한 다음 LiteFS 노드들이 서로 통신할 API 서버를 시작해요. 이것을 Dockerfile의 ENTRYPOINT로 사용할 수 있어요:
ENTRYPOINT litefs mount
슈퍼바이저로 실행
LiteFS는 단독으로 실행되거나 애플리케이션을 위한 간단한 슈퍼바이저 프로세스 역할을 할 수 있어요. 슈퍼바이저로 실행하면 LiteFS가 클러스터에 연결한 후에 애플리케이션 시작을 기다릴 수 있어요.
설정의 exec 섹션에서 명령을 하나 이상 지정할 수 있어요. lease.promote를 true로 설정하면 후보(candidate) 노드에서만 마이그레이션 스크립트를 실행하도록 지정할 수 있어요. 즉, 후보가 자동으로 primary로 승격(promote)되어 마이그레이션을 실행한다는 뜻이에요.
exec:
# Only run migrations on candidate nodes.
- cmd: "rails db:migrate"
if-candidate: true
# Then run the application server on all nodes.
- cmd: "rails server"
Docker 컨테이너 권한
LiteFS는 FUSE 파일 시스템을 사용하며, 이를 실행하려면 추가 권한이 필요해요.
빠르게 작동시키는 가장 쉬운 방법은 --privileged로 실행하는 거예요:
docker run --privileged ...
보안 요구 사항에 따라 [FUSE 문서][]를 확인하고 권한을 줄일 수 있는지 결정해 보세요!
LiteFS 인스턴스 테스트
LiteFS가 마운트되면 SQLite 클라이언트나 sqlite3 CLI를 사용해 마운트 디렉터리의 데이터베이스와 상호작용할 수 있어요:
sqlite3 /litefs/my.db
LiteFS는 마운트 루트의 파일만 허용하며 현재 서브디렉터리는 지원하지 않아요.
데이터베이스 가져오기
기존 데이터베이스가 있다면 litefs import 명령으로 가져올 수 있어요.
litefs import -name my.db /path/to/database
자세한 내용은 litefs import 문서를 참조하세요.
데이터베이스를 제자리에 복사하기 위해 cp를 사용하지 마세요.
primary 노드로 쓰기 설정
LiteFS는 분산 시스템이므로 일반 SQLite와 몇 가지 차이점이 있어요. LiteFS는 모든 쓰기가 primary 노드에서 발생해야 하므로 애플리케이션이 쓰기 요청을 현재 primary로 리디렉션해야 해요. 또한 primary에 쓰기를 실행한 후 변경 사항이 해당 replica에 전파되기 전에 replica에서 읽는 것도 가능해요.
대부분의 웹 애플리케이션에서는 애플리케이션이 GET 요청에서 쓰기 작업(INSERT, UPDATE 등)을 피하는 규칙을 따른다면 로드 밸런서 설정을 활용해 쓰기를 primary 노드로 라우팅할 수 있어요.
쓰기를 primary 노드로 라우팅하고 다른 요청은 primary와 replica 노드 사이에서 로드 밸런싱하는 sample nginx config를 확인할 수 있어요.