> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 빠른 시작

> 몇 분 안에 FIM One을 실행하거나 클라우드 버전을 즉시 시도하세요.

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

## 옵션 A: Docker (권장)

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

```bash theme={null}
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](http://localhost:3000) 을 열면 첫 실행 시 관리자 계정 생성 과정을 거치게 됩니다. 이것이 전부입니다.

초기 빌드 후, 이후 시작은 다음만 필요합니다:

```bash theme={null}
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](https://docs.astral.sh/uv/), Node.js 18+, pnpm.

```bash theme={null}
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](http://localhost:3000) (UI) + :8000 (API) |
| `./start.sh dev`     | 동일, 핫 리로드 포함 (Python `--reload` + Next.js HMR) | 동일                                                                |
| `./start.sh dev:api` | API만, 개발 모드 (`--reload`)                       | [http://localhost:8000/api](http://localhost:8000/api)            |
| `./start.sh dev:ui`  | Next.js만, 개발 모드 (HMR)                          | [http://localhost:3000](http://localhost:3000)                    |
| `./start.sh api`     | FastAPI만 (헤드리스, 통합 또는 테스트용)                    | [http://localhost:8000/api](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](https://jina.ai/)\*\*는 웹 검색/페치, 임베딩 및 전체 RAG 파이프라인을 활성화합니다(무료 티어 사용 가능).

최소 `.env`:

```bash theme={null}
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
```

모든 구성 옵션의 전체 목록은 [환경 변수](/configuration/environment-variables) 참조를 참조하세요.

## 프로덕션 배포

### Docker (권장)

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

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

```bash theme={null}
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`를 통해 워커를 증가시키세요:

```bash theme={null}
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 소켓을 마운트하세요:

```yaml theme={null}
# docker-compose.yml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

#### Cloudflare Tunnel

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

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

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

**설정:**

<Steps>
  <Step title="터널 생성">
    [Cloudflare Zero Trust](https://one.dash.cloudflare.com/) → Networks → Tunnels → **Create a tunnel**로 이동하세요.
    커넥터 유형으로 **Cloudflared**를 선택하세요.
  </Step>

  <Step title="공개 호스트명 구성">
    터널 구성에서 공개 호스트명을 추가하세요:

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

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

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

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

  <Step title=".env에 토큰 추가">
    ```bash theme={null}
    # Add to your .env file on the server
    CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiNj...
    ```
  </Step>

  <Step title="터널 오버레이로 배포">
    ```bash theme={null}
    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`를 사용할 수 있습니다.
  </Step>

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

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

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

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

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

```bash theme={null}
./start.sh           # production mode
./start.sh portal    # same as above (explicit)
./start.sh api       # API only (headless)
```

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

Redis를 로컬에서 다중 워커로 활성화하려면:

```bash theme={null}
# 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
```