환경 변수

Hollo는 환경 변수를 통해 여러 가지 설정을 할 수 있습니다. 환경 변수는 프로젝트 최상위 디렉터리에 .env 파일을 만들거나, Docker의 -e/--env 옵션을 쓰거나, Railway의 environment variables 메뉴에서 설정할 수 있습니다.

기본 설정

PORT 선택 Railway에서는 안 쓰임

서버가 수신할 포트 번호. 기본값은 3000입니다.

BIND 선택 Railway에서는 안 쓰임

서버가 수신할 주소. 유효한 IP 주소나 localhost여야 합니다.

DATABASE_URL Railway에서는 안 쓰임

PostgreSQL 데이터베이스의 URL. 예: postgresql://hollo:password@localhost/hollo.

SECRET_KEY Railway에서는 안 쓰임

세션을 보호하기 위한 비밀 키. 최소 44자 이상이어야 합니다. 다음 명령어로 안전한 무작위 비밀 키를 생성 가능합니다:

openssl rand -hex 32

TZ 선택

애플리케이션의 시간대(time zone). 유효한 시간대 식별자여야 합니다. 예: UTC, America/New_York, Asia/Seoul.

기본값은 UTC입니다.

NODE_TYPE 선택

이 프로세스에서 실행할 구성 요소를 제어합니다. 유효한 값은:

• all (기본값): 웹 서버, Fedify 메시지 큐, 임포트 워커, 정리 워커, 원격 답글 가져오기 워커를 모두 실행
• web: 웹 서버(HTTP API)만 실행
• worker: 워커만 실행 (Fedify 메시지 큐 + 임포트 워커 + 정리 워커 + 원격 답글 가져오기 워커)

이를 통해 더 나은 확장성을 위해 웹 서버와 백그라운드 워커를 분리할 수 있습니다. 팔로워가 많은 고트래픽 인스턴스를 운영할 때 워커를 분리하면 성능이 향상될 수 있습니다.

기본값은 all입니다.

참고

대부분의 단일 사용자 인스턴스에서는 기본값인 all 모드로 충분합니다. 워커 분리는 주로 수천 명의 팔로워가 있거나 연합 활동이 많은 인스턴스에 유용합니다.

web 모드를 사용할 때는 들어오는 액티비티를 처리하고 나가는 포스트를 전송하기 위해 최소 하나의 worker 노드가 실행 중이어야 합니다.

BEHIND_PROXY 선택 Railway에서는 안 쓰임

Hollo가 리버스 프록시 뒤에 있는 경우 true로 설정하세요. Hollo가 L7 로드 밸런서 뒤에 위치할 경우 (일반적으로 그래야 합니다), 이 옵션을 켜세요.

기본적으로는 꺼져 있습니다.

참고

이 옵션을 켜면, Hollo는 리버스 프록시로부터 전달 받은 X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host 헤더를 신뢰합니다. 이 동작은 보안상 주의를 기울여야 합니다.

HANDLE_HOST 선택

도메인 분리 WebFinger 설정에서 사용할 페디버스 핸들 도메인입니다. 이 옵션을 설정하면 페디버스 핸들이 @user@HANDLE_HOST 형식이 되지만, Hollo 자체는 여전히 WEB_ORIGIN에서 동작합니다.

WEB_ORIGIN과 함께 설정해야 하며, 한 쪽만 설정하면 Hollo가 시작에 실패합니다. 계정을 처음 만들기 전에 두 변수를 설정해야 합니다. 연합이 시작된 뒤 핸들 도메인을 바꾸면 원격 팔로워 관계가 끊어집니다.

기본적으로 설정되어 있지 않습니다.

WEB_ORIGIN 선택

도메인 분리 WebFinger 설정에서 Hollo의 ActivityPub 서버가 실제로 동작하는 오리진(스킴 + 호스트)입니다. 예: https://ap.example.com. 액터 URI, 인박스 URL을 비롯한 모든 연합 엔드포인트가 이 오리진을 기반으로 만들어집니다.

HANDLE_HOST와 함께 설정해야 하며, 한 쪽만 설정하면 Hollo가 시작에 실패합니다.

기본적으로 설정되어 있지 않습니다.

ALLOW_PRIVATE_ADDRESS 선택

