↓Skip to main content
MINOSAUR

Docker로 Homepage 대시보드 설치하기

·440 words·3 mins
미뇽
Author
미뇽
안녕하세요! 기술로 세상을 이롭게 만들고 싶은 개발자 미뇽입니다.
Table of Contents

Homepage는 다양한 셀프 호스팅 서비스와 Docker 컨테이너 상태 등을 한눈에 볼 수 있는 현대적이고 미려한 대시보드입니다. 깔끔한 UI와 강력한 통합 기능 덕분에 많은 사용자에게 사랑받고 있습니다.

이 가이드에서는 Docker Compose를 사용하여 Homepage 대시보드를 설치하는 가장 표준적인 방법을 단계별로 안내합니다.

설치 준비
#

먼저, Homepage의 설정 파일과 docker-compose.yml 파일을 보관할 디렉토리를 생성합니다.

# homepage 설치를 위한 상위 폴더 생성 및 이동
mkdir homepage
cd homepage

# Homepage 설정 파일(YAML)이 저장될 config 폴더 생성
mkdir config

docker-compose.yml 파일 작성
#

homepage 디렉토리 내부에 docker-compose.yml 파일을 생성하고 아래의 내용을 작성합니다.

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      # 로컬의 config 폴더를 컨테이너 내부의 설정 폴더와 연결합니다.
      - ./config:/app/config
      # (선택 사항) Docker 컨테이너 위젯을 사용하려면 Docker 소켓을 연결합니다.
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # [필수] 허용할 호스트를 지정하는 보안 설정입니다. 아래에서 자세히 설명합니다.
      - HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev
    restart: unless-stopped
  • ports: 호스트(서버)의 3000번 포트를 컨테이너의 3000번 포트와 연결합니다.
  • volumes:
    • ./config:/app/config: 로컬의 config 폴더를 컨테이너와 연결하여 대시보드 설정을 영속적으로 보관합니다. 컨테이너가 삭제되어도 설정이 유지됩니다.
    • /var/run/docker.sock...: (선택 사항) Docker 소켓을 연결하면, Homepage 대시보드에서 실행 중인 다른 Docker 컨테이너의 상태를 모니터링하는 위젯을 사용할 수 있습니다.
  • environment: 컨테이너의 환경 변수를 설정합니다. HOMEPAGE_ALLOWED_HOSTS는 매우 중요한 보안 설정입니다.

HOMEPAGE_ALLOWED_HOSTS 보안 설정
#

HOMEPAGE_ALLOWED_HOSTS는 Homepage 대시보드에 접속할 때 허용할 도메인 이름(호스트명)이나 IP 주소를 지정하는 필수 보안 설정입니다.

이 설정은 악의적인 사용자가 변조된 Host 헤더로 요청을 보내는 HTTP Host Header 공격을 막아, 대시보드를 더 안전하게 보호하는 역할을 합니다. 만약 이 목록에 없는 주소로 접속을 시도하면 “Invalid Host header"와 같은 오류가 발생합니다.

여러 주소를 등록할 때는 쉼표(,) 로 구분하며, 쉼표 뒤에 공백은 없어야 합니다.

내부 IP 주소로만 접속하는 경우
#

가장 기본적인 설정입니다. 리버스 프록시 없이 내부 네트워크에서 서버의 IP 주소로만 접속할 때 사용합니다.

environment:
  - HOMEPAGE_ALLOWED_HOSTS=192.168.0.100:3000

리버스 프록시와 도메인 주소만 사용하는 경우 (가장 일반적)
#

Traefik, Nginx Proxy Manager 등 리버스 프록시를 통해 설정한 도메인으로만 접속을 허용합니다. 이렇게 설정하면 http://서버IP:3000과 같은 직접적인 IP 접속은 차단됩니다.

environment:
  - HOMEPAGE_ALLOWED_HOSTS=dashboard.your-domain.com

내부 IP와 도메인 주소 모두 사용하려는 경우
#

내부 네트워크에서는 IP로 빠르게 접속하고, 외부에서는 도메인으로 접속하는 등 두 가지 방식을 모두 허용할 때 사용합니다.

environment:
  - HOMEPAGE_ALLOWED_HOSTS=192.168.0.100,dashboard.your-domain.com

Docker 컨테이너 이름으로 접속하는 경우
#

다른 Docker 컨테이너가 Docker 내부 네트워크를 통해 homepage라는 서비스 이름으로 접속해야 할 경우(예: 상태 모니터링) 사용합니다.

environment:
  - HOMEPAGE_ALLOWED_HOSTS=homepage,192.168.0.100,dashboard.your-domain.com

Homepage 실행 및 확인
#

docker-compose.yml 파일 작성을 완료하고, 본인의 환경에 맞게 HOMEPAGE_ALLOWED_HOSTS 설정을 마쳤다면 아래 명령어를 실행하여 Homepage를 시작합니다.

docker-compose up -d

이 명령은 Docker 이미지를 다운로드하고, 정의된 설정에 따라 컨테이너를 생성하여 백그라운드에서 실행합니다.

실행이 완료되면 웹 브라우저를 열고 http://<서버_IP_주소>:3000으로 접속하여 Homepage의 기본 화면이 나타나는지 확인합니다.

마무리하며
#

이것으로 Homepage 대시보드의 기본 설치가 완료되었습니다. 이제 여러분은 homepage/config 폴더에 있는 YAML 파일들을 수정하여 자신만의 서비스, 북마크, 위젯을 추가하며 개성 있는 대시보드를 꾸며나갈 수 있습니다.

참조