빠른 시작

☁️ Option 0: Cloud (Zero Setup) 자체 호스팅을 원하지 않으신가요? cloud.fim.ai에서 FIM One을 즉시 시도하세요 — Docker 없음, API 키 없음, 구성 없음. 로그인하면 바로 시작할 수 있습니다. 얼리 액세스.

옵션 A: Docker (권장)

로컬 Python 또는 Node.js가 필요 없습니다 — 모든 것이 컨테이너 내부에서 빌드됩니다.

git clone https://github.com/fim-ai/fim-one.git
cd fim-one

# Configure — only LLM_API_KEY is required
cp example.env .env
# Edit .env: set LLM_API_KEY (and optionally LLM_BASE_URL, LLM_MODEL)

# Build and run (first time, or after pulling new code)
docker compose up --build -d

http://localhost:3000 을 열면 첫 실행 시 관리자 계정 생성 과정을 거치게 됩니다. 이것이 전부입니다. 초기 빌드 후, 이후 시작은 다음만 필요합니다:

docker compose up -d          # start (skip rebuild if image unchanged)
docker compose down           # stop
docker compose logs -f        # view logs

데이터는 Docker 명명된 볼륨(fim-data, fim-uploads)에 유지되며 컨테이너 재시작 후에도 유지됩니다. 참고: Docker 모드는 핫 리로드를 지원하지 않습니다. 코드 변경 시 이미지를 다시 빌드해야 합니다(docker compose up --build -d). 라이브 리로드를 사용한 활성 개발의 경우 아래의 옵션 B를 사용하세요.

옵션 B: 로컬 개발

필수 요구사항: Python 3.11+, uv, Node.js 18+, pnpm.

git clone https://github.com/fim-ai/fim-one.git
cd fim-one

cp example.env .env
# Edit .env: set LLM_API_KEY

# Install
uv sync --all-extras
cd frontend && pnpm install && cd ..

# Launch (with hot reload)
./start.sh

명령어	시작되는 항목	URL
`./start.sh`	Next.js + FastAPI	http://localhost:3000 (UI) + :8000 (API)
`./start.sh dev`	동일, 핫 리로드 포함 (Python `--reload` + Next.js HMR)	동일
`./start.sh dev:api`	API만, 개발 모드 (`--reload`)	http://localhost:8000/api
`./start.sh dev:ui`	Next.js만, 개발 모드 (HMR)	http://localhost:3000
`./start.sh api`	FastAPI만 (헤드리스, 통합 또는 테스트용)	http://localhost:8000/api

구성

FIM One은 모든 OpenAI 호환 LLM 제공자와 함께 작동합니다 — OpenAI, DeepSeek, Anthropic, Qwen, Ollama, vLLM 등.

제공자	`LLM_API_KEY`	`LLM_BASE_URL`	`LLM_MODEL`
OpenAI	`sk-...`	(기본값)	`gpt-4o`
DeepSeek	`sk-...`	`https://api.deepseek.com/v1`	`deepseek-chat`
Anthropic	`sk-ant-...`	`https://api.anthropic.com/v1`	`claude-sonnet-4-6`
Ollama (로컬)	`ollama`	`http://localhost:11434/v1`	`qwen2.5:14b`

**Jina AI**는 웹 검색/페치, 임베딩 및 전체 RAG 파이프라인을 활성화합니다(무료 티어 사용 가능). 최소 .env:

LLM_API_KEY=sk-your-key
# LLM_BASE_URL=https://api.openai.com/v1   # default — change for other providers
# LLM_MODEL=gpt-4o                         # default — change for other models

JINA_API_KEY=jina_...                       # unlocks web tools + RAG

모든 구성 옵션의 전체 목록은 환경 변수 참조를 참조하세요.

프로덕션 배포

Docker (권장)

docker compose up -d는 필요한 모든 것을 실행합니다 — 수동 서비스 구성이 필요 없습니다:

서비스	목적	구성 대상
fim-one	API + 프론트엔드	`.env` (LLM 키 등)
Redis	크로스-워커 인터럽트 릴레이	compose에서 자동 구성

docker compose up --build -d   # first time / after code changes
docker compose up -d           # subsequent starts
docker compose logs -f         # view logs
docker compose down            # stop all services

워커를 통한 확장

기본적으로 API는 단일 워커 프로세스로 실행됩니다. 더 많은 동시 사용자를 처리하려면 .env를 통해 워커를 증가시키세요:

WORKERS=4   # number of Uvicorn worker processes

다중 워커 요구사항:

PostgreSQL — SQLite는 단일 쓰기 방식이며 동시 쓰기를 지원하지 않습니다. DATABASE_URL을 PostgreSQL 연결 문자열로 설정하세요.
Redis — Docker Compose에 이미 포함되어 있습니다(자동 구성). 워커 간 인터럽트/인젝트 릴레이를 처리합니다.

WORKERS=1(기본값)인 경우 Redis나 PostgreSQL이 필요하지 않습니다 — SQLite가 잘 작동합니다.

Nginx 역방향 프록시

HTTPS 및 사용자 정의 도메인의 경우 Nginx 역방향 프록시를 앞에 배치하세요:

User → Nginx (443/HTTPS) → localhost:3000

