CasaOS/ZimaOS에서 Homarr: 현재 Docker Compose 설정

결론: 2023년 BigBear 템플릿 대신 Homarr의 최신 Docker Compose 방식을 사용하세요

기존 CasaOS 게시물은 BigBearCasaOS가 원클릭 설치용으로 Homarr를 패키징했을 때 유용했습니다. Homarr는 크게 변경되었습니다. 현재 셀프 호스팅 방식은 Compose를 사용하며, 상태를 다음 경로에 영구 저장합니다: /appdata다음이 필요합니다: SECRET_ENCRYPTION_KEY컨테이너 통합을 위해 Docker 소켓을 선택적으로 마운트할 수 있습니다.

영구적인 Compose 정의로 시작하기

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /DATA/AppData/homarr:/appdata
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SECRET_ENCRYPTION_KEY=REPLACE_WITH_64_HEX_CHARS

최신 Homarr Docker 설치 안내에서는 Compose를 권장하며 /appdata를 설명합니다.

처음 시작하기 전에 암호화 키 생성

openssl rand -hex 32

Homarr는 이 비밀 키를 사용하여 민감한 통합 데이터를 보호합니다. 공개 Compose 내보내기에서 제외하세요. OpenSSL의 안전한 랜덤 생성에서 해당 명령을 설명합니다.

필요한 경우에만 Docker 소켓 마운트

Docker 소켓은 호스트를 강력하게 제어할 수 있습니다. Homarr에 링크, 북마크 및 외부 위젯만 필요하다면 이를 생략하세요. 의도적으로 사용하는 Docker 인식 통합에만 추가하세요.

ZimaOS 데이터에는 ZimaOS OpenAPI 사용

스토리지 또는 시스템 상태에는 대시보드 HTML을 스크래핑하는 대신 게시된 ZimaOS OpenAPI를 사용하세요. ZimaOS 앱 요구 사항에서 리소스 계획을 다룹니다.

인증이 준비될 때까지 Homarr를 내부용으로 유지하세요

대시보드에는 내부 IP, 포트 및 인프라 상태가 노출될 수 있습니다. 인증과 HTTPS 없이 직접 공개하지 마세요. ZimaOS HTTPS 프록시가 공개 액세스 계층을 제공합니다.

Homarr를 컨테이너로 업데이트하기

docker compose down
docker compose pull
docker compose up -d

영구 저장 /appdata 컨테이너를 다시 생성해도 유지됩니다. 따라서 기존 컨테이너를 보존하는 것보다 볼륨이 더 중요합니다.

Homarr 설정을 컨테이너 안에만 두지 마세요

/appdata가 영구 호스트 저장소에 매핑되지 않으면 컨테이너를 다시 생성할 때 구성이 삭제될 수 있습니다. 호스트 측 Homarr 폴더를 백업하세요. ZimaOS 백업이 복구 계층을 제공합니다.

Homarr를 관리 우회 수단이 아닌 첫 관문으로 사용하세요

Homarr는 링크와 읽기 전용 상태 정보를 중앙화할 수 있지만, 각 기반 앱에는 여전히 자체 인증이 필요합니다. 한 번의 클릭으로 접속할 수 있도록 공개 위젯에 관리자 자격 증명을 삽입하지 마세요.

첫날에 모든 서비스를 연결하지 말고 대시보드를 단계적으로 구성하세요

먼저 ZimaOS, Plex, Home Assistant 및 기타 서비스로 연결되는 일반 링크를 추가하세요. 대시보드 자체가 안정화된 후 통합을 한 번에 하나씩 추가하세요. 이렇게 하면 로그인 루프, 느린 페이지 로드 또는 권한 문제를 일으킨 통합을 명확히 파악할 수 있습니다. API 통합을 스무 개 추가한 대시보드는 백엔드 하나만 시간 초과된 경우에도 전체 앱이 고장 난 것처럼 보일 수 있습니다.

내부 호스트 이름 또는 안정적인 LAN IP를 사용하세요

Homarr의 최신 컨테이너 지침에서는 네트워크의 클라이언트가 확인할 수 있는 호스트 이름 또는 직접 IP 주소를 사용할 것을 권장합니다. 리버스 프록시를 사용하는 경우 공개 호스트 이름을 일관되게 유지하고 WebSocket/API 요청이 동일한 오리진을 사용하도록 하세요. 컨테이너를 다시 생성하면 변경될 수 있으므로 임시 Docker IP를 하드코딩하지 마세요.

보기 좋은 레이아웃 이상의 항목을 백업하세요

대시보드에는 암호화된 통합 자격 증명, 사용자 계정, 아이콘 및 서비스 메타데이터가 포함될 수 있습니다. 전체 영구 /appdata 암호화 키와 함께 디렉터리를 보관하세요. 백업에 의존하기 전에 일회용 Homarr 컨테이너에 복원을 테스트하세요.

자동 컨테이너 업데이트에 주의하세요

대시보드는 홈랩의 나머지 환경이 정상적으로 작동하는지 가장 먼저 알아차리는 곳인 경우가 많습니다. Homarr가 자동으로 업데이트되면서 다른 서비스와 동시에 장애가 발생하면 원인을 진단하기가 더 어려워집니다. 가동 시간이 중요하다면 검증된 버전을 고정하거나 수동으로 업데이트한 다음, 테스트 후 순차적으로 최신 버전으로 진행하세요.

업그레이드가 성공할 때마다 정확한 Homarr 이미지 태그를 기록해 두면 롤백을 간단하게 수행할 수 있습니다.

자주 묻는 질문

Homarr에 BigBearCasaOS가 여전히 필요한가요?

아니요. Homarr는 자체적인 최신 Docker 및 Compose 설치 경로를 제공합니다.

SECRET_ENCRYPTION_KEY란 무엇인가요?

이는 Homarr가 민감한 통합 데이터를 보호하기 위해 사용하는 영구 비밀 키입니다.

Docker 소켓이 필요한가요?

Docker를 인식하는 통합 또는 컨테이너 제어에만 해당합니다.

Homarr에서 ZimaOS 시스템 데이터를 표시할 수 있나요?

ZimaOS OpenAPI를 사용하는 사용자 지정 통합을 통해 가능할 수 있습니다.

Homarr를 안전하게 업데이트하려면 어떻게 해야 하나요?

/appdata를 유지하고, 최신 이미지를 가져온 뒤 서비스를 다시 생성한 다음 이전 이미지를 삭제하기 전에 대시보드를 확인하세요.