이 옵션을 true로 설정하면 서버 측 요청 위조(SSRF) 공격 방지를 풉니다.

로컬 네트워크에서 테스트할 때 이 옵션을 켜야 할 수 있습니다.

기본적으로는 꺼져 있습니다.

참고

이 옵션을 켜는 것은 보안상 위험할 수 있습니다. 신뢰할 수 있는 환경에서만 사용하고, 프로덕션 환경에서는 사용하지 마세요.

부가 기능

HOME_URL 선택

설정될 경우, 첫 페이지 접속 시 이 URL로 리다이렉트됩니다. 설정되지 않을 경우, 첫 페이지에서 인스턴스 내 계정 목록이 보입니다.

REMOTE_ACTOR_FETCH_POSTS 선택

원격 액터와 처음으로 조우하게 되었을 때 가져올 최신 공개 게시물의 수.

기본값은 10입니다.

REMOTE_REPLIES_SCRAPE_DEPTH 선택

백그라운드 워커 작업에서 가져올 원격 답글의 계층 수입니다. 0으로 설정하면 원격 답글 가져오기를 비활성화합니다.

기본값은 2입니다.

REMOTE_REPLIES_SCRAPE_MAX_ITEMS 선택

원격 답글 가져오기 작업 하나에서 저장할 답글 항목의 최대 수입니다.

기본값은 100입니다.

REMOTE_REPLIES_SCRAPE_INTERVAL_SECONDS 선택

같은 origin에 대한 원격 답글 가져오기 요청 사이의 최소 대기 시간(초)입니다.

기본값은 5입니다.

REMOTE_REPLIES_SCRAPE_BACKOFF_SECONDS 선택

원격 서버가 Retry-After 없이 HTTP 429를 반환했을 때 원격 답글 가져오기 작업을 다시 시도하기 전까지 기다릴 시간(초)입니다.

기본값은 300입니다.

REMOTE_REPLIES_SCRAPE_COOLDOWN_SECONDS 선택

완료된 원격 답글 가져오기 작업이 같은 답글 컬렉션의 중복 작업을 억제하는 시간(초)입니다.

기본값은 300입니다.

MEDIA_PROXY 선택

다른 서버에 있는 미디어(아바타, 헤더, 첨부 미디어, 커스텀 이모지, 미리보기 카드 이미지)를 Hollo가 어떻게 클라이언트에게 전달할지 결정합니다. 지정 가능한 값:

• off (기본값): Mastodon API와 웹 UI가 원격 URL을 그대로 전달합니다. 이전과 동일한 동작입니다.
• proxy: 모든 원격 미디어 URL을 서명된 /proxy/<sig>/<b64url> 경로로 재작성합니다. Hollo가 매 요청마다 원본을 스트리밍해 응답하며 디스크에는 저장하지 않습니다. 클라이언트는 Hollo 도메인만 보게 되어 원격 서버의 CORS 설정에 영향을 받지 않고, 방문자 IP도 외부로 노출되지 않습니다.
• cache: proxy와 동일한 URL 재작성에 더해, 스트리밍한 본문을 설정된 저장소 백엔드의 proxy/<sha256>.bin에 저장하고, 콘텐츠 타입 정보를 담은 사이드카 파일을 proxy/<sha256>.json에 함께 저장합니다. 이후 요청은 원본을 다시 가져오지 않습니다. 로컬 계정과 승인된 팔로우 관계가 있는 리모트 액터의 아바타도 액터가 저장되거나 갱신될 때 이 캐시에 미리 저장됩니다. /thumbnail_cleanup 관리자 페이지에서 필요할 때 캐시를 비울 수 있습니다.

불리언 동의어로 true / on / 1은 proxy의 별칭으로, false / off / 0은 off의 별칭으로 받아들입니다. 디스크 캐싱은 반드시 cache로 명시적으로 요청해야 합니다.

proxy와 cache 모드에서 Hollo는 HTTP(S)가 아닌 스킴은 프록시하지 않고, 원본 URL과 모든 리다이렉트 대상에 대해 SSRF 검사를 수행하며, 본문 크기를 32 MiB로 제한하고, image/svg+xml은 Hollo 도메인에서 실행되는 인라인 스크립트를 포함할 수 있어 절대 프록시하지 않습니다.

