웹 개발자를 위한 Studio 설정

Studio 다운로드 받기

Studio가 있는 계정으로 Maxisnap에 로그인한 다음:

• Windows: Maxisnap에서 설정 → 계정 → Maxisnap Studio 설정 마법사를 열고 “시작하기”를 클릭한 다음 “대시보드 다운로드”를 클릭합니다. Maxisnap이 Studio ZIP 파일을 다운로드 폴더에 저장하고 그 폴더를 엽니다.
• Mac: Maxisnap에서 Settings → Welcome & Help → Studio Setup Guide를 열고 “Get Started”를 클릭한 다음 “Download Dashboard”를 클릭합니다. Maxisnap이 Studio ZIP 파일을 다운로드 폴더에 저장합니다.

ZIP 파일의 압축을 풉니다. Windows에서는 마우스 오른쪽 버튼으로 클릭하고 “모두 추출”을 선택합니다. Mac에서는 두 번 클릭합니다.

Maxisnap-Studio-v<version>/
  Maxisnap Studio - Start Here.html   guided setup (branding + every route)
  snaps/                              PHP edition: upload this folder to a web host
  cloudflare/                         Cloudflare Workers edition (Worker + R2 + D1)
    deploy/cli.mjs                    deploys it through the Cloudflare API (Node 20+)
  docs/Developer guide.html           architecture, upload API, security, updates
  docs/Cloudflare setup - technical brief.html
  AGENTS.md                           instructions for AI coding assistants

전체 Developer guide에는 아키텍처, 업로드 API, 키와 역할, 보안 모델, 문제 해결 방법이 담겨 있습니다. 다운로드의 docs/Developer guide.html 파일입니다.

PHP 에디션: 업로드하고 설정 마치기

1. 숨김 파일인 .htaccess 파일을 포함해 snaps 폴더를 웹 루트에 업로드하여 최종 경로가 public_html/snaps/index.php가 되도록 하세요. Start Here 페이지에서 만든 브랜딩 적용 snaps.zip도 같은 방식으로 사용합니다. 그 자리에서 압축을 풀고, snaps/snaps처럼 중첩되지 않게 하세요.
2. https://yourcompany.com/snaps/ 주소를 한 번 여세요. 설정 페이지가 PHP와 폴더 권한을 확인하고 40자 길이의 관리자 키를 제안합니다. 키는 최소 16자 이상이어야 합니다. 키를 복사한 다음 “Create my dashboard”를 클릭하세요.
3. nginx에서는 snaps/.htaccess의 라우팅 규칙과 접근 거부 규칙을 그대로 구현하세요. uploads, data, branding은 비공개로 유지하세요.

설정 페이지가 your-settings.php를 만들며, 이 파일은 업데이트 후에도 유지됩니다:

'dashboard_key' => '…',          // the Admin key; the setup page writes it
'base_url'      => 'https://yourcompany.com/snaps',  // the address setup was opened at; fix it here if share links come out wrong
'max_upload_mb' => 500,          // your host's PHP limits still apply

Cloudflare 에디션: 터미널에서 배포

함께 제공되는 CLI는 먼저 계정을 읽고, 무엇을 만들고 무엇을 건드리지 않을지 보여 주는 실행 계획을 표시하며, 이미 사용 중인 이름은 거부합니다. 배포가 중간에 멈춰도 같은 명령을 다시 실행하면 아무것도 두 번 만들지 않고 이어서 진행합니다.

cd cloudflare
# Option 1: the bundled CLI (Node 20+; plan first, then --yes). PowerShell:
$env:CLOUDFLARE_API_TOKEN = "<token: Account Settings Read; Workers Scripts, R2 and D1 Edit;
                              for --zone/--hostname also Zone Read, DNS Read, Workers Routes Read>"
