맥미니M4(실리콘맥) remotion 및 fastapi 하이브리드 설치 및 도커 n8n 연동방법

맥미니 M4(Apple Silicon) 환경에서 Remotion의 강력한 비디오 렌더링 기능과 FastAPI의 빠른 API 성능을 결합하고, 이를 Docker 기반의 n8n과 연동하는 하이브리드 서버 구축 방법을 안내해 드립니다.

---

환경 준비 (Pre-requisites)

M4 칩의 성능을 온전히 활용하기 위해 모든 도구는 Apple Silicon(arm64) 전용 버전으로 설치해야 합니다.

• Homebrew: 맥 필수 패키지 관리자
  홈브루 설치가 안되어있다면!? 맥 homebrew 설치방법
• Node.js (v18+): Remotion 실행용 (brew install node)
• Python (3.10+): FastAPI 실행용 (brew install python)
• FFmpeg: Remotion 비디오 합성에 필수 (brew install ffmpeg)
• Docker Desktop: n8n 실행용 (반드시 Apple Silicon용 설치)

---

1. 전체 구조 (Directory Structure)

아래와 같이 폴더 구조를 생성할 것이다. 먼저 automation-project 폴더를 만들어 놓자

automation-project/
├── backend/            # FastAPI 서버 (Python)
│   └── main.py
├── video/              # Remotion 프로젝트 (React/TS)
└── docker-compose.yml  # n8n 컨테이너 설정

---

2. Remotion 및 FastAPI 설치 및 설정

Step 1: Remotion 프로젝트 생성 

video 폴더를 만들고 그 안에서 Remotion을 초기화합니다.

cd automation-project
npx create-video@latest video
*설치오류 시 brew install node 설치 후 재실행

명령어를 입력하면 터미널에 몇 가지 질문이 나옵니다. 아래와 같이 선택하세요.
Select a template: HelloWorld 엔터
Add TailwindCSS?: Yes 엔터

• 주의: M4의 성능을 쓰기 위해 brew install ffmpeg가 미리 되어 있어야 합니다.

Step 2: Remotion 정상 작동 확인 (중요!)

렌더링을 자동화하기 전에, 네이티브 환경에서 Remotion이 정상적으로 비디오를 그리는지 확인해야 합니다.

cd video

npm install

#version이 정상적으로 출력되는지 확인
npx remotion --version

#브라우저에 remotion이 실행되면 성공
npm run dev

• 확인 사항: 위 명령어를 입력하면 브라우저가 열리며 미리보기 화면이 뜹니다. 화면이 잘 보인다면 Ctrl + C를 눌러 종료합니다.

Step 3: FastAPI 백엔드 구성(가상환경으로 구성)

backend 폴더에서 필요한 라이브러리를 설치하고 API 코드를 작성합니다.

cd ../backend
python3 -m venv venv

(명령어를 치고 나면 backend 폴더 안에 venv라는 폴더가 새로 생깁니다.)

Step 4: 가상환경 활성화

이 프로젝트 환경으로 들어가는 작업입니다.

source venv/bin/activate

• 확인: 입력을 마치면 터미널 프롬프트 맨 앞에 (venv) 라는 글자가 생겼는지 확인하세요. 이게 보여야 가상환경에 들어온 것입니다.

Step 4: FastAPI 및 uvicorn 설치

가상환경이 활성화된 상태에서는 pip 명령어를 바로 사용할 수 있습니다.

pip install fastapi uvicorn

Step 5: main.py 파일 생성

터미널(가상환경이 활성화된 상태)에서 파일을 생성합니다.

touch main.py

Step 6: 코드 작성 (main.py)

선호하는 에디터(VS Code 등)로 main.py를 열고 아래 코드를 복사해서 붙여넣으세요. M4 맥미니의 성능을 활용하고 n8n과 연동하기 최적화된 코드입니다.

from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel
import subprocess
import os
import json
import uuid

app = FastAPI()

# 작업 상태 저장소
render_jobs = {}

# 💡 n8n에서 보내는 데이터 구조와 100% 일치해야 합니다.
class RenderRequest(BaseModel):
    title: str = "기본 제목"
    content: str = "기본 내용"
    video_config: str = "HelloWorld"
    job_id: str  # 👈 이 줄이 누락되어 에러가 났던 것입니다!