기본값은 off입니다.

REMOTE_MEDIA_THUMBNAILS 선택

게시물을 수신할 때 Hollo가 원격 첨부 미디어를 내려받아 로컬 WebP 썸네일을 생성할지 결정합니다. 값은 on / true / 1(이전과 동일한 동작) 또는 off / false / 0입니다.

off로 설정하면 Hollo는 들어오는 첨부에 대해 원본 다운로드와 Sharp 파이프라인을 건너뛰고, 원격 URL을 그대로 썸네일 URL로 저장합니다. MEDIA_PROXY=proxy 또는 cache와 함께 쓰면 클라이언트는 렌더 시 여전히 같은 출처의 URL을 보게 되며, MEDIA_PROXY=off일 때는 원본 URL을 그대로 받습니다. 미디어가 많은 게시물을 자주 받는 인스턴스에서 디스크 공간을 크게 절약할 수 있습니다.

기본값은 on입니다.

REMOTE_ACTOR_STALENESS_DAYS 선택

원격 액터의 캐시된 데이터가 오래된 것으로 간주되기까지의 일수. 액티비티 처리 중(예: 부스트나 새 게시물 수신 시) 오래된 액터를 만나면 해당 프로필 데이터가 비동기적으로 새로고침됩니다.

기본값은 7입니다.

REFRESH_ACTORS_ON_INTERACTION 선택

true로 설정하면 모든 수신 액티비티(좋아요, 에모지 리액션, 팔로우 등)에서 오래된 액터 데이터를 체크합니다. false(기본값)일 경우 타임라인에 표시되는 액티비티(Announce, Create)에서만 체크합니다.

기본적으로는 꺼져 있습니다.

TIMELINE_INBOXES 선택

이 옵션을 false로 설정하면 타임라인 수신함 모드가 비활성화됩니다. 활성화된 경우(기본값), 타임라인에 표시될 게시물들이 실시간으로 필터링되는 것이 아니라, 미리 추출된 게시물들이 데이터베이스에 저장됩니다. 이 기능은 많은 원격 게시물을 수신하는 상대적으로 큰 인스턴스에서 유용합니다.

Hollo 0.9.0부터 기본값이 true로 바뀌었습니다. Hollo 1.0.0에서는 이 옵션이 완전히 제거되며, 타임라인 수신함 모드만 지원됩니다.

기본적으로는 켜져 있습니다.

ALLOW_HTML 선택

이 옵션을 true로 설정하면 날 HTML을 Markdown 사이에 쓸 수 있습니다. (Markdown은 Hollo에서 프로필 소개나 게시물 내용 등에 사용됩니다.) Markdown에서 지원하는 서식보다 더 다양한 서식을 사용하고 싶을 때 유용하지만, XSS 공격을 막기 위해 HTML 태그와 속성이 어느 정도 제한됩니다.

기본적으로는 꺼져 있습니다.

로그 및 디버그

LOG_LEVEL 선택

애플리케이션의 로그 레벨. debug, info, warning, error, fatal 중 택일.

기본값은 info입니다.

LOG_QUERY 선택

SQL 쿼리를 로그에 남기려면 true로 설정하세요.

기본값은 false입니다.

LOG_FILE 선택

구조화된 로그를 쓸 파일의 경로를 지정하세요. 콘솔에 출력되는 로그와는 다르게, 이 로그는 구조화 로그 형식(기본값: JSON Lines)으로 기록됩니다.

LOG_FILE_FORMAT 선택

LOG_FILE로 지정한 로그 파일의 형식. 다음 값 중 하나를 선택하세요:

• jsonl (기본값): JSON Lines 형식. 한 줄에 JSON 객체 하나씩 출력합니다. 구조화된 JSON을 파싱하는 로그 집계 도구에 적합합니다.
• logfmt: logfmt 형식. 한 줄에 키-값 쌍으로 출력합니다. 사람이 읽기 쉽고 Loki 등의 도구와 호환됩니다.

기본값은 jsonl입니다.

SENTRY_DSN 선택

오류 리포트와 트레이스를 보낼 Sentry 프로젝트의 DSN.

FEDIFY_DEBUG 선택

