본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

Mastodon

원문 보기 위키 갱신

Mastodon ↗︎은 인기 있는 fediverse ↗︎ 소프트웨어예요. 이 가이드에서는 새 인스턴스를 만들거나 기존 인스턴스를 마이그레이션할 때, 자체 호스팅 Mastodon 인스턴스의 객체 스토리지로 R2를 구성하는 방법을 설명해 드릴게요.

출처: 문서

본문

새 인스턴스 설정

자체 호스팅 Mastodon 인스턴스는 여러 가지 방법으로 설정할 수 있어요. 자세한 내용은 공식 문서 ↗︎를 참고해 주세요. 설치 후 Mastodon 문서의 환경 구성 ↗︎ 단계에 도달하면 아래 절차를 따라 다음 단계를 진행하면 돼요.

1. 파일 접근용 호스트 이름 결정

Mastodon 인스턴스의 기본 호스트 이름과 달리, 파일용 객체 스토리지는 고유한 호스트 이름이 필요해요. 예를 들어 Mastodon의 호스트 이름을 mastodon.example.com으로 설정했다면 파일 접근에는 mastodon-files.example.com이나 files.example.com을 사용할 수 있어요. 즉 mastodon.example.com에서 인스턴스를 방문할 때, 게시물에 이미지나 영상 같은 미디어가 첨부되어 있으면 그 파일은 이 단계에서 결정한 호스트 이름(예: mastodon-files.example.com) 아래에서 제공돼요.

참고

나중에 R2에서 다른 S3 호환 서비스로 옮기더라도 이 단계에서 결정한 호스트 이름을 계속 사용할 수 있어요. 기존 파일 참조를 깨지 않도록 인스턴스가 실행된 후에는 호스트 이름을 바꾸지 않는 것을 권장해요. 이런 경우 Bulk Redirects를 사용해 이전 호스트 이름에 도달하는 요청이 새 호스트 이름을 참조하도록 지시할 수 있어요.

2. R2 버킷 만들고 설정

  1. Cloudflare 대시보드에서 R2 object storage 페이지로 이동해요. Overview로 이동 ↗
  2. Create bucket을 선택해요.
  3. 버킷 이름을 입력하고 Create bucket을 선택해요. 이 이름은 Mastodon 인스턴스를 설정할 때 내부적으로 사용되며 공개적으로 접근할 수 없어요.
  4. 버킷이 생성되면 이 버킷의 Settings 탭으로 이동해 S3 API 값을 복사해요.
  5. Settings 탭에서 Connect Domain을 선택하고 1단계의 호스트 이름을 입력해요.
  6. R2의 overview 페이지로 돌아가 Manage R2 API Tokens을 선택해요.
  7. Create API token을 선택해요.
  8. API 이름 옆의 연필 아이콘을 선택해 토큰 이름을 Mastodon으로 지정하고 Edit 권한을 부여해요. Create API Token을 선택해 토큰 생성을 마무리해요.
  9. Access Key ID와 Secret Access Key 값을 복사해요.

3. Mastodon용 R2 구성

공식 구성 파일 ↗︎을 기반으로 Mastodon 인스턴스를 구성하면서 File storage 섹션을 다음 내용으로 바꿔요.

S3_ENABLED=true
S3_ALIAS_HOST={{mastodon-files.example.com}}                  # Change to the hostname determined in step 1
S3_BUCKET={{your-bucket-name}}                                # Change to the bucket name set in step 2
S3_ENDPOINT=https://{{unique-id}}.r2.cloudflarestorage.com/   # Change the {{unique-id}} to the part of S3 API retrieved in step 2
AWS_ACCESS_KEY_ID={{your-access-key-id}}                      # Change to the Access Key ID retrieved in step 2
AWS_SECRET_ACCESS_KEY={{your-secret-access-key}}              # Change to the Secret Access Key retrieved in step 2
S3_PROTOCOL=https
S3_PERMISSION=

