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

# ipmideck 실행

> Windows, Linux 또는 Docker에서 ipmideck를 시작하고, 데이터 디렉터리를 찾고, 바인드 오류, 종료, 재시작을 처리합니다.

ipmideck가 [설치](/ko/installation)되면 실행 방식은 크게 두 가지로 나뉩니다.
`ipmideck` 명령으로 시작하는 **호스트 설치**와, 웹 서버를 직접 실행하는
**Docker 컨테이너**입니다. 둘은 다르게 동작합니다. 호스트 명령은 대화형 운영자
콘솔을 제공하는 반면, 컨테이너는 일반 로그만 스트리밍합니다. 이 페이지는 둘 다 다룹니다.

## 호스트 설치: `ipmideck start`

호스트 설치 (pip)에서는 서버가 `ipmideck` 명령으로 시작됩니다. 기본 명령은
`start`입니다.

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck start
  ```

  ```text cmd theme={null}
  ipmideck start
  ```

  ```bash bash theme={null}
  ipmideck start
  ```
</CodeGroup>

서브 명령이 없는 단순한 `ipmideck`는 `ipmideck start`와 동일하게 동작합니다.

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck
  ```

  ```text cmd theme={null}
  ipmideck
  ```

  ```bash bash theme={null}
  ipmideck
  ```
</CodeGroup>

기본적으로 서버는 `0.0.0.0:3000`에 바인드되므로, 가동되면 브라우저에서
`http://<your-ip>:3000`을 엽니다.

<Note>
  `ipmilink`는 동일한 명령의 하위 호환 별칭입니다. `ipmilink start`는
  `ipmideck start`와 정확히 동일하게 동작합니다. 모든 새로운 것에는 `ipmideck`를 사용하세요.
</Note>