true로 설정하면 Fedify 디버거를 활성화합니다. Fedify 디버거는 ActivityPub 트레이스와 액티비티를 실시간으로 검사할 수 있는 내장 대시보드입니다. 활성화하면 /__debug__/에서 디버그 대시보드에 접근할 수 있습니다.

기본적으로는 꺼져 있습니다.

주의

Fedify 디버거는 개발 목적으로만 사용하도록 설계되어 있습니다. 프로덕션 환경에서 이 옵션을 활성화하면 내부 트레이스 데이터가 외부에 노출되어 보안상 위험합니다.

미디어 저장소

DRIVE_DISK

Hollo에서 프로필 사진, 커스텀 에모지, 기타 미디어와 같은 파일들을 저장할 디스크 드라이버.

선택지는 fs (로컬 파일시스템) 또는 s3 (S3 호환 오브젝트 스토리지) 중 하나입니다.

하위 호환성을 위해 s3가 기본값이지만, 앞으로는 기본값이 사라질 예정이므로 명시적으로 설정하는 것이 좋습니다.

드라이버에 관해 자세히 알아보려면 FlyDrive 문서(영문)를 참고하세요.

주의

운영중인 Hollo의 DRIVE_DISK 및 관련 설정을 도중에 변경하더라도, 기존 파일들은 옮겨지지 않습니다. 새로운 파일들만 새로운 설정에 따라 저장됩니다.

또한, 기존 파일들은 여전히 예전의 설정에 따라 서빙되므로, 이 점을 유의하세요. 예를 들어, S3_BUCKET을 바꿨어도, 기존 파일들은 예전의 버킷에서 서빙되므로 지우면 안 됩니다.

STORAGE_URL_BASE

미디어 파일들을 서빙할 URL의 앞 부분. 예: https://media.hollo.social.

DRIVE_DISK=fs인 경우, 로컬 파일시스템에 저장된 파일들을 웹에서 접근할 수 있도록 하려면 https://<호스트>/assets 형태로 설정해야 합니다. 예: https://hollo.example.com/assets.

주의

• 실제 운영시에는 HTTPS를 사용해야 합니다.
• 공개적으로 접근 가능해야 연합이 올바르게 작동합니다.
• 유연성을 위해 오브젝트 스토리지의 실제 도메인을 직접 쓰는 대신, CNAME된 도메인을 사용하는 것을 권장합니다.

로컬 파일시스템 설정

FS_STORAGE_PATH FS 드라이버에서 필수

로컬 파일시스템에서 파일들을 저장할 경로. 예: /var/lib/hollo.

참고

• 디렉터리가 존재해야 하며 Hollo 프로세스가 쓸 수 있어야 합니다.
• 권한 설정은 디렉터리의 경우 755, 파일들의 경우 644를 권장합니다.
• 충분한 디스크 공간이 확보되어 있는지 확인하세요.
• 필히 정기적인 백업을 하시기 바랍니다.
• Docker를 쓸 때는 경로가 제대로 마운트되었는지 확인하세요.

S3 호환 오브젝트 스토리지 설정

참고

이하의 설정들은 DRIVE_DISK=s3일 때만 필요합니다.

AWS IAM 정책이 아래 권한들을 지니고 있는지 확인하세요:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket

S3_REGION S3 드라이버에서 필수

S3 호환 오브젝트 스토리지의 지역. 예: us-east-1. 몇몇 AWS가 아닌 S3 호환 서비스에서는 이 값이 필요 없을 수 있습니다.

S3_BUCKET S3 드라이버에서 필수

S3 호환 오브젝트 스토리지의 버킷 이름. 예: hollo.

S3_ENDPOINT_URL S3 드라이버에서 필수

S3 호환 오브젝트 스토리지의 엔드포인트 URL. 예: https://s3.us-east-1.amazonaws.com.

S3_FORCE_PATH_STYLE 선택

S3 호환 오브젝트 스토리지에 대해 경로 스타일 URL을 강제할지 여부 (true 혹은 false). AWS가 아닌 S3 호환 서비스에서 유용합니다. 기본적으로는 꺼져 있습니다.

AWS_ACCESS_KEY_ID S3 드라이버에서 필수

S3 호환 오브젝트 스토리지 액세스 키.

AWS_SECRET_ACCESS_KEY S3 드라이버에서 필수

S3 호환 오브젝트 스토리지 비밀 키.