Add first-run Docker smoke checks

README.ko.md

@@ -31,6 +31,8 @@
 npx @starter-series/create my-service --template docker-deploy
 cd my-service
 # 내 앱 Dockerfile + 코드 추가 후:
+npm run compose:check
+npm run build
 docker compose up
 ```
 
@@ -39,6 +41,8 @@ docker compose up
 ```bash
 git clone https://github.com/starter-series/docker-deploy-starter my-service
 cd my-service
+npm run compose:check
+npm run build
 docker compose up
 ```
 
@@ -58,6 +62,7 @@ rm -rf app/
 
 # 4. 로컬 테스트
 cp .env.example .env
+npm run smoke
 docker compose up
 ```
 
@@ -190,6 +195,10 @@ docker compose up
 # Docker로 로컬 실행
 docker compose up
 
+# 첫 실행 전 credential-free smoke
+npm run compose:check
+npm run build
+
 # Dockerfile 변경 후 재빌드
 docker compose up --build
 
@@ -205,6 +214,9 @@ node scripts/bump-version.js major   # 1.0.0 → 2.0.0
 # Node 테스트: 버전 범프 검증 + /health (200) 및 알 수 없는 경로 (404)
 npm test
 
+# Compose config + Docker 이미지 smoke
+npm run smoke
+
 # 롤백 통합 테스트 (Docker 필요, CI에서도 실행됨)
 bash tests/rollback-integration.sh
 ```

README.md

@@ -31,6 +31,8 @@ Build your app. Push to deploy.
 npx @starter-series/create my-service --template docker-deploy
 cd my-service
 # Add your app's Dockerfile + code, then:
+npm run compose:check
+npm run build
 docker compose up
 ```
 
@@ -39,6 +41,8 @@ docker compose up
 ```bash
 git clone https://github.com/starter-series/docker-deploy-starter my-service
 cd my-service
+npm run compose:check
+npm run build
 docker compose up
 ```
 
@@ -58,6 +62,7 @@ rm -rf app/
 
 # 4. Test locally
 cp .env.example .env
+npm run smoke
 docker compose up
 ```
 
@@ -190,6 +195,10 @@ See **[docs/VPS_DEPLOY.md](docs/VPS_DEPLOY.md)** for a detailed setup guide.
 # Start locally with Docker
 docker compose up
 
+# Credential-free smoke before first run
+npm run compose:check
+npm run build
+
 # Rebuild after Dockerfile changes
 docker compose up --build
 
@@ -205,6 +214,9 @@ node scripts/bump-version.js major   # 1.0.0 → 2.0.0
 # Node tests: version-bump validation + /health (200) and unknown path (404)
 npm test
 
+# Compose config + Docker image smoke
+npm run smoke
+
 # Rollback integration test (needs Docker; also run in CI)
 bash tests/rollback-integration.sh
 ```

package.json

@@ -4,6 +4,9 @@
   "private": true,
   "description": "Test harness for the docker-deploy-starter template (scripts + app).",
   "scripts": {
+    "compose:check": "bash scripts/smoke.sh --config-only",
+    "build": "docker build -t docker-deploy-starter:smoke .",
+    "smoke": "bash scripts/smoke.sh",
     "test": "node --test \"tests/**/*.test.js\""
   }
 }

scripts/smoke.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONFIG_ONLY=0
+if [ "${1:-}" = "--config-only" ]; then
+  CONFIG_ONLY=1
+elif [ "${1:-}" != "" ]; then
+  echo "Usage: bash scripts/smoke.sh [--config-only]" >&2
+  exit 2
+fi
+
+if docker compose version >/dev/null 2>&1; then
+  COMPOSE=(docker compose)
+elif docker-compose version >/dev/null 2>&1; then
+  COMPOSE=(docker-compose)
+else
+  echo "::error::Docker Compose is required (docker compose or docker-compose)." >&2
+  exit 1
+fi
+
+created_env=0
+if [ ! -f .env ]; then
+  if [ ! -f .env.example ]; then
+    echo "::error::.env is missing and .env.example was not found." >&2
+    exit 1
+  fi
+  cp .env.example .env
+  created_env=1
+fi
+
+cleanup() {
+  if [ "$created_env" -eq 1 ]; then
+    rm -f .env
+  fi
+}
+trap cleanup EXIT
+
+if ! "${COMPOSE[@]}" config --quiet; then
+  "${COMPOSE[@]}" config >/dev/null
+fi
+echo "Compose config smoke passed."
+
+if [ "$CONFIG_ONLY" -eq 1 ]; then
+  exit 0
+fi
+
+if ! docker info >/dev/null 2>&1; then
+  echo "::error::Docker daemon is not reachable. Start Docker Desktop, Colima, or your Docker service, then rerun npm run smoke." >&2
+  exit 1
+fi
+
+docker build -t docker-deploy-starter:smoke .
+echo "Docker build smoke passed: docker-deploy-starter:smoke"