게이트웨이 직접 운영하기

Label 309 레코드를 검증하는 데에는 누구에게서도 아무것도 필요하지 않습니다. 계정도, 서버도, 키도 필요 없습니다. 게시는 그 나머지 절반입니다. 게시는 Cardano에 트랜잭션을 올리는 일이고, 여기에는 수수료가 듭니다. 그 수수료를 지불하는 것이 바로 게이트웨이입니다. 게이트웨이는 레코드를 온체인에 기록하는, 자금이 마련된 Cardano 지갑(그리고 봉인된 파일을 위한 Arweave 지갑)을 보유하며, 트랜잭션을 구성해 제출하고, 확정될 때까지 추적하며, 단독 검증을 위해 레코드를 다시 제공합니다.

대부분의 경우에는 SDK나 CLI를 다른 사람이 운영하는 게이트웨이로 향하게 합니다. 하지만 이 백엔드 전체가 오픈 소스이므로(label-309-gateway, Rust 바이너리 하나에 Postgres를 더한 구성), 직접 운영할 수도 있습니다. 자신의 앱을 위해 개인용으로 하나 운영해도 되고, 유료 서비스로 다른 사람에게 제공해도 됩니다. 이 게이트웨이는 설계상 멀티테넌트이며, 하나의 인스턴스 아래에 여러 계정과 API 키를 둡니다. 이 가이드는 레퍼런스 Docker Compose를 사용하여, 아무것도 없는 상태에서 가격이 산정된 첫 견적을 받는 데까지 안내합니다.

시작하기 전에

Docker와 Docker Compose가 필요하며, 여유 디스크가 몇 기가바이트 있는 호스트도 필요합니다. 아래의 모든 내용은 Cardano preprod를 대상으로 합니다. 배포를 띄울 때 취할 수 있는 안전한 방식이기 때문입니다. 메인넷으로의 전환은 나중에, 배포에 자금이 채워지고 검증이 끝난 뒤에 의도적으로 내리는 결정입니다.

코드를 받고 설정 파일 작성하기

저장소를 클론한 다음, 레퍼런스 docker-compose.yml이 있는 deploy/에서 작업하십시오. 예제 설정을 복사한 뒤, 네트워크·수수료 대역·스토리지·가격 등 배포 환경에 맞게 수정하십시오.

git clone https://github.com/cardanowall/label-309-gateway
cd label-309-gateway/deploy
cp ../gateway.example.toml gateway.toml

이 예제 파일에는 주석이 달려 있고 이미 preprod를 대상으로 하므로, 처음 실행할 때 그대로 부팅됩니다.

키링 만들기

게이트웨이가 사용하는 모든 서명 키는 age로 암호화된 키링 파일 하나에 담깁니다. 먼저 키링을 만든 다음, Cardano 키(preprod), Arweave 키, 그리고 webhook-wrap 키를 추가하십시오. 이 keyring 단계들은 gateway 바이너리를 직접 실행합니다. 키링은 신뢰할 수 있는 머신에서 만들어 그 암호화된 파일만 컨테이너로 복사하도록 설계되어 있으므로, 이 단계에서만큼은 저장소에서 릴리스 빌드를 받아 사용하십시오.

mkdir -p secrets
printf '%s' 'a-strong-passphrase' > secrets/gateway-keyring-passphrase
export GATEWAY_KEYRING_PASSPHRASE="$(cat secrets/gateway-keyring-passphrase)"

