SnapOtter/apps/docs/ko/guide/getting-started.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
명령 하나로 Docker에 SnapOtter를 설치. Docker Compose 설정, 소스에서 빌드하기, 전체 기능 개요 포함.	55c67edda625	68bf7f60b68d	human

시작하기

::: tip 설치 전에 사용해 보기 demo.snapotter.com에서 전체 UI를 살펴보세요 - 가입이나 설치가 필요 없습니다. :::

빠른 시작

docker run -d --name SnapOtter -p 1349:1349 -v SnapOtter-data:/data snapotter/snapotter:latest

이 단일 컨테이너는 필요한 모든 것을 실행한다. DATABASE_URL이 설정되어 있지 않으면, 루프백 인터페이스에서 자체 PostgreSQL과 Redis를 시작하고(임베디드 모드) 모든 데이터를 SnapOtter-data 볼륨에 보관한다. SnapOtter를 사용해 보거나 홈랩에서 셀프 호스팅하기에 가장 빠른 방법이다. 프로덕션에서는 PostgreSQL과 Redis를 각자의 컨테이너에 두는 아래의 Docker Compose 스택을 실행하라. 임베디드 모드는 root로 실행되며(기본값), DATABASE_URL을 설정하는 즉시 자동으로 꺼진다.

Raspberry Pi나 오래된 노트북, 작은 VPS에 설치할 예정이라면 저사양 환경 설정에서 조정된 설치 가이드와 제한된 하드웨어에서 기대할 수 있는 것을 확인하라.

첫 로그인 시 비밀번호 변경을 요청받는다.

::: tip 익명 제품 애널리틱스 SnapOtter에는 익명 제품 애널리틱스가 기본으로 포함되어 있다. 끄려면 Settings → System → Privacy를 열고 Anonymous Product Analytics를 끄면 된다. 전체 인스턴스에 대해 즉시 중지된다.

리빌드 없이 인스턴스의 모든 텔레메트리를 비활성화하려면 환경 변수 SNAPOTTER_TELEMETRY=0(false과 off도 작동함)를 설정할 수도 있다.

오류 모니터링은 오픈소스 프로그램을 통해 SnapOtter를 후원하는 Sentry로 구동된다.

수집되는 내용에 대한 자세한 사항은 SnapOtter가 수집하는 것을 참고하라. :::

::: tip NVIDIA CUDA 가속 --gpus all를 추가하여 NVIDIA CUDA 가속 배경 제거, 업스케일링, 얼굴 강화, 그리고 복원. OCR CPU 기반으로 유지되며 유무에 관계없이 동일한 이미지에서 작동합니다. GPU 입장:

docker run -d --name SnapOtter -p 1349:1349 --gpus all -v SnapOtter-data:/data snapotter/snapotter:latest

NVIDIA Container Toolkit이 필요하다. CUDA를 사용할 수 없으면 자동으로 CPU로 폴백한다. VA-API, Quick Sync, OpenCL을 통한 Intel/AMD iGPU 가속은 현재 AI 추론에 지원되지 않는다. 벤치마크는 Docker 태그를 참고하라. :::

::: details GHCR에서도 제공

docker run -d --name SnapOtter -p 1349:1349 -v SnapOtter-data:/data ghcr.io/snapotter-hq/snapotter:latest

두 레지스트리 모두 릴리스마다 동일한 이미지를 게시한다. :::

Docker Compose

services:
  SnapOtter:
    image: snapotter/snapotter:latest  # or ghcr.io/snapotter-hq/snapotter:latest
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD=admin
      - DATABASE_URL=postgres://snapotter:snapotter@postgres:5432/snapotter
      - REDIS_URL=redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: snapotter
      POSTGRES_PASSWORD: snapotter
      POSTGRES_DB: snapotter
    volumes:
      - SnapOtter-pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U snapotter"]
      interval: 10s
      timeout: 5s
      retries: 12

  redis:
    image: redis:8-alpine
    command: ["redis-server", "--maxmemory-policy", "noeviction", "--appendonly", "yes"]
    volumes:
      - SnapOtter-redisdata:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 12

volumes:
  SnapOtter-data:
  SnapOtter-pgdata:
  SnapOtter-redisdata:

모든 환경 변수는 구성을 참고하라.

소스에서 빌드

전제 조건: Node.js 22+, pnpm 9+, Docker (Postgres + Redis용), Python 3.10+ (AI 기능용), Git.

git clone https://github.com/snapotter-hq/SnapOtter.git
cd SnapOtter
docker compose -f docker-compose.dev.yml up -d   # start Postgres + Redis
pnpm install
pnpm dev

• 프론트엔드: http://localhost:1349
• 백엔드: http://localhost:13490

할 수 있는 것

파일 처리 (200+ 도구)

모달리티	개수	예시 도구
이미지	105	크기 조정, 자르기, 압축, 변환, 배경 제거, 업스케일, OCR, 워터마크, 콜라주, 컬러화, GIF 도구, 형식 프리셋
비디오	57	트림, 자르기, 압축, 변환, 병합, 오디오 추출, 자동 자막, 비디오→GIF, 크기 조정, 안정화, 형식 프리셋
오디오	27	트림, 병합, 변환, 노멀라이즈, 노이즈 감소, 전사, 피치 시프트, 페이드, 벨소리 제작기, 형식 프리셋
PDF / 문서	42	병합, 분할, 압축, OCR, 워터마크, 편집(리댁트), Word→PDF, Excel→PDF, 회전, 보호, 복구
파일	10	CSV→JSON, JSON→XML, CSV 병합, CSV 분할, ZIP 생성, ZIP 추출, 차트 제작기, YAML/JSON

파이프라인

도구를 다단계 워크플로로 연결하고 하나의 이미지 또는 전체 배치에 적용한다:

1. 사이드바에서 Pipelines를 연다.
2. 단계를 추가한다(어떤 도구든, 어떤 설정이든).
3. 단일 파일 또는 전체 배치를 한 번에 실행한다.
4. 나중에 재사용하도록 파이프라인을 저장한다.

파이프라인은 기본적으로 20단계를 허용한다. 제한을 무제한으로 만들려면 MAX_PIPELINE_STEPS=0을 설정하라.

파일 라이브러리

처리하는 모든 파일은 Files 라이브러리에 저장할 수 있다. SnapOtter는 전체 버전 히스토리를 추적하므로 원본 업로드부터 최종 출력까지 모든 처리 단계를 추적할 수 있다.

저장은 명시적이다. 라이브러리에 저장하는 결과는 삭제할 때까지 보관되는 반면, 처리하고 저장하지 않은 결과는 72시간 후 자동으로 삭제된다(FILE_MAX_AGE_HOURS로 구성 가능).

REST API 및 API 키

모든 도구는 HTTP로 접근할 수 있다:

curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer si_<your-api-key>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800,"height":600,"fit":"cover"}'

Settings → API Keys에서 API 키를 생성한다. 모든 엔드포인트는 REST API 레퍼런스를 참고하거나, 대화형 레퍼런스는 http://localhost:1349/api/docs를 방문하라.

다중 사용자 및 팀

역할 기반 접근 제어로 여러 사용자를 활성화한다:

• 관리자: 전체 접근 - 사용자, 팀, 설정, 모든 파일/파이프라인/API 키 관리
• 사용자: 도구 사용, 자신의 파일/파이프라인/API 키 관리

Settings → Teams에서 팀을 만들어 사용자를 그룹화한다.

AUTH_ENABLED=true을 설정하라(또는 로그인 없는 단일 사용자/개인 사용에는 false).