{#deployment-deployment}
# 배포

AgensGraph 서버가 운영 트래픽을 받기 전에 정해야 할 것들입니다. 소프트웨어를 장비에 올리는
절차는 [AgensGraph 설치](../get_started/install.md)에 있고, 이 페이지는 그 주변의 선택을
다룹니다.

{#deployment-platforms}
## 플랫폼

AgensGraph는 Linux와 Windows에서 빌드·실행되며, 개발용으로는 macOS에서도 됩니다. 배포는 대부분
Linux에서 이루어집니다. 시험한 배포판은 Rocky Linux·RHEL·Debian·Ubuntu의 현재 릴리스입니다.
[컨테이너 이미지](#install-docker)는 Debian trixie와 bookworm, Rocky 9와 10, 그리고 Alpine 위에서
빌드됩니다.

AgensGraph의 어떤 점도 PostgreSQL의 플랫폼 지원 범위를 좁히지 않으므로,
[PostgreSQL의 지원 플랫폼 안내](https://www.postgresql.org/docs/18/installation-platform-notes.html)가
그대로 적용됩니다.

{#deployment-sizing}
## 용량 산정

권장값 표가 아니라 데이터에서 출발하십시오.

**가장 크게 작용하는 지렛대는 메모리입니다.** 그래프 순회는 인덱스를 따라 흩어진 페이지로 간선을
따라가므로 임의 접근 작업입니다. 캐시 밖의 임의 접근은 느립니다. 작업 집합 — 쿼리가 훑는 레이블과 그
인덱스 — 이 운영체제 캐시에 들어가는 것을 목표로 삼으십시오. `shared_buffers`와
`effective_cache_size`를 그에 맞춰 잡으십시오. 방법은 [설정](#configuration-memory)에 있습니다.

무엇을 상대하고 있는지 보려면:

```sql
SELECT l.labname,
       pg_size_pretty(pg_total_relation_size(l.relid)) AS total
FROM pg_catalog.ag_label l
  JOIN pg_catalog.ag_graph g ON g.oid = l.graphid
WHERE g.graphname = 'moviekb'
ORDER BY pg_total_relation_size(l.relid) DESC;
```

간선 레이블은 대개 그래프에서 가장 큰 객체이고 자체 인덱스를 셋 지니므로, 행뿐 아니라 인덱스까지
계산에 넣으십시오.

**스토리지는 플래시여야 합니다.** 처리량 때문이 아니라 임의 읽기 지연 때문입니다. 순회가 시간을
쓰는 곳이 거기입니다. 그것은 플래너 설정도 바꿉니다.
[설정](#configuration-planner-settings-that-matter-for-traversal)의 `random_page_cost`를
참고하십시오.

**CPU는 순회에서는 생각보다 덜 중요하고**, 레이블 전체를 훑는 분석 쿼리에서는 생각보다 더
중요합니다. 앞은 대체로 직렬이고 뒤는 병렬화되기 때문입니다.

쓸 만한 무엇이든 하려면 RAM은 최소 4 GB입니다. 디스크는 데이터와 인덱스, WAL, 그리고 인덱스를
만들 여유까지 잡으십시오. 기본 설치 자체에 약 2.5 GB가 듭니다.

{#deployment-before-the-first-start}
## 처음 기동하기 전에

**서버는 그 자신의 권한 없는 사용자로 실행하십시오.** root도 아니고, 애플리케이션과 함께 쓰는
로그인 계정도 아닙니다:

```shell
useradd --system --home /var/lib/agensgraph --shell /usr/sbin/nologin agens
```

가능하다면 **데이터 디렉터리를 자기 파일시스템에 두십시오.** 그래야 그것이 가득 차도 장비의
나머지를 함께 끌고 가지 않고, 따로 스냅샷을 뜰 수 있습니다.

```shell
install -o agens -g agens -m 0700 -d /var/lib/agensgraph/18/data
sudo -u agens initdb -D /var/lib/agensgraph/18/data
```

`initdb`는 데이터 디렉터리에 0700이나 0750 모드를 요구합니다. PostgreSQL 18에서는 데이터 페이지
체크섬도 기본으로 켭니다. 그대로 두는 편이 좋고, 나중에 이 클러스터로 업그레이드할 때 플래그 하나를
좌우하므로 알아 둘 만합니다.
[2.18로 업그레이드하기](#upgrade-to-218-step-2-initialize-the-new-cluster)를 참고하십시오.

**커널 자원**은 손댈 일이 드뭅니다. AgensGraph는 9.3 이후의 PostgreSQL이 그렇듯 주 공유 메모리에
익명 mmap을 쓰고 System V 세그먼트는 아주 작게만 쓰므로, 예전의 `SHMMAX` 조정은 필요 없습니다.
여전히 발목을 잡을 수 있는 것은 메모리가 빠듯한 호스트에서의 `vm.overcommit_memory`와 OOM 킬러, 그리고
접속이 많은 서버에서의 열린 파일 제한입니다.
[PostgreSQL의 커널 자원 절](https://www.postgresql.org/docs/18/kernel-resources.html)이
레퍼런스입니다.

{#deployment-running-under-systemd}
## systemd에서 운영하기

인스턴스 하나를 위한 유닛입니다:

```ini
[Unit]
Description=AgensGraph 2.18
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
User=agens
Group=agens
Environment=AGDATA=/var/lib/agensgraph/18/data
ExecStart=/usr/local/agensgraph/bin/postgres -D ${AGDATA}
ExecReload=/bin/kill -HUP $MAINPID
KillMode=mixed
KillSignal=SIGINT
TimeoutStopSec=120
OOMScoreAdjust=-900

[Install]
WantedBy=multi-user.target
```

`postgres`를 직접 기동하는 `Type=notify` 구성이 systemd가 가장 잘 다루는 형태입니다. 서버가
실제로 접속을 받기 시작한 시점을 systemd에 알려 주고, `systemctl stop`이 깨끗한 종료를 하도록
유지합니다. `OOMScoreAdjust`는 커널이 postmaster보다 백엔드를 먼저 죽이도록 만듭니다.

임시 작업에는 `ag_ctl`을, 서비스에는 systemd를 쓰십시오. 손으로 기동하고 systemd로 정지하는 식으로
둘을 섞으면 postmaster가 유령처럼 남게 됩니다.

{#deployment-connections}
## 접속

**`listen_addresses`** 는 `initdb` 직후 `localhost`입니다. 넓힐 때는 의도를 가지고, 아래의 인증
규칙과 함께해야 합니다.

**`max_connections`** 의 기본값은 100입니다. 접속마다 메모리가 들고 그래프 쿼리는 `work_mem`
할당을 여러 개 동시에 쓸 수 있으므로, 이 값을 올리는 것은 공짜가 아닙니다. 짧게 살다 가는 접속을
많이 여는 애플리케이션 앞에는 커넥션 풀러를 두십시오. AgensGraph는 PostgreSQL 프로토콜을 쓰므로
PgBouncer와 Pgpool-II가 그대로 동작합니다.

**인증**은 `pg_hba.conf`이며, 로컬 접속의 기본값인 `trust`는 그대로 둘 것이 아닙니다.
[보안](security.md)을 참고하십시오.

{#deployment-replication-and-high-availability}
## 복제와 고가용성

그래프는 테이블이고 WAL은 그 차이를 알지 못하므로, 스트리밍 복제·논리 복제·동기 커밋이 모두
그래프에서 동작합니다. 따라서 대기 서버는 추가 설정 없이 그래프 데이터를 담고, 읽기 전용 그래프
쿼리는 핫 스탠바이에서 실행됩니다.

AgensGraph에만 해당하는 것 둘입니다:

* 그래프 쓰기는 병렬화되지 않으므로, 쓰기가 많은 그래프 워크로드는 주 서버에서 문장 하나에 코어
  하나를 넘겨 쓰지 않습니다. 이는 복제의 동작이 아니라 쓰기 처리량을 어떻게 계획할지에
  영향을 줍니다.
* 대기 서버를 승격한 뒤, 또는 어떤 물리 복원 뒤에도 `ag_graph.graphmeta_valid`를 확인하고 거짓이면
  `regather_graphmeta()`를 실행하십시오.
  [그래프 메타데이터](../system_catalogs/graph-metadata.md)를 참고하십시오.

자동 장애 조치에는 보통 Patroni를 씁니다. PostgreSQL에서와 마찬가지로 AgensGraph에서도
동작합니다.

{#deployment-a-pre-production-checklist}
## 운영 투입 전 점검 목록

* `postgresql.conf`를 [설정](configuration.md)에 비추어 검토했는가. 특히 `shared_buffers`·
  `work_mem`·`effective_cache_size`·`random_page_cost`.
* `pg_hba.conf`에 `trust` 규칙이 없고, `listen_addresses`가 필요 이상으로 넓지 않은가.
* 백업이 돌고 있고 복원을 시험했는가. [백업과 복구](#backup-what-to-check)에 따라 그래프 개수까지
  확인했는가.
* 최근 쓰기를 잃는 것이 용납되지 않는다면 WAL 아카이빙을 켰는가.
* 느린 쿼리가 흔적을 남기도록 `log_min_duration_statement`를 설정하고 `auto_explain`을
  올렸는가.
* 접속 수·복제 지연·캐시 적중률·디스크 여유를 감시하고 있는가.
* `autovacuum`을 켜 둔 채로 두었는가. 간선 레이블은 자주 바뀌며, autovacuum을 끄는 것이 그래프
  데이터베이스가 데이터의 두 배 크기인 테이블을 갖게 되는 경로입니다.
* `auto_gather_graphmeta`를 의도를 가지고 정했는가. 켜서 플래너의 스캔 쳐내기를 위해 쓰기마다
  조금씩 치르거나, 꺼 두고 정해진 일정에 다시 수집하거나.
* 간선 레이블의 통계 목표치를 확인했는가. 특히 클러스터를 2.17에서 업그레이드했다면.
  [2.18로 업그레이드하기](#upgrade-to-218-step-6-post-upgrade-tasks)를 참고하십시오.