준비부터 첫 앨범까지,
한 단계씩 따라오세요.

STEP 1

준비물과 설치 사전점검

집 장비에서 실행하는 StarFrame 프로그램을 Family Node라고 부릅니다. 상시 켜둘 장비와 별도의 백업 위치부터 준비하세요.

NAS·PC

2 코어 / 2 GB 이상 권장. 원본 사진·영상을 담을 여유 공간

실행 환경

Docker·Docker Compose 또는 시놀로지 Container Manager. linux/amd64·linux/arm64 지원, 관리 권한 필요

장비 주소

공유기 DHCP 예약 등을 이용한 고정 사설 IP

포트

NAS 관리 화면 등에서 80·443 포트를 사용하는지 확인

장비 시각

정확한 시각과 시간대(Asia/Seoul)

백업 위치

앨범 원본과 분리된 디스크 또는 별도 저장 위치

모든 NAS의 호환을 보장하지 않습니다. 기존 포트를 바꾸기 전에는 관리 화면에 다시 접속할 방법을 확인하세요.

STEP 2

설정 파일을 받아 실행하기

무료 설치 안내에서 현재 릴리스의 설정 파일을 받습니다.

docker compose up -d
docker compose ps -a

STEP 3

서버 자신에서 첫 접속·초기 설정

서버의 브라우저에서 http://127.0.0.1:8080을 엽니다. 이 주소는 서버 자신에서만 접근할 수 있습니다. 기본 바인딩을 외부 공개로 바꾸지 말고, 다른 기기는 리버스 프록시와 HTTPS를 통해 연결하세요.

1. 서버 점검: 설정 마법사의 부족한 항목을 확인합니다.
2. 가족 소개·앱 이름: 설치할 가족의 정보와 테마를 설정합니다.
3. 소유자 계정: 이 장비를 관리할 계정을 만듭니다.
4. 복구 코드: 한 번만 표시되는 코드를 안전한 곳에 보관합니다. 지원 메일에는 보내지 마세요.

초기 설정을 마치고 앨범에 들어가면 성공입니다. 마법사가 열리지 않으면 기동 상태와 접속 위치를 확인하세요.

STEP 4

HTTPS 주소를 준비하고 가족 초대하기

먼저 HTTPS 설정을 완료하고 담당자가 해당 주소에서 로그인과 업로드를 확인합니다. STARFRAME_PUBLIC_URL은 가족에게 안내할 실제 HTTPS 주소로 설정합니다.

1. 관리자 › 초대에서 초대를 생성하고 해당 가족에게만 전달합니다.
2. 가족은 초대받은 주소로 접속해 각자의 계정으로 참여합니다.
3. 브라우저에서 사진·영상을 열고, 권한이 있는 가족은 업로드·댓글을 사용합니다.

홈 화면 추가와 알림은 HTTPS 및 기기·브라우저 지원이 필요합니다. iPhone 알림은 홈 화면 추가가 전제입니다. 미리보기의 iOS 설치 안내는 완성된 흐름으로 보장하지 않습니다.

초대 토큰과 복구 코드를 공개하거나 지원 문의에 붙여넣지 마세요.

STEP 5

HTTPS와 제한 모드

HTTP에서는 기본 앨범 열람이 가능하더라도 홈 화면 설치·서비스 워커·알림 등이 꺼진 제한 모드입니다. 신뢰된 인증서가 있는 HTTPS를 준비해야 합니다. 자체 서명 인증서의 경고를 무시하는 방식은 해결책이 아닙니다.

무료 사용자는 도메인/DDNS와 인증서 발급·갱신을 직접 구성합니다. 시놀로지 DDNS와 DSM 인증서, 도메인을 가진 서버의 Caddy·nginx, 사설망의 HTTPS 등 환경에 맞는 경로를 선택합니다.

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
client_max_body_size 0;
proxy_request_buffering off;
proxy_buffering off;
proxy_read_timeout 1h;
proxy_send_timeout 1h;

STEP 6

집 밖에서 접속하기

외부접속에는 접근 가능한 주소와 네트워크 경로가 필요합니다. 직접 운영하는 경우 도메인/DDNS, HTTPS, 포트포워딩을 사용자가 설정합니다.

공인 IPv4가 없고 직접 접근 가능한 IPv6도 없는 회선(CGNAT 환경)에서는 외부 직접접속이 성립하지 않습니다. 집 안 전용 HTTPS 구성이나 VPN 계열 사설 네트워크 경로를 검토해야 합니다.

사진과 영상은 가족 기기와 집 장비 사이에서 오갑니다. StarFrame 중앙 서버가 미디어를 저장하거나 릴레이하는 경로는 제공하지 않습니다.

STEP 7

백업과 업데이트를 별도로 준비하세요.

관리자 › 백업에서 백업을 설정·실행합니다. 백업 기능이 있어도 백업본을 안전한 위치에 보관하는 책임은 담당자에게 있습니다. 사진 업로드를 휴대폰 사진 자동 백업이나 외부 사본 생성으로 오해하지 마세요.

RAID는 백업을 대신하지 않습니다. 원본과 다른 저장장치에 사본을 두고 가능하면 집 밖에도 보관하세요. 성공 표시뿐 아니라 실제 복원 가능 여부도 확인해야 합니다. StarFrame은 고객 원본의 사본을 보관하지 않습니다.

STEP 8

막힌 단계부터 확인하세요.

화면이 안 열림

서버에서 실행했는지, starframe이 healthy인지 확인합니다. 다른 기기의 127.0.0.1은 서버 주소가 아닙니다. 첫 접속

로그인·업로드 실패

Host, HTTPS 전달 헤더, 신뢰 프록시, 업로드 제한을 확인합니다. HTTPS 설정

집 밖에서 실패

공인 IP·이중 NAT·포트 충돌과 실제 외부 경로를 확인합니다. 접속 조건

집 안에서 실패

DNS 재바인딩·split DNS와 신뢰된 인증서를 확인합니다. Connect 조건

기동 로그 확인 명령입니다. 로그를 문의에 첨부하기 전 주소·계정·토큰 등 민감한 내용은 제거하세요.

docker compose logs --tail=50 starframe