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

# JupyterHub

**멀티 사용자 Jupyter 노트북 서버**입니다. 여러 사용자가 각자의 Jupyter 노트북 환경을 독립적으로 사용할 수 있습니다.

## 어디에 쓰이나요?

* **교육 환경**: 수강생 각자에게 독립적인 Jupyter 노트북 환경 제공
* **팀 개발**: 데이터 분석팀, 머신러닝 엔지니어팀이 공유 서버에서 각자의 노트북 사용
* **GPU 공유**: 하나의 GPU 서버를 여러 사용자가 나누어 사용
* **환경 통일**: 모든 사용자가 동일한 Python 패키지, 라이브러리 환경에서 작업

일반 Jupyter Notebook은 1명의 사용자만 사용할 수 있지만, JupyterHub는 **여러 사용자가 동시에** 접속하여 각자의 노트북을 실행합니다.

## Docker Compose

```yaml docker-compose.yml theme={null}
services:
  jupyterhub:
    image: quay.io/jupyterhub/jupyterhub:latest
    container_name: jupyterhub
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - jupyterhub_data:/srv/jupyterhub
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DOCKER_NETWORK_NAME=jupyterhub-network
    command: jupyterhub --ip 0.0.0.0

volumes:
  jupyterhub_data:
```

<Note>
  위는 기본 설정입니다. 실제 운영 시에는 `jupyterhub_config.py` 파일로 인증 방식, 스포너(Spawner) 설정 등을 구성합니다. Docker 기반 스포너를 사용하면 각 사용자마다 별도의 컨테이너가 생성됩니다.
</Note>

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

브라우저에서 `http://localhost:8000`으로 접속합니다.

## 기본 정보

| 항목      | 값    |
| ------- | ---- |
| 웹 UI 포트 | 8000 |

## 라이선스

| 구분     | 내용                       |
| ------ | ------------------------ |
| 라이선스   | BSD 3-Clause             |
| 개인 사용  | 자유롭게 사용 가능               |
| 상업적 사용 | 자유롭게 사용 가능, 수정/재배포 제한 없음 |

## 참고

* [JupyterHub 공식 문서](https://jupyterhub.readthedocs.io/)
* [JupyterHub GitHub](https://github.com/jupyterhub/jupyterhub)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Trackio" icon="arrow-right" href="/stacks/trackio">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>