def render_remotion_video(job_id: str, data: RenderRequest):
    video_dir = os.path.abspath(os.path.join(os.getcwd(), "..", "video"))
    os.makedirs(os.path.join(video_dir, "out"), exist_ok=True)
    
    # 확장자는 Remotion이 알아서 붙이도록 제외하거나 .mp4 명시
    output_filename = f"out/render_{job_id}.mp4"
    
    render_jobs[job_id] = {"status": "processing", "progress": 50}

    cmd = [
        "npx", "remotion", "render",
        data.video_config, output_filename,
        f"--props={json.dumps({'title': data.title, 'content': data.content})}",
        "--codec=h264",
        "--concurrency=10",
        "--overwrite"
    ]

    print(f"🚀 렌더링 시작 (ID: {job_id})")
    result = subprocess.run(cmd, cwd=video_dir)

    if result.returncode == 0:
        render_jobs[job_id] = {
            "status": "completed", 
            "progress": 100, 
            "file_path": f"{video_dir}/{output_filename}"
        }
        print(f"✅ 렌더링 완료 (ID: {job_id})")
    else:
        render_jobs[job_id] = {"status": "failed", "progress": 0}
        print(f"❌ 렌더링 실패 (ID: {job_id})")

@app.post("/render")
async def start_render(data: RenderRequest, background_tasks: BackgroundTasks):
    # 💡 n8n이 보낸 job_id를 사용하여 상태 기록 시작
    job_id = data.job_id
    render_jobs[job_id] = {"status": "queued", "progress": 0}
    
    background_tasks.add_task(render_remotion_video, job_id, data)
    
    return {"status": "started", "job_id": job_id}

@app.get("/status/{job_id}")
async def get_status(job_id: str):
    return render_jobs.get(job_id, {"status": "not_found"})

@app.get("/")
def health():
    return {"status": "ok"}

3. FastAPI 서버 실행하기

이제 작성한 서버를 가동합니다. (가상환경이 켜져 있어야 합니다.)

#경로 이동 후 가상환경 실행
cd ../backend
source venv/bin/activate

#서버 기동
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

• --host 0.0.0.0: Docker 내부의 n8n이 접근할 수 있도록 허용합니다.
• --reload: 코드를 수정할 때마다 서버가 자동으로 재시작됩니다.

---

제대로 작동하는지 테스트

서버가 켜진 상태에서 새로운 터미널을 열어 아래 명령어를 입력하거나, 웹 브라우저에서 http://localhost:8000/에 접속해 보세요.

curl -X POST "http://localhost:8000/render" \
     -H "Content-Type: application/json" \
     -d '{"title": "M4 맥미니 테스트", "content": "n8n과 FastAPI 연동 성공!"}'

 

 

4. n8n에서 FastAPI 호출하기 (핵심 연동)

이제 n8n에서 워크플로우를 만듭니다.

1. HTTP Request 노드 추가
2. Method: POST
3. URL: http://host.docker.internal:8000/render
   • 중요: Docker 내부에서 맥 호스트의 FastAPI에 접근하려면 반드시 host.docker.internal을 사용해야 합니다.
4. Body Parameters: FastAPI의 RenderRequest 모델에 정의한 값들을 넣어줍니다.
   • title: (예: 오늘의 뉴스 요약) — n8n의 이전 노드 데이터를 연결하세요.
   • content: (예: 맥미니 M4에서 렌더링 중입니다.)
   • video_config: HelloWorld (또는 Remotion 프로젝트의 Composition ID)

---

 

정리! 전체 흐름도 (데이터 이동 경로)

1. n8n (Docker): "HTTP Request" 노드가 실행되면서 http://host.docker.internal:8000/render로 데이터를 보냅니다.
2. 맥미니 (Native): 실행 중인 **FastAPI 서버(Uvicorn)**가 이 요청을 받습니다.
3. FastAPI: 받은 데이터를 가지고 터미널 명령(npx remotion render...)을 실행합니다.
4. Remotion: M4 칩의 성능을 사용해 video 폴더에 영상을 생성합니다.