node deploy/cli.mjs whoami
node deploy/cli.mjs plan --account <account id> --name snaps
#   no workers.dev name on the account yet? The plan asks you to "Choose your free
#   workers.dev name": add --subdomain <your-company> to both commands (account-wide).
#   A subdomain of your domain as well: add --zone <zone id> --hostname snaps.example.com
node deploy/cli.mjs deploy --account <account id> --name snaps --yes
#   prints the Studio address and the Admin key once, and writes deployment.json here

# Option 2: plain Wrangler (create the bucket and database, set their ids in wrangler.jsonc)
npm install
npx wrangler r2 bucket create maxisnap-studio-media
npx wrangler d1 create maxisnap-studio
npx wrangler secret put ADMIN_KEY
npm run sync
npx wrangler deploy

배포가 끝나면 Studio 주소와 관리자 키가 한 번만 표시되고, 명령을 실행한 폴더에 deployment.json이 기록됩니다. 이 파일을 보관하세요. update와 remove가 이 파일을 사용합니다.

작동 확인

curl.exe -s -H "X-Dashboard-Key: <Admin key>" https://<studio address>/api/health.php
# {"ok":true,"app":"Maxisnap Studio","version":"…"}   the Cloudflare edition adds "edition":"cloudflare"

그런 다음 브라우저에서 Studio 주소를 열고 관리자 키로 로그인하세요. 401은 키가 잘못되었다는 뜻이고, 404는 주소나 폴더가 잘못되었다는 뜻입니다.

Maxisnap 연결

• Windows용 Maxisnap: 설정 → 계정 → Maxisnap Studio 설정 마법사를 열고 “시작하기”를 클릭하고, 4단계 “Maxisnap 연결”이 나올 때까지 “다음”을 클릭합니다. Studio 주소와 키를 붙여넣고 “연결 테스트”를 클릭한 다음 “다음”을 클릭하고, 마지막 페이지에서 “완료 및 저장”을 클릭합니다. 설정할 때 받은 관리자 키도, 대시보드의 People & access에 있는 업로드 코드도 사용할 수 있습니다.
• Mac용 Maxisnap: Settings → Welcome & Help → Studio Setup Guide를 열고 “I already have a dashboard”를 선택합니다. Studio 주소와 키를 붙여넣고 “Test Connection”, “Next”, “Finish & Save”를 차례로 클릭합니다.

업로드 API 알아보기

• Maxisnap 앱은 X-Dashboard-Key 헤더와 함께 api/upload.php로 업로드합니다. 이미지(PNG, JPG, GIF, WebP)와 동영상(MP4, WebM, MOV)을 받을 수 있습니다.
• Windows용 Maxisnap과 Mac용 Maxisnap은 각 업로드를 Cloudflare Studio에 요청 한 번으로 보내며, Cloudflare Studio는 파일당 최대 25 MB까지 받습니다.
• Cloudflare 에디션에는 더 큰 파일을 위한 청크 업로드 API도 있으며, Developer guide에 설명되어 있습니다: api/upload/start, part, complete.
• 공유 페이지와 해당 미디어 파일은 다음 경로를 사용하며, 그 밖의 모든 경로는 내부용입니다: /<slug> /<slug>.<ext>

나중에 업데이트하거나 제거하기

PHP: snaps/How to update.txt에 나열된 파일만 교체한 다음 호스트와 CDN 캐시를 지우세요. 캡처, 팀원, 브랜딩, 설정은 그대로 유지됩니다.

Cloudflare: 새 패키지의 cloudflare 폴더에서 다음을 실행하세요. 이전 deployment.json을 그 폴더에 복사해 두어야 합니다.

# Update: from a newer package's cloudflare folder, with the old deployment.json copied in
node deploy/cli.mjs update --record deployment.json --yes
# New Admin key (shown once):
node deploy/cli.mjs update --record deployment.json --yes --new-admin-key
# Remove the custom domain and the Worker; the bucket and database (the captures) stay
node deploy/cli.mjs remove --record deployment.json --yes
# Also delete every capture: cannot be undone
node deploy/cli.mjs remove --record deployment.json --yes --delete-data

Cloudflare 기술 개요서 읽기: 모든 리소스, 권한, API 호출.