S3_PERMISSION은 비워 두세요. 이렇게 하면 R2가 지원하지 않는 ACL 헤더를 Mastodon이 보내지 못하게 해요.

구성 후 인스턴스를 실행할 수 있어요. 인스턴스가 실행된 후 미디어 첨부 파일을 업로드하고, 위에서 설정한 호스트 이름에서 첨부 파일이 검색되는지 확인해 보세요. R2의 버킷 페이지로 돌아가면 다음 구조가 보일 거예요.

인스턴스 설정·실행 후의 Mastodon 버킷 구조

R2로 마이그레이션

이미 실행 중인 인스턴스가 있다면 미디어 파일을 R2로 마이그레이션해서 이그레스 비용 없음의 이점을 누릴 수 있어요.

1. R2 버킷 설정과 파일 마이그레이션 시작

  1. (선택 사항) 마이그레이션할 파일 수를 최소화하려면 Mastodon admin CLI ↗︎로 사용하지 않는 파일을 정리할 수 있어요.
  2. 위의 새 인스턴스 설정 섹션 1단계와 2단계를 따라 파일 마이그레이션을 위한 R2 버킷을 준비해요.
  3. 모든 미디어 파일을 R2로 마이그레이션해요. 다양한 제공자를 연결하는 방법은 예시를 참고해 주세요. 현재 미디어 파일을 로컬에 호스팅하고 있다면 rclone을 사용해 로컬 파일을 R2에 업로드할 수 있어요.

2. (선택 사항) 파일 경로 리다이렉트 설정

파일 마이그레이션이 진행되는 동안(꽤 오래 걸릴 수 있어요) 파일 경로 리다이렉트 설정을 준비할 수 있어요.

미디어 파일을 로컬에 호스팅했다면 리다이렉트를 설정해야 할 가능성이 높아요. 기본적으로 로컬에 호스팅된 미디어 파일은 https://mastodon.example.com/cache/... 같은 경로를 가지는데, R2 버킷이 Mastodon 인스턴스와 함께 실행된 후에는 https://mastodon-files.example.com/cache/... 같은 경로로 리다이렉트해야 해요. 이미 다른 S3 호환 객체 스토리지 서비스를 사용하고 있고 같은 호스트 이름을 유지하고 싶다면 리다이렉트를 설정할 필요가 없어요.

Bulk Redirects는 모든 플랜에서 사용할 수 있어요. 자세한 내용은 대시보드에서 Bulk Redirects 만들기를 참고해 주세요.

Bulk Redirects의 일부인 Source URL 목록과 그에 대응하는 새 Target URL

3. 버킷과 리다이렉트 검증

마이그레이션 계획에 따라 버킷이 공개적으로 접근 가능하고 리다이렉트가 올바르게 동작하는지 확인할 수 있어요. 확인하려면 https://mastodon.example.com/cache/... 같은 경로의 기존 업로드 미디어 파일을 열고, 호스트 이름을 mastodon.example.com에서 mastodon-files.example.com으로 바꿔 새 경로를 방문해 보세요. 파일이 올바르게 열리면 마지막 단계로 진행해요.

4. 마이그레이션 마무리

마이그레이션 중에도 인스턴스가 계속 실행 중일 수 있고, 그동안 직접 업로드나 다른 연합 인스턴스에서 가져오는 방식으로 새 미디어 파일이 생길 가능성이 높아요. 새로 생성된 파일만 업로드하려면 rclone 같은 프로그램을 사용할 수 있어요. 동기화 프로그램을 다시 실행하면 모든 기존 파일이 적어도 Class B 작업을 사용해 확인된다는 점을 유의해 주세요.

모든 파일이 동기화되면, 새 인스턴스 설정의 3단계에서 언급한 새 객체 스토리지 구성으로 Mastodon 인스턴스를 다시 시작하면 돼요.

더 알아보기 (Learn more)