서버 설치 (docker compose)

표준 설치는 자체 완결형 tarball 과 sudo ./install.sh 입니다. tarball 은 모든 docker 이미지 (ongrid, ongrid-web, singchia/frontier) 를 포함하므로 Docker Hub 풀이 없습니다 — 제한된 네트워크와 에어갭에서도 동작합니다.

에어갭 세부 사항은 에어갭 설치 를 참고하세요. 더 빠른 가이드는 Quickstart 를 참고하세요. docker 없는 systemd 네이티브 설치는 Linux server platform 을 참고하세요.

사전 요건

Linux 호스트:

최소 4 GB RAM, 8 GB 권장 (Prometheus + Loki + Tempo + MySQL + 매니저가 모두 여기에 살고 있습니다).
/var/lib/ongrid (데이터 루트) 아래 20 GB 여유 디스크. ONGRID_DATA_DIR=… 로 다른 위치 지정 가능 — NFS / iSCSI / NVMe 모두 가능하며, 단순한 bind-mount 입니다.
docker compose v2 서브커맨드를 가진 Docker ≥ 24 (docker compose version 이 출력되어야 함).
openssl — install.sh 가 첫 부팅에서 tls.crt / tls.key 가 없을 때 self-signed TLS 인증서를 생성하는 데 사용.
브라우저와 모든 edge 로부터의 인바운드 TCP/443 개방.
모든 edge 로부터의 인바운드 TCP/40012 개방 (frontier 브로커).
모든 edge 가 도달 가능한 공인 IP 또는 도메인. ONGRID_PUBLIC_URL 에 들어가며, 가장 흔한 오설정입니다.

ONGRID_PUBLIC_URL 에 사설 IP 사용 금지

installer 가 IP 를 자동 감지하여 확인을 요청합니다. 10.x / 192.168.x / 172.16-31.x 주소를 수락했는데 edge 가 공인 인터넷에 있다면 로그와 트레이스가 조용히 push 실패합니다. 컨트롤 플레인 터널은 여전히 동작 (자체 포트로 nginx 와 독립) 하므로 UI 에서 edge 는 정상으로 보이지만 Loki 와 Tempo 는 비어 있게 됩니다.

설치

bash

# 최신 태그는 https://github.com/ongridio/ongrid/releases 에서
VER=v0.7.159

gh release download "$VER" \
    --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'

# sha256 검증 — 각 릴리스에 .sha256 사이드카가 함께 옵니다.
sha256sum -c "ongrid-${VER}-linux-amd64.tar.xz.sha256"

tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"

sudo ./install.sh

유용한 플래그:

Flag	What
`--mode systemd`	네이티브 systemd 설치 (docker 없음) 로 전환. `systemd/install-systemd.sh` 로 디스패치. Linux server platform 참고.
`--with-deps`	systemd 전용. apt/dnf 로 `mariadb` + `nginx` + `grafana` 자동 설치, sha256 검증으로 pinned prom / loki / tempo / qdrant 바이너리 다운로드.
`--profile monitoring`	compose 전용. Prometheus 9090 을 호스트에 노출 (랩탑 개발에 유용; prod 에서는 기본 off).
`--no-seed`	compose 전용. 관리자 부트스트랩 배너 출력 생략 (재설치 시).
`--force`	compose 전용. 기존 설치 위에 재설치 (`.env` 와 데이터 볼륨 보존).

install.sh 가 하는 일

순서대로:

Preflight. docker CLI 가 $PATH 에 있고, daemon 에 접근 가능하고, docker compose v2 가 존재함을 검증. 그중 하나라도 실패하면 조기 종료.
설정 스테이징 을 ${ONGRID_INSTALL_DIR:-/opt/ongrid}/ 에:
- docker-compose.yml, .env.example, VERSION, frontier.yaml,
- prometheus.yml (prom 컨테이너 /etc/prometheus/ 에 bind-mount),
- prometheus-rules.yml (ADR-026 self-observability 알림),
- loki-config.yaml, tempo-config.yaml,
- grafana/ provisioning,
- searxng/ 설정,
- edge/ (arch 별 edge 바이너리 + 플러그인 바이너리 + 업그레이드 번들).
${ONGRID_DATA_DIR:-/var/lib/ongrid}/ 아래 호스트 데이터 디렉터리 생성 및 각 컨테이너 이미지가 실행되는 uid 로 chown:
- mysql/ → 999:999 (mysql:8.0)
- prometheus/ → 65534:65534 (prom 은 nobody 로 실행)
- loki/ → 10001:10001
- tempo/ → 10001:10001
- grafana/ → 472:472
- embeddings/ → 65532:65532 (매니저 nonroot 사용자)
첫 부팅에서 이를 놓치면 prom/loki/tempo/grafana 가 permission denied on /<datadir> 로 크래시합니다.
오프라인 RAG 용 번들 임베딩 모델 스테이징 — /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/. 이미 커스텀 모델로 교체했다면 installer 는 건드리지 않습니다.
nginx 설정 새로고침 을 tarball 에서 수행, ${INSTALL_DIR}/certs/ 에 인증서가 없으면 365 일 유효 self-signed 인증서 생성 (CN=ongrid, SAN: DNS:ongrid, DNS:localhost, IP:127.0.0.1).
images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar 에서 docker load 로 docker 이미지 로드. 레지스트리 풀 불필요.
.env 생성 또는 재사용. ${INSTALL_DIR}/.env 가 존재하면 유지 (--force 도 운영자 편집 .env 를 덮어쓰지 않음). 없으면 .env.example 에서 복사. 그런 다음 빈 값을 강력한 랜덤 값으로 채움:
- MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD — 24 자,
- ONGRID_JWT_SECRET — 64 자,
- ONGRID_ADMIN_PASSWORD — 20 자 (최종 배너용으로 기록됨),
- GRAFANA_ADMIN_PASSWORD — 20 자.
비어 있으면 ONGRID_PUBLIC_URL 입력 요청. 30 초 카운트다운, 기본 = 베스트 게스 호스트. curl ... | bash 에서도 살아남도록 /dev/tty 를 읽음.
--env-file .env 와 함께 docker compose up -d. -f 인자 없음 — 튜닝용 docker-compose.override.yml 을 추가하면 자동 로드됨.
nginx 를 통해 https://localhost/healthz 폴링 을 최대 60 초간. 매니저의 /healthz 는 MySQL 도달 가능하고 에이전트 커널이 배선되면 200 을 돌려줍니다.
설치 배너 출력 — Web URL, API URL, 터널 엔드포인트, 부트스트랩 관리자 이메일 + 비밀번호 (첫 설치 시에만).