실제 터미널 (TTY)에서 `ipmideck start`는 대화형 운영자 콘솔을 엽니다. 동일한 명령이
터미널 없이 실행될 때, 예를 들어 파일로 파이프되거나 프로세스 관리자 아래에서는,
콘솔을 건너뛰고 대신 일반 로그로 서비스합니다. 아래의
[헤드리스 / 비 TTY 모드](#헤드리스--비-tty-모드)를 참조하세요.

## Docker: 컨테이너가 서버를 직접 실행한다

Docker 컨테이너는 `ipmideck` 명령을 실행하지 **않습니다**. 그 이미지는 웹 서버
(uvicorn)를 직접 시작합니다.

```bash theme={null}
docker run --network host ipmideck/ipmideck:latest
```

컨테이너는 `ipmideck` CLI를 결코 호출하지 않으므로, 서브 명령, 플래그, 대화형 콘솔 중
어느 것도 Docker 내부에는 적용되지 않습니다. 컨테이너는 **일반 로그**만 stdout으로
스트리밍하며, 이는 헤드리스 호스트 모드와 정확히 같습니다. 컨테이너는 `0.0.0.0:3000`에
바인드되며, BMC에 UDP 포트 `623`으로 도달할 수 있도록 `--network host`가 필요합니다.
네트워킹 세부 정보는 [설치](/ko/installation)를 참조하세요.

<Note>
  컨테이너는 CLI 플래그가 아니라 `IPMIDECK_` 접두사가 붙은 환경 변수와 `/data`의 볼륨으로
  구성하세요. [구성](/ko/configuration)을 참조하세요. 게시된 이미지는 곧 제공됩니다. 위 명령은
  그것이 활성화되면 실행할 정확한 명령입니다.
</Note>

## 데이터 디렉터리

ipmideck는 `config.yaml`, SQLite 데이터베이스, 자격 증명 암호화 키를 단일 데이터 디렉터리에
씁니다. 그 위치는 플랫폼에 따라 다릅니다.

* **Linux / Docker:** `/data`
* **Windows:** `./data` (`ipmideck`를 실행하는 디렉터리 기준 상대 경로)

어떤 플랫폼에서도 `IPMIDECK_DATA_DIR` 환경 변수로 위치를 재정의할 수 있습니다.

<CodeGroup>
  ```powershell PowerShell theme={null}
  $env:IPMIDECK_DATA_DIR = "C:\ipmideck-data"
  ipmideck start
  ```

  ```text cmd theme={null}
  set IPMIDECK_DATA_DIR=C:\ipmideck-data
  ipmideck start
  ```

  ```bash bash theme={null}
  IPMIDECK_DATA_DIR=/srv/ipmideck ipmideck start
  ```
</CodeGroup>

Docker에서 이미지는 이미 `IPMIDECK_DATA_DIR=/data`를 설정하므로, 컨테이너 재시작에 걸쳐
구성과 기록을 유지하려면 해당 경로를 볼륨으로 영속화하세요.

## 환경 변수 재정의

`config.yaml` 설정을 재정의하는 모든 `IPMIDECK_` 접두사가 붙은 환경 변수는 호스트에서든
Docker에서든 동일하게 작동합니다. 전체 목록은 [구성](/ko/configuration)을 참조하세요. ipmideck가
바인드하는 *방식*을 바꾸는 두 가지는 다음과 같습니다.

| 환경 변수                  | 효과                       |
| ---------------------- | ------------------------ |
| `IPMIDECK_SERVER_HOST` | 바인드 호스트 (기본값 `0.0.0.0`). |
| `IPMIDECK_SERVER_PORT` | 바인드 포트 (기본값 `3000`).     |

<Note>
  환경 변수는 `config.yaml`보다 우선합니다. 호스트 설치에서는 명시적인 명령줄 바인드
  플래그가 환경 변수와 파일 둘 다에 우선합니다.
</Note>

## 포트가 이미 사용 중

바인드 포트에서 무언가 이미 수신 대기 중이면, ipmideck는 다른 인스턴스와 포트를 두고
다투는 대신 시작을 거부합니다. 이를 stderr에 출력하고 상태 `1`로 종료합니다.

```text theme={null}
ERROR: IPMIDeck refused to start — port 3000 is already in use on 0.0.0.0 (another instance may be running).
```

이는 보통 ipmideck의 두 번째 사본이 이미 실행 중이거나, 다른 서비스가 그 포트를
점유했음을 의미합니다. 다른 프로세스를 중지하거나 `IPMIDECK_SERVER_PORT`
(또는 `config.yaml`의 `server.port`)로 포트를 변경한 후 다시 시작하세요.

## 주소를 사용할 수 없음

다른 종류의 실패는 바인드를 요청한 *호스트*를 사용할 수 없을 때입니다. 예를 들어 이 머신에
존재하지 않는 주소, IPv6 전용 인터페이스, 또는 바인드 권한이 없는 특권 포트입니다. ipmideck는
이를 별도로 보고하고 마찬가지로 상태 `1`로 종료합니다.

```text theme={null}
ERROR: IPMIDeck cannot bind 0.0.0.0:3000 — address unavailable or not permitted.
```

`IPMIDECK_SERVER_HOST` (또는 `server.host`)의 값을 확인하세요. 머신에 실제로 존재하는
주소여야 하며, 포트가 바인드 권한이 있는 것인지 확인하세요.

## Ctrl+C로 정상 종료

ipmideck를 중지하려면 **Ctrl+C** (이는 `SIGINT`를 보냅니다. `SIGTERM`도 동일하게 처리됩니다)를
누르세요. 종료는 정상적입니다. 웹 서버가 루프를 빠져나가고, 애플리케이션의 lifespan
종료가 실행되며, **팬 제어가 BMC로 반환되고**, 프로세스는 트레이스백 없이 깨끗하게
종료됩니다.

<Warning>
  종료가 팬 제어를 BMC로 복원하므로, ipmideck가 종료되는 순간 FanPilot은 팬 구동을
  중지합니다. BMC 자체의 팬 정책이 인계받습니다. 이는 의도된 안전장치입니다. 팬 루프의
  동작에 대해서는 [기능](/ko/features)을 참조하세요.
</Warning>

Docker에서 컨테이너는 `SIGTERM` (`docker stop`이 보내는 것)에서 중지되므로, 컨테이너를
중지하면 동일한 정상 종료가 실행됩니다.

## 재시작

재시작이 작동하는 방식은 운영 체제에 따라 다릅니다.

* **Linux (및 기타 POSIX 시스템):** ipmideck는 **제자리에서** 재시작합니다. `config.yaml`을
  다시 읽는 새 프로세스를 다시 시작하며, 동일한 제어 터미널을 유지합니다.
* **Windows:** 제자리 재실행이 없습니다. ipmideck는 깨끗하게 종료하고 명령을 직접 다시
  실행하도록 요청하는 힌트를 출력합니다.

```text theme={null}
IPMIDeck: restart required to apply the new bind.
  Run  ipmideck start  again to restart.
```

Windows에서는 같은 셸에서 `ipmideck start`를 다시 실행하기만 하면, 새 프로세스가 `config.yaml`을
다시 읽고 새 설정을 가져옵니다.

## 헤드리스 / 비 TTY 모드

ipmideck가 연결된 터미널 없이 실행될 때, 파일로 파이프되거나, 리디렉션되거나, 프로세스
관리자 아래에서는, TTY가 없음을 감지하여 **대화형 콘솔을 건너뜁니다**. 대시보드를 정상적으로
서비스하고 대신 **일반 로그**를 stdout으로 스트리밍합니다. 이는 항상 콘솔 없이 실행되는
Docker 컨테이너에서 얻는 출력과 같습니다.

이 모드는 특별한 것이 필요 없습니다. 슈퍼바이저나 파이프라인이 호출하는 방식으로 ipmideck를
시작하고 stdout에서 로그를 읽기만 하면 됩니다.

## 다음 단계

* [설치](/ko/installation): Docker와 pip 자세히.
* [구성](/ko/configuration): `config.yaml`, 환경 변수 재정의, 데이터 위치.
* [문제 해결](/ko/troubleshooting): 연결 및 IPMI 오류.