API는 내부적으로 포트 8000에서 실행됩니다 — Next.js는 /api/* 요청을 자동으로 프록시합니다. 포트 3000만 노출하면 됩니다.

코드 실행 샌드박스

코드 실행 샌드박스(CODE_EXEC_BACKEND=docker)를 사용하는 경우 Docker 소켓을 마운트하세요:

# docker-compose.yml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Cloudflare Tunnel

포트를 열지 않는 설정을 위해 Nginx 대신 Cloudflare Tunnel을 사용하세요. 모든 트래픽이 Cloudflare의 엣지를 통해 흐르므로 포트 80/443을 노출하거나, SSL 인증서를 관리하거나, 방화벽 규칙을 구성할 필요가 없습니다.

중국 본토 사용자: Cloudflare Free/Pro/Business 요금제는 중국 본토에 PoP(Points-of-Presence)가 없습니다. 중국 본토의 트래픽은 해외 엣지(일반적으로 미국 서부)로 라우팅되어 빈번한 502 오류와 높은 지연 시간이 발생합니다. 주요 사용자가 중국 본토에 있는 경우 Cloudflare Tunnel을 사용하지 마세요. 중국 본토에 안정적으로 접근하려면 Cloudflare Enterprise with China Network(JD Cloud 파트너십)이 필요합니다.

User → Cloudflare Edge (SSL) → Tunnel → cloudflared → fim-one:3000

설정:

터널 생성

Cloudflare Zero Trust → Networks → Tunnels → Create a tunnel로 이동하세요. 커넥터 유형으로 Cloudflared를 선택하세요.

공개 호스트명 구성

터널 구성에서 공개 호스트명을 추가하세요:

필드	값
Type	`HTTP`
URL	`fim-one:3000`

다른 모든 설정(HTTP Host Header, Chunked Encoding, Timeouts, Access)은 기본값으로 두세요.

URL은 localhost가 아닌 Docker 서비스 이름 fim-one을 사용합니다. cloudflared가 같은 Docker 네트워크의 별도 컨테이너로 실행되기 때문입니다.

터널 토큰 복사

터널의 Configure 페이지에서 설치 명령을 찾으세요 — eyJ...로 시작하는 토큰이 포함되어 있습니다. 복사하세요.

.env에 토큰 추가

# Add to your .env file on the server
CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiNj...

터널 오버레이로 배포

docker compose -f docker-compose.yml -f docker-compose.tunnel.yml build
docker compose -f docker-compose.yml -f docker-compose.tunnel.yml up -d

docker-compose.tunnel.yml 오버레이는 cloudflared 사이드카 컨테이너를 추가합니다. 기본 docker-compose.yml은 변경되지 않으므로 Cloudflare가 없는 커뮤니티 사용자는 계속 docker compose up -d를 사용할 수 있습니다.

이전 DNS 레코드 제거

도메인에 이전에 서버의 IP를 가리키는 A 레코드가 있었다면 Cloudflare DNS에서 삭제하세요. 터널이 자동으로 엣지 엔드포인트를 가리키는 CNAME 레코드를 생성합니다.

서버 포트 닫기

서버의 docker-compose.yml에서 ports 섹션을 제거하거나 주석 처리하세요. 트래픽은 이제 터널을 통해서만 흐르므로 인바운드 포트가 필요하지 않습니다.

Cloudflare Tunnel은 Free를 포함한 모든 요금제에서 무료입니다. 대역폭이나 트래픽 제한이 없습니다.

스크립트 배포 (베어 메탈)

베어 메탈 서버 또는 사용자 정의 프로세스 관리자의 경우 ./start.sh를 직접 사용하세요:

./start.sh           # production mode
./start.sh portal    # same as above (explicit)
./start.sh api       # API only (headless)

이 모드에서는 Redis가 자동으로 포함되지 않습니다. 시스템은 기본적으로 단일 워커, 인프로세스 모드로 실행되며 — 저트래픽 배포에 적합합니다. Redis를 로컬에서 다중 워커로 활성화하려면:

# Start a Redis instance (Docker or system package)
docker run -d --name redis -p 6379:6379 redis:7-alpine

# Add to .env
REDIS_URL=redis://localhost:6379/0
WORKERS=4
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/fim_one

왜 FIM One인가

시작하기

구성

통합

기능

FIM One 확장

옵션 A: Docker (권장)

옵션 B: 로컬 개발

구성

프로덕션 배포

Docker (권장)

워커를 통한 확장

Nginx 역방향 프록시

코드 실행 샌드박스

Cloudflare Tunnel

스크립트 배포 (베어 메탈)

​옵션 A: Docker (권장)

​옵션 B: 로컬 개발

​구성

​프로덕션 배포

​Docker (권장)

​워커를 통한 확장

​Nginx 역방향 프록시

​코드 실행 샌드박스

​Cloudflare Tunnel

​스크립트 배포 (베어 메탈)

옵션 A: Docker (권장)

옵션 B: 로컬 개발

구성

프로덕션 배포

Docker (권장)

워커를 통한 확장

Nginx 역방향 프록시

코드 실행 샌드박스

Cloudflare Tunnel

스크립트 배포 (베어 메탈)