설치 후

다음과 같은 배너가 보입니다.

text

===============================================================
  ongrid installation complete
===============================================================

Install dir:     /opt/ongrid
Version:         v0.7.159

Web UI:          https://203.0.113.10/
API URL:         https://203.0.113.10/api/v1
Tunnel endpoint: 203.0.113.10:40012   (for edges)

TLS: self-signed cert in /opt/ongrid/certs/ — browsers will warn
      on first visit. Replace tls.crt + tls.key with a real cert and
      'docker compose -f /opt/ongrid/docker-compose.yml restart nginx'.

---------------- bootstrap admin ----------------
email:    admin@example.com
password: 9Xp4hKqf1bL2zRq3Wn7v
>> Record this password NOW. It will not be shown again.
-------------------------------------------------

관리자 비밀번호 기록

부트스트랩 비밀번호는 단 한 번 표시됩니다. /opt/ongrid/.env (mode 0600) 에도 저장됩니다. 둘 다 잃으면 reset-admin-password CLI 또는 DB 직접 편집으로 리셋 — 첫 부팅 체크리스트 참고.

스택 검증

bash

# 모든 컨테이너가 Up 이어야 함
sudo docker compose -f /opt/ongrid/docker-compose.yml ps

# 매니저 헬스
curl -fk https://localhost/healthz

# 매니저 로그 tail
sudo docker compose -f /opt/ongrid/docker-compose.yml logs -f ongrid

# UI 접속
open https://<your-host>/   # TLS 경고 수락

TLS 인증서 교체

self-signed 인증서는 시험용으로는 괜찮지만 모든 브라우저가 경고를 표시합니다. 프로덕션에서는 실제 인증서 (Let's Encrypt, 사내 CA 등) 를 /opt/ongrid/certs/ 에 둡니다.

bash

sudo cp fullchain.pem /opt/ongrid/certs/tls.crt
sudo cp privkey.pem   /opt/ongrid/certs/tls.key
sudo chmod 600        /opt/ongrid/certs/tls.key
sudo chmod 644        /opt/ongrid/certs/tls.crt
sudo docker compose -f /opt/ongrid/docker-compose.yml restart nginx

install.sh 와 upgrade.sh 는 운영자 제공 인증서를 절대 덮어쓰지 않습니다.

와일드카드 동작

nginx 는 certs/ 에서 *.crt / *.key 를 제공하지만, 컨테이너가 찾는 파일명은 tls.crt 와 tls.key 뿐입니다. 인증서 매니저 (certbot, acme.sh, cert-manager) 가 표준 사본을 다른 곳에 유지한다면 심볼릭 링크도 무방합니다.

파일 배치

Path	Owner	Purpose
`/opt/ongrid/docker-compose.yml`	root	Compose 정의.
`/opt/ongrid/.env`	root, 0600	시크릿 + 튜너블.
`/opt/ongrid/certs/`	root, 0700	`tls.crt`, `tls.key`.
`/opt/ongrid/edge/`	root	Edge 바이너리, 업그레이드 번들 (`edge-bundle-<arch>-<ver>.tar.gz`), `install.sh`, `apply-pending-upgrade.sh`. nginx 가 `/edge/` 에서 읽기 전용 제공.
`/opt/ongrid/prometheus.yml`	root	Prom scrape + remote_write 설정.
`/opt/ongrid/grafana/`	root	Provisioning yamls (datasources, dashboards).
`/var/lib/ongrid/mysql/`	999:999	MySQL 데이터. 백업 대상.
`/var/lib/ongrid/prometheus/`	65534:65534	Prom TSDB. 기본 90 일 보존, 20GB 상한.
`/var/lib/ongrid/loki/`	10001:10001	Loki 청크 + 인덱스.
`/var/lib/ongrid/tempo/`	10001:10001	Tempo 블록.
`/var/lib/ongrid/qdrant/`	root	벡터 저장소.
`/var/lib/ongrid/grafana/`	472:472	Grafana 상태 (dashboards, users, SA 토큰).
`/var/lib/ongrid/embeddings/`	65532:65532	오프라인 BGE 모델 캐시.
`/var/log/ongrid/`	mixed	매니저 로그 파일.

다음은

첫 부팅 체크리스트 — 모델 provider, Prom 보존, public URL, 시간대, 첫 incident.
Edge install — 첫 edge 등록.
Upgrade — upgrade.sh 흐름, stage-then-swap, .previous 롤백.
환경 변수 — 튜닝 가능한 모든 ONGRID_* 환경 변수.

서버 설치 (docker compose) ​

사전 요건 ​

설치 ​

install.sh 가 하는 일 ​

설치 후 ​

스택 검증 ​

TLS 인증서 교체 ​

파일 배치 ​

다음은 ​

서버 설치 (docker compose)

사전 요건

설치

install.sh 가 하는 일

설치 후

스택 검증

TLS 인증서 교체

파일 배치

다음은