gateway keyring init             --path secrets/gateway-keyring.age
gateway keyring add-cardano      --path secrets/gateway-keyring.age --network preprod
gateway keyring add-arweave      --path secrets/gateway-keyring.age
gateway keyring add-webhook-wrap --path secrets/gateway-keyring.age
chmod 600 secrets/*

각 add- 단계는 방금 만든 주소를 출력합니다. 출력된 두 주소에 자금을 넣으십시오. Cardano 주소는 온체인 기록 수수료를 지불하고, Arweave 주소는 봉인된 파일의 스토리지 크레딧을 충당합니다. 그런 다음, compose가 읽어 들이는 데이터베이스 비밀번호를 설정하십시오.

echo 'POSTGRES_PASSWORD=a-strong-db-password' > .env

띄우기

먼저 운영자를 프로비저닝하십시오. 이 과정에서 마이그레이션이 적용되고 루트 시크릿이 단 한 번만 출력됩니다. 안전한 곳에 보관하십시오. 이것은 컨트롤 플레인의 마스터 자격 증명입니다.

docker compose run --rm gateway operator bootstrap --label acme

그런 다음 Postgres와 게이트웨이를 시작하십시오.

docker compose up -d

지갑, 계정, 키 등록하기

compose는 일부러 호스트 포트를 공개하지 않습니다. 데이터 플레인과 컨트롤 플레인이 소켓 하나를 공유하므로, 포트를 노출하면 컨트롤 플레인까지 노출되기 때문입니다. 컨트롤 플레인은 컨테이너 안에서 다루십시오. 셸을 여십시오.

docker compose exec gateway sh

bootstrap이 출력한 루트 시크릿으로 로컬 컨트롤 플레인을 가리킨 다음, 자금이 채워진 Cardano 지갑(keyring add-cardano가 출력한 주소)을 등록하고, 계정을 만들어 크레딧을 지급하며, 게시 권한으로 범위를 지정한 데이터 플레인 API 키를 발급하십시오.

export GATEWAY_CONTROL_URL=http://127.0.0.1:8080/control/v1
export GATEWAY_CONTROL_TOKEN='ctl_…the root secret from bootstrap…'

gateway admin wallet register primary addr_test1… preprod
gateway admin account create
gateway admin account fund <account_id> 10000000 "starter credit"   # $10
gateway admin key create <account_id> poe:create,poe:read,account:read

key create는 데이터 플레인을 구동하는 API 키를 출력합니다. 이 키와 베이스 URL만 있으면 앱에 필요한 모든 것이 갖춰집니다.

첫 견적 받기

설정 과정에서 호스트로부터 데이터 플레인에 접근하려면, docker-compose.yml의 루프백 ports 매핑(127.0.0.1:8080:8080)의 주석을 해제하고 docker compose up -d를 다시 실행하십시오. 반드시 루프백만 사용하고, 절대 0.0.0.0을 쓰지 마십시오. 그런 다음, 방금 발급한 API 키로 가격을 고정하십시오.

curl -sS -X POST http://127.0.0.1:8080/api/v1/poe/quote \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"record_bytes":256,"recipient_count":0,"file_bytes_total":0}'

응답에는 15분간 유효한 quote_id와 비용 내역이 담겨 있습니다. 게시 호출은 이 quote_id를 잔액 차감과 함께 원자적으로 소비합니다. SDK 가이드에서 쓰는 것과 똑같은 2단계 형태, 즉 가격을 고정한 다음 제출하는 방식입니다. 이제 여러분의 게이트웨이가 살아 있습니다.

다음으로 나아갈 곳

실행 중인 바이너리는 자체 대화형 API 레퍼런스를 제공합니다. 데이터 플레인은 /api/v1/docs에, 컨트롤 플레인은 /control/v1/docs에 있으며, 각각 완전히 오프라인으로 렌더링됩니다. 저장소의 두 문서가 더 깊이 다룹니다. 운영자 런북은 자금 마련, 자격 증명, 자금 처리 방식, 그리고 운영 단계의 실무를 다루고, 통합 가이드는 그 위에 제품을 만드는 법을 다룹니다.

여러분 게이트웨이의 데이터 플레인이 바로 SDK와 CLI 가이드에서 말하는 베이스 URL입니다. https://your-gateway.example를 이제 여러분이 관리하는 주소로 바꾸고, API 키를 나눠 준 다음, 온전히 여러분의 것인 백엔드에서 첫 PoE를 게시해 보십시오.