dev

Tencent Cloud dev 환경 (VM + Compose)

Environment Overview

서비스	인스턴스 ID	Hostname	DNS
app	ins-90x6jnx5	deck-app-dev	deck-app-dev.tpm.querypie.io
linkpie	ins-6imdjii9	deck-linkpie-dev	deck-linkpie-dev.tpm.querypie.io
deskpie	ins-5ag0g1h5	deck-deskpie-dev	deck-deskpie-dev.tpm.querypie.io

• 공용 배포 키: 1Password Deck - Deployment on Tencent Cloud
• GitHub Actions workflow: .github/workflows/deploy-dev.yml

아키텍처

app / linkpie / deskpie는 각각 전용 VM에서 단독으로 실행합니다 (stage와 동일한 구조).

• 각 서비스는 전용 VM에서 단독으로 실행합니다.
• 이미지 태그를 서비스별로 독립 관리합니다 (APP_IMAGE_TAG, LINKPIE_IMAGE_TAG, DESKPIE_IMAGE_TAG).
• 각 VM에서 nginx 로드밸런서 뒤에 2개 인스턴스로 실행합니다.

VM-app     → nginx:443 → [app-1, app-2]
VM-linkpie → nginx:443 → [linkpie-1, linkpie-2]
VM-deskpie → nginx:443 → [deskpie-1, deskpie-2]

사전 준비

1. Tencent Cloud CLI (tccli) 설치 및 인증

pip install tccli

tccli configure
# SecretId / SecretKey / Region: ap-seoul / Output: json

2. VM 접속

ssh -i ~/.ssh/deck ubuntu@deck-app-dev.tpm.querypie.io
ssh -i ~/.ssh/deck ubuntu@deck-linkpie-dev.tpm.querypie.io
ssh -i ~/.ssh/deck ubuntu@deck-deskpie-dev.tpm.querypie.io

운영 기준 SSH 키는 1Password Deck - Deployment on Tencent Cloud 항목입니다. 문서의 ~/.ssh/deck 경로는 로컬 저장 예시일 뿐입니다. GitHub Actions secret DEV_DEPLOY_SSH_KEY도 같은 개인키 내용을 사용합니다.

3. VM에 Docker + Compose 설치

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker compose version

4. 이미지 레지스트리

이미지 레지스트리(ireg.querypie.io/ci)는 별도 인증 없이 pull 가능합니다.

배포

초기 설정

git clone git@github.com:chequer-io/deck.git deck && cd deck

cp deploy/compose/tencent/dev/.env.example deploy/compose/tencent/dev/.env
# ⚠️ .env는 GHA 배포 워크플로우가 매 배포 시 envsubst로 자동 생성합니다.
#    테스트/디버깅 목적으로 일시 편집할 수 있지만, 다음 배포에서 덮어써집니다.
#    영구 변경은 .env.example 또는 GHA secrets를 통해 수행하세요.

필수 운영값:

• APP_BASE_URL
• DATABASE_URL
• APP_CRYPTO_CURRENT_PROVIDER=ENV
• APP_CRYPTO_PROVIDERS_ENV_KEK
• APP_CRYPTO_PROVIDERS_ENV_KEK_KID (선택, 기본값 kek-v1)

앱은 split datasource env를 읽지 않고 DATABASE_URL만 사용한다. 현재 Tencent compose 샘플은 ENV 단일 KEK 운영만 문서화한다.

• bundled PostgreSQL의 비밀번호는 compose.yml의 DB_PASSWORD 기본값(deck)으로 설정된다. DATABASE_URL의 password도 이 값과 일치해야 한다.
• DATABASE_URL의 user, password에 &, =, %, ?, # 같은 reserved character가 들어가면 percent-encoding해서 넣는다.

TLS 인증서 초기 발급 (최초 1회)

각 VM별 도메인:

VM	도메인
app VM	deck-app-dev.tpm.querypie.io
linkpie VM	deck-linkpie-dev.tpm.querypie.io
deskpie VM	deck-deskpie-dev.tpm.querypie.io

# 1. certbot 설치
sudo apt-get update && sudo apt-get install -y certbot

# 2. nginx 중지 후 standalone 모드로 발급
#    nginx가 실행 중이면: docker compose --profile <SERVICE> stop nginx-<SERVICE>
sudo certbot certonly --standalone \
  -d <이 VM의 도메인> \
  --email infra@querypie.com --agree-tos --non-interactive

apt install certbot 시 systemd timer(certbot.timer)가 자동 등록되어 인증서 갱신이 자동화됩니다.

서비스 시작

cd deploy/compose/tencent/dev
SERVICE=app  # app | linkpie | deskpie
docker compose --profile ${SERVICE} up -d

TLS 인증서 갱신

certbot 설치 시 systemd timer가 자동 등록되므로 별도 crontab 설정이 필요 없습니다. 갱신 후 nginx reload를 위해 리포의 deploy hook 스크립트를 심링크합니다.

# deploy hook 등록 (최초 1회)
sudo ln -sf /home/ubuntu/deck/deploy/shared/scripts/certbot-deploy-hook.sh \
  /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

# timer 상태 확인
systemctl list-timers certbot.timer

수동 갱신이 필요한 경우: sudo certbot renew

무중단 롤링 배포

nginx upstream drain/rejoin 방식으로 한 replica씩 순서대로 교체한다. 배포는 compose-rollout.sh 스크립트를 통해 수행한다.

cd /home/ubuntu/deck/deploy/compose/tencent/dev
bash /home/ubuntu/deck/deploy/shared/scripts/compose-rollout.sh <service> false deck-dev_db-data

# 예시
bash /home/ubuntu/deck/deploy/shared/scripts/compose-rollout.sh app false deck-dev_db-data

상세 프로토콜, 실패 시나리오별 대응, 격리 상태 복구 방법: docs/reference/infra/rolling-deployment.md

롤백

.env의 이미지 태그를 이전 버전으로 변경 후 동일한 절차를 수행한다.

# .env에서 <SERVICE>_IMAGE_TAG를 이전 태그로 변경 후 (예: APP_IMAGE_TAG, LINKPIE_IMAGE_TAG, DESKPIE_IMAGE_TAG)
cd /home/ubuntu/deck/deploy/compose/tencent/dev
bash /home/ubuntu/deck/deploy/shared/scripts/compose-rollout.sh <service> false deck-dev_db-data

리소스 확인

docker compose ps
docker compose logs -f app-1 app-2
docker stats