From 998fb4ef3cd5c47fd547e316356d7df7ca490e24 Mon Sep 17 00:00:00 2001
From: jmin <jmjeong1@strato.co.kr>
Date: Wed, 1 Jul 2026 09:36:21 +0900
Subject: [PATCH 1/2] Improve catalog deletion and Helm registration handling

---
 .../components/DeleteConfirmModal.vue         | 111 +++++++-
 .../softwareCatalog/components/uploadForm.vue | 194 +++++++++++++-
 .../softwarecatalog/CatalogRepository.java    |   2 +
 .../mcmp/softwarecatalog/CatalogService.java  |  12 +-
 .../application/dto/DeploymentParameters.java |   1 +
 .../application/dto/DeploymentRequest.java    |   1 +
 .../application/dto/DeploymentRequestDTO.java |   2 +
 .../OperationHistoryRepository.java           |   8 +
 .../repository/PackageInfoRepository.java     |   3 +
 .../repository/UnifiedLogRepository.java      |   2 +-
 .../service/impl/DockerDeploymentService.java |   2 +
 .../impl/HelmChartIntegrationServiceImpl.java | 240 +++++++++++++++++-
 .../service/DockerOperationService.java       |  41 +--
 13 files changed, 563 insertions(+), 56 deletions(-)

diff --git a/applicationFE/src/views/softwareCatalog/components/DeleteConfirmModal.vue b/applicationFE/src/views/softwareCatalog/components/DeleteConfirmModal.vue
index 25e53701..0cafc54b 100644
--- a/applicationFE/src/views/softwareCatalog/components/DeleteConfirmModal.vue
+++ b/applicationFE/src/views/softwareCatalog/components/DeleteConfirmModal.vue
@@ -9,11 +9,38 @@
         </div>
         <div class="modal-body">
           <p>Are you sure you want to delete <strong>{{ targetCatalog.name }}</strong> ({{ targetCatalog.category }}) catalog?</p>
-          <p class="text-muted">This action cannot be undone.</p>
+          <div v-if="isCheckingDeployments" class="text-muted">
+            <span class="spinner-border spinner-border-sm me-2" role="status"></span>
+            Checking deployed applications...
+          </div>
+          <div v-else-if="deploymentCheckFailed" class="alert alert-warning mb-0">
+            Unable to verify deployed applications. Try again before deleting this catalog.
+          </div>
+          <div v-else-if="hasActiveDeployments" class="alert alert-warning mb-0">
+            <div class="fw-semibold">This catalog has deployed applications.</div>
+            <div>Please delete the deployed applications first.</div>
+            <ul class="mb-0 mt-2 ps-3">
+              <li v-for="deployment in activeDeploymentPreview" :key="deployment.key">
+                {{ deployment.label }}
+              </li>
+            </ul>
+            <div v-if="remainingDeploymentCount > 0" class="mt-1">
+              and {{ remainingDeploymentCount }} more...
+            </div>
+          </div>
+          <p v-else class="text-muted">This action cannot be undone.</p>
         </div>
         <div class="modal-footer">
+          <button
+            v-if="deploymentCheckFailed"
+            type="button"
+            class="btn btn-outline-secondary"
+            :disabled="isCheckingDeployments"
+            @click="checkDeployedApplications">
+            Retry
+          </button>
           <button type="button" class="btn btn-secondary" @click="hide">Cancel</button>
-          <button type="button" class="btn btn-danger" @click="confirmDelete" :disabled="isDeleting">
+          <button type="button" class="btn btn-danger" @click="confirmDelete" :disabled="deleteDisabled">
             <span v-if="isDeleting" class="spinner-border spinner-border-sm me-2" role="status"></span>
             {{ isDeleting ? 'Deleting...' : 'Delete' }}
           </button>
@@ -24,9 +51,10 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, onBeforeUnmount } from 'vue'
+import { computed, nextTick, ref, onMounted, onBeforeUnmount } from 'vue'
 import { useToast } from 'vue-toastification'
-import { deleteSoftwareCatalog } from '../../../api/softwareCatalog'
+import { deleteSoftwareCatalog, getCatalogDeploymentStatus } from '../../../api/softwareCatalog'
+import { getApplicationStatusLabel } from '../applicationStatusDisplay'
 
 interface Props {
   targetCatalog?: any
@@ -37,10 +65,31 @@ const emit = defineEmits(['deleted', 'close'])
 
 const toast = useToast()
 const isDeleting = ref(false)
+const isCheckingDeployments = ref(false)
+const deploymentCheckFailed = ref(false)
+const activeDeployments = ref([] as any[])
 const deleteModal = ref<HTMLElement | null>(null)
+const DELETE_COMPLETED_STATUSES = new Set([
+  'UNINSTALLED',
+  'DELETED',
+  'DELETE_COMPLETED'
+])
+
+const hasActiveDeployments = computed(() => activeDeployments.value.length > 0)
+const activeDeploymentPreview = computed(() => activeDeployments.value.slice(0, 3))
+const remainingDeploymentCount = computed(() => Math.max(activeDeployments.value.length - activeDeploymentPreview.value.length, 0))
+const deleteDisabled = computed(() =>
+  isDeleting.value ||
+  isCheckingDeployments.value ||
+  deploymentCheckFailed.value ||
+  hasActiveDeployments.value
+)
 
 // 모달 열기
-const show = () => {
+const show = async () => {
+  await nextTick()
+  checkDeployedApplications()
+
   if (deleteModal.value) {
     try {
       // Bootstrap이 있는지 확인
@@ -111,8 +160,60 @@ const fallbackHide = () => {
 }
 
 // 삭제 확인
+const checkDeployedApplications = async () => {
+  activeDeployments.value = []
+  deploymentCheckFailed.value = false
+
+  if (!props.targetCatalog?.id) {
+    return
+  }
+
+  isCheckingDeployments.value = true
+
+  try {
+    const { data } = await getCatalogDeploymentStatus(props.targetCatalog.id)
+    const statuses = Array.isArray(data?.applicationStatuses) ? data.applicationStatuses : []
+    activeDeployments.value = statuses
+      .filter(isNotDeletedDeployment)
+      .map(toDeploymentBlocker)
+  } catch (error) {
+    console.log(error)
+    deploymentCheckFailed.value = true
+  } finally {
+    isCheckingDeployments.value = false
+  }
+}
+
+const isNotDeletedDeployment = (deployment: any) => {
+  const status = normalizeStatus(deployment?.status || deployment?.podStatus)
+  return !DELETE_COMPLETED_STATUSES.has(status)
+}
+
+const toDeploymentBlocker = (deployment: any, index: number) => {
+  const target = [
+    deployment?.namespace,
+    deployment?.mciId,
+    deployment?.vmId || deployment?.clusterName
+  ].filter(Boolean).join(' / ')
+  const deploymentType = deployment?.deploymentType || 'Deployment'
+  const status = getApplicationStatusLabel(deployment?.status || deployment?.podStatus)
+
+  return {
+    key: deployment?.id || `${deploymentType}-${target}-${index}`,
+    label: `${deploymentType}${target ? ` - ${target}` : ''} (${status})`
+  }
+}
+
+const normalizeStatus = (status: string | null | undefined) => String(status || '').trim().toUpperCase()
+
 const confirmDelete = async () => {
   if (!props.targetCatalog?.id) return
+  if (deleteDisabled.value) {
+    if (hasActiveDeployments.value) {
+      toast.warning('This catalog has deployed applications. Please delete them first.')
+    }
+    return
+  }
   
   isDeleting.value = true
   
diff --git a/applicationFE/src/views/softwareCatalog/components/uploadForm.vue b/applicationFE/src/views/softwareCatalog/components/uploadForm.vue
index 80807d40..01d4773d 100644
--- a/applicationFE/src/views/softwareCatalog/components/uploadForm.vue
+++ b/applicationFE/src/views/softwareCatalog/components/uploadForm.vue
@@ -52,6 +52,32 @@
                 </div>
               </div>
             </div>
+
+            <div class="row" v-if="isArtifactHub">
+              <div class="col-lg-12">
+                <div class="mb-3">
+                  <label class="form-label">Category <span class="text-red">*</span></label>
+                  <select class="form-select" v-model="formData.category">
+                    <option value="">Select Category</option>
+                    <option v-for="category in categoryList" :value="category.value" :key="category.key">{{ category.value }}</option>
+                    <option :value="CUSTOM_CATEGORY_VALUE">Custom...</option>
+                  </select>
+                </div>
+              </div>
+            </div>
+
+            <div class="row" v-if="isArtifactHub && formData.category === CUSTOM_CATEGORY_VALUE">
+              <div class="col-lg-12">
+                <div class="mb-3">
+                  <label class="form-label">Custom Category <span class="text-red">*</span></label>
+                  <input
+                    type="text"
+                    class="form-control"
+                    v-model="formData.customCategory"
+                    placeholder="Enter category">
+                </div>
+              </div>
+            </div>
           </form>
         </div>
         <div class="modal-footer">
@@ -69,10 +95,10 @@
 </template>
 
 <script setup lang="ts">
-import { ref, watch, onUnmounted } from 'vue'
+import { computed, ref, watch, onUnmounted } from 'vue'
 import { IconUpload } from '@tabler/icons-vue'
 import { useToast } from 'vue-toastification'
-import { getApplicationTagForDockerHub, getApplicationTagForArtifactHub } from '@/api/softwareCatalog'
+import { getApplicationTagForDockerHub, getApplicationTagForArtifactHub, getCategoryList } from '@/api/softwareCatalog'
 // @ts-ignore
 import _ from 'lodash';
 
@@ -93,11 +119,49 @@ const formData = ref<any>({
   path: '',
   sourceType: '',
   name: '',
-  tag: ''
+  tag: '',
+  category: '',
+  customCategory: ''
 })
 
+const CUSTOM_CATEGORY_VALUE = '__CUSTOM__'
+const DEFAULT_CATEGORY_OPTIONS = [
+  'AI_MACHINE_LEARNING',
+  'DATABASE',
+  'INTEGRATION_AND_DELIVERY',
+  'MONITORING_AND_LOGGING',
+  'NETWORKING',
+  'SECURITY',
+  'STORAGE',
+  'STREAMING_AND_MESSAGING'
+]
+
+const CATEGORY_ID_MAP: Record<string, string> = {
+  '1': 'AI_MACHINE_LEARNING',
+  '2': 'DATABASE',
+  '3': 'INTEGRATION_AND_DELIVERY',
+  '4': 'MONITORING_AND_LOGGING',
+  '5': 'NETWORKING',
+  '6': 'SECURITY',
+  '7': 'STORAGE',
+  '8': 'STREAMING_AND_MESSAGING'
+}
+
+const CATEGORY_NAME_MAP: Record<string, string> = {
+  'AI / MACHINE LEARNING': 'AI_MACHINE_LEARNING',
+  'AI MACHINE LEARNING': 'AI_MACHINE_LEARNING',
+  'DATABASE': 'DATABASE',
+  'INTEGRATION AND DELIVERY': 'INTEGRATION_AND_DELIVERY',
+  'MONITORING AND LOGGING': 'MONITORING_AND_LOGGING',
+  'MONITORING & LOGGING': 'MONITORING_AND_LOGGING',
+  'NETWORKING': 'NETWORKING',
+  'SECURITY': 'SECURITY',
+  'STORAGE': 'STORAGE',
+  'STREAMING AND MESSAGING': 'STREAMING_AND_MESSAGING'
+}
+
 // Props 변경 감지하여 폼 데이터 업데이트
-watch(() => [props.sourceData?.sourceType, props.sourceData?.name], () => {
+watch(() => [props.sourceData?.sourceType, props.sourceData?.name], async () => {
   if (props.sourceData?.sourceType) {
     formData.value.sourceType = props.sourceData?.sourceType
   }
@@ -108,11 +172,15 @@ watch(() => [props.sourceData?.sourceType, props.sourceData?.name], () => {
       _getApplicationTagForDockerHub(props.sourceData?.name)
     } else if(formData.value.sourceType.toUpperCase() == 'ARTIFACTHUB') {
       _getApplicationTagForArtifactHub(props.sourceData)
+      await _getCategoryListForArtifactHub()
+      applyRecommendedCategory(props.sourceData)
     }
   }
 }, { immediate: true })
 
 const tagList = ref([] as any)
+const categoryList = ref([] as { key: string, value: string }[])
+const isArtifactHub = computed(() => formData.value.sourceType?.toUpperCase() === 'ARTIFACTHUB')
 
 onUnmounted(() => {
   resetFormData()
@@ -124,9 +192,12 @@ const resetFormData = () => {
     path: '',
     sourceType: '',
     name: '',
-    tag: ''
+    tag: '',
+    category: '',
+    customCategory: ''
   }
   tagList.value = []
+  categoryList.value = []
 }
 
 const _getApplicationTagForDockerHub = async (sourceData: any) => {
@@ -166,16 +237,127 @@ const _getApplicationTagForArtifactHub = async (sourceData: any) => {
   }
 }
 
+const _getCategoryListForArtifactHub = async () => {
+  const categoryMap = new Map<string, { key: string, value: string }>()
+  const addCategory = (value: any) => {
+    const normalizedValue = normalizeCategoryValue(value)
+    if (!normalizedValue) return
+    categoryMap.set(normalizedValue, {
+      key: normalizedValue,
+      value: normalizedValue
+    })
+  }
+
+  DEFAULT_CATEGORY_OPTIONS.forEach(addCategory)
+
+  try {
+    const [{ data: helmCategories }, { data: dockerCategories }] = await Promise.all([
+      getCategoryList({ target: 'HELM', availableOnly: false }),
+      getCategoryList({ target: 'DOCKER', availableOnly: false })
+    ])
+
+    ;[...(helmCategories || []), ...(dockerCategories || [])].forEach((category: any) => {
+      addCategory(category?.value || category?.key || category)
+    })
+  } catch (error) {
+    console.log(error)
+  }
+
+  categoryList.value = Array.from(categoryMap.values()).sort((a, b) => a.value.localeCompare(b.value))
+}
+
+const applyRecommendedCategory = (sourceData: any) => {
+  const recommendedCategory = normalizeCategoryValue(
+    sourceData?.category ||
+    sourceData?.categories?.[0] ||
+    sourceData?.categoryName ||
+    sourceData?.category_name
+  )
+
+  if (!recommendedCategory) {
+    formData.value.category = ''
+    formData.value.customCategory = ''
+    return
+  }
+
+  const hasCategoryOption = categoryList.value.some((category) => category.value === recommendedCategory)
+  if (hasCategoryOption) {
+    formData.value.category = recommendedCategory
+    formData.value.customCategory = ''
+    return
+  }
+
+  formData.value.category = CUSTOM_CATEGORY_VALUE
+  formData.value.customCategory = recommendedCategory
+}
+
+const normalizeCategoryValue = (category: any): string => {
+  if (category === null || category === undefined) return ''
+
+  if (typeof category === 'object') {
+    return normalizeCategoryValue(
+      category.value ||
+      category.key ||
+      category.name ||
+      category.displayName ||
+      category.display_name ||
+      category.category
+    )
+  }
+
+  const rawValue = String(category).trim()
+  if (!rawValue) return ''
+
+  if (CATEGORY_ID_MAP[rawValue]) {
+    return CATEGORY_ID_MAP[rawValue]
+  }
+
+  const normalizedDisplayName = rawValue
+    .replace(/[_-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toUpperCase()
+
+  if (CATEGORY_NAME_MAP[normalizedDisplayName]) {
+    return CATEGORY_NAME_MAP[normalizedDisplayName]
+  }
+
+  return rawValue
+    .replace(/&/g, 'AND')
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_')
+    .toUpperCase()
+}
+
+const getSelectedCategory = () => {
+  if (!isArtifactHub.value) return ''
+  if (formData.value.category === CUSTOM_CATEGORY_VALUE) {
+    return normalizeCategoryValue(formData.value.customCategory)
+  }
+  return normalizeCategoryValue(formData.value.category)
+}
+
 const onSubmit = () => {
   if (!formData.value.tag.trim()) {
     toast.error('Tag is required.')
     return
   }
 
+  const selectedCategory = getSelectedCategory()
+  if (isArtifactHub.value && !selectedCategory) {
+    toast.error('Category is required.')
+    return
+  }
+
   const emitData = _.cloneDeep(props.sourceData)
   emitData.tag = formData.value.tag
   emitData.sourceType = formData.value.sourceType
   emitData.name = formData.value.name
+  if (isArtifactHub.value) {
+    emitData.version = formData.value.tag
+    emitData.category = selectedCategory
+  }
 
   // 업로드 데이터 emit
   emits('uploaded', emitData)
@@ -316,4 +498,4 @@ defineExpose({
   color: #6c757d;
   font-size: 0.875rem;
 }
-</style>
\ No newline at end of file
+</style>
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/CatalogRepository.java b/src/main/java/kr/co/mcmp/softwarecatalog/CatalogRepository.java
index 0f6e98d8..6a1d5c08 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/CatalogRepository.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/CatalogRepository.java
@@ -29,6 +29,8 @@ public interface CatalogRepository extends JpaRepository<SoftwareCatalog, Long>
     @Query("SELECT sc FROM SoftwareCatalog sc LEFT JOIN FETCH sc.catalogRefs WHERE LOWER(sc.name) LIKE LOWER(CONCAT('%', :keyword, '%'))")
     List<SoftwareCatalog> findByNameContainingIgnoreCaseWithCatalogRefs(@Param("keyword") String keyword);
 
+    List<SoftwareCatalog> findByNameIgnoreCase(String name);
+
     @Modifying
     @Query("DELETE FROM SoftwareCatalog sc WHERE sc.id = :catalogId")
     void deleteByIdBulk(@Param("catalogId") Long catalogId);
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/CatalogService.java b/src/main/java/kr/co/mcmp/softwarecatalog/CatalogService.java
index 49b2f8b4..b2c7e316 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/CatalogService.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/CatalogService.java
@@ -14,7 +14,9 @@
 import kr.co.mcmp.softwarecatalog.application.repository.DeploymentHistoryRepository;
 import kr.co.mcmp.softwarecatalog.application.repository.DeploymentLogRepository;
 import kr.co.mcmp.softwarecatalog.application.repository.HelmChartRepository;
+import kr.co.mcmp.softwarecatalog.application.repository.OperationHistoryRepository;
 import kr.co.mcmp.softwarecatalog.application.repository.PackageInfoRepository;
+import kr.co.mcmp.softwarecatalog.application.repository.UnifiedLogRepository;
 import kr.co.mcmp.softwarecatalog.rating.repository.OverallRatingRepository;
 import kr.co.mcmp.softwarecatalog.application.constants.ActionType;
 import kr.co.mcmp.softwarecatalog.application.constants.PackageType;
@@ -56,6 +58,8 @@ public class CatalogService {
     private final DeploymentHistoryRepository deploymentHistoryRepository;
     private final DeploymentLogRepository deploymentLogRepository;
     private final ApplicationStatusRepository applicationStatusRepository;
+    private final OperationHistoryRepository operationHistoryRepository;
+    private final UnifiedLogRepository unifiedLogRepository;
     private final EntityManager entityManager;
     private final SoftwareSourceService softwareSourceService;
 
@@ -339,6 +343,12 @@ public void deleteCatalog(Long catalogId) {
             }
 
             // 3. APPLICATION_STATUS 삭제 (외래키 제약조건 해결)
+            unifiedLogRepository.deleteByCatalogId(catalogId);
+            entityManager.flush();
+
+            operationHistoryRepository.deleteAllByCatalogId(catalogId);
+            entityManager.flush();
+
             applicationStatusRepository.deleteAllByCatalogId(catalogId);
             entityManager.flush();
 
@@ -649,4 +659,4 @@ private void saveIngressConfig(SoftwareCatalog catalog, String ingressUrl) {
             log.error("Failed to save ingress config", e);
         }
     }
-}
\ No newline at end of file
+}
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentParameters.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentParameters.java
index a12dc369..f7bcfd35 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentParameters.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentParameters.java
@@ -50,6 +50,7 @@ public class DeploymentParameters {
      * 추가 설정
      */
     private Map<String, Object> additionalConfig;
+    private Boolean debugKeepAlive;
     
     /**
      * 리소스 제한 정보
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequest.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequest.java
index 45da4c83..a140366f 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequest.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequest.java
@@ -67,6 +67,7 @@ public class DeploymentRequest {
      * 추가 설정 정보
      */
     private java.util.Map<String, Object> additionalConfig;
+    private Boolean debugKeepAlive;
     
     // HPA 설정
     private Boolean hpaEnabled;
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequestDTO.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequestDTO.java
index 2ce9a029..e739fa4b 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequestDTO.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/dto/DeploymentRequestDTO.java
@@ -41,6 +41,7 @@ public class DeploymentRequestDTO {
     // 자원 유형 선택값
     private String resourceType;
     private Map<String, Object> additionalConfig;
+    private Boolean debugKeepAlive;
     
     // Ingress 설정
     private Boolean ingressEnabled;
@@ -73,6 +74,7 @@ public DeploymentRequest toDeploymentRequest() {
                 .workloadRebalancingEnabled(this.workloadRebalancingEnabled)
                 .resourceType(this.resourceType)
                 .additionalConfig(this.additionalConfig)
+                .debugKeepAlive(this.debugKeepAlive)
                 .ingressEnabled(this.ingressEnabled)
                 .ingressHost(this.ingressHost)
                 .ingressPath(this.ingressPath)
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/OperationHistoryRepository.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/OperationHistoryRepository.java
index 6130c57c..dc65efe2 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/OperationHistoryRepository.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/OperationHistoryRepository.java
@@ -4,6 +4,9 @@
 import java.util.Optional;
 
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
 import kr.co.mcmp.softwarecatalog.application.model.OperationHistory;
@@ -18,4 +21,9 @@ public interface OperationHistoryRepository extends JpaRepository<OperationHisto
     List<OperationHistory> findByDeploymentHistoryIdOrderByCreatedAtAsc(Long deploymentHistoryId);
 
     Optional<OperationHistory> findTopByDeploymentHistoryIdOrderByCreatedAtDesc(Long deploymentHistoryId);
+
+    @Modifying
+    @Query("delete from OperationHistory o where o.applicationStatus.catalog.id = :catalogId " +
+            "or o.deploymentHistoryId in (select d.id from DeploymentHistory d where d.catalog.id = :catalogId)")
+    void deleteAllByCatalogId(@Param("catalogId") Long catalogId);
 }
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/PackageInfoRepository.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/PackageInfoRepository.java
index 4091ff83..116c16eb 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/PackageInfoRepository.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/PackageInfoRepository.java
@@ -46,6 +46,9 @@ public interface PackageInfoRepository extends JpaRepository<PackageInfo, Long>
      */
     List<PackageInfo> findByPackageNameAndPackageVersion(String packageName, String packageVersion);
 
+    @Query("SELECT p FROM PackageInfo p WHERE LOWER(p.packageName) = LOWER(:packageName) OR LOWER(p.packageName) LIKE LOWER(CONCAT('%/', :packageName)) ORDER BY p.id DESC")
+    List<PackageInfo> findCategoryCandidatesByPackageName(@Param("packageName") String packageName);
+
     /**
      * catalog_id를 null로 설정 (카탈로그 삭제 시 외래키 제약조건 해결)
      */
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/UnifiedLogRepository.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/UnifiedLogRepository.java
index c0070f5a..77d61afd 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/UnifiedLogRepository.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/repository/UnifiedLogRepository.java
@@ -100,7 +100,7 @@ long countByDeploymentIdAndMessageContainingBetween(
      * 카탈로그 ID로 로그 삭제
      */
     @Modifying
-    @Query("DELETE FROM UnifiedLog u WHERE u.deployment.catalog.id = :catalogId")
+    @Query("DELETE FROM UnifiedLog u WHERE u.deployment.catalog.id = :catalogId OR u.applicationStatus.catalog.id = :catalogId")
     void deleteByCatalogId(@Param("catalogId") Long catalogId);
     
     /**
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/DockerDeploymentService.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/DockerDeploymentService.java
index c209f1ba..99ec4fad 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/DockerDeploymentService.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/DockerDeploymentService.java
@@ -468,6 +468,7 @@ private DeploymentParameters createDeployParameters(DeploymentRequest request, S
                 .name(containerConfig.name)
                 .image(imageUrl)
                 .portBindings(containerConfig.portBindings)
+                .debugKeepAlive(Boolean.TRUE.equals(request.getDebugKeepAlive()))
                 .build();
     }
     
@@ -850,6 +851,7 @@ private Map<String, String> convertToMap(DeploymentParameters params) {
         map.put("name", params.getName());
         map.put("image", params.getImage());
         map.put("portBindings", params.getPortBindings());
+        map.put("debugKeepAlive", String.valueOf(Boolean.TRUE.equals(params.getDebugKeepAlive())));
         return map;
     }
 }
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/HelmChartIntegrationServiceImpl.java b/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/HelmChartIntegrationServiceImpl.java
index 85370993..8b690c8a 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/HelmChartIntegrationServiceImpl.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/application/service/impl/HelmChartIntegrationServiceImpl.java
@@ -2,15 +2,21 @@
 
 import java.util.HashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
+import java.util.Optional;
 
 import kr.co.mcmp.externalrepo.model.ArtifactHubPackage;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import kr.co.mcmp.softwarecatalog.CatalogRepository;
+import kr.co.mcmp.softwarecatalog.SoftwareCatalog;
 import kr.co.mcmp.softwarecatalog.application.dto.HelmChartRegistrationRequest;
 import kr.co.mcmp.softwarecatalog.application.model.HelmChart;
+import kr.co.mcmp.softwarecatalog.application.model.PackageInfo;
 import kr.co.mcmp.softwarecatalog.application.repository.HelmChartRepository;
+import kr.co.mcmp.softwarecatalog.application.repository.PackageInfoRepository;
 import kr.co.mcmp.softwarecatalog.application.service.ArtifactHubIntegrationService;
 import kr.co.mcmp.softwarecatalog.application.service.HelmChartIntegrationService;
 import kr.co.mcmp.softwarecatalog.application.service.NexusIntegrationService;
@@ -33,6 +39,8 @@ public class HelmChartIntegrationServiceImpl implements HelmChartIntegrationServ
     private final ArtifactHubIntegrationService artifactHubIntegrationService;
     private final NexusIntegrationService nexusIntegrationService;
     private final HelmChartRepository helmChartRepository;
+    private final PackageInfoRepository packageInfoRepository;
+    private final CatalogRepository catalogRepository;
     private final UserRepository userRepository;
     private final NexusConfig nexusConfig;
 
@@ -55,11 +63,14 @@ public Map<String, Object> registerHelmChart(HelmChartRegistrationRequest reques
                 request.getPackageId(), request.getName());
 
         Map<String, Object> result = new HashMap<>();
+        request.setVersion(firstNonBlank(request.getVersion(), request.getTag()));
 
         try {
             // 1. Helm Chart 에서 존재 여부 확인
             ArtifactHubPackage.Package detailInfo = artifactHubIntegrationService.getPackageDetailInfo("helm", request.getRepository().getName(), request.getName(), request.getTag());
             if(detailInfo != null) {
+                request.setCategory(resolveCategory(request.getCategory(), detailInfo, request.getName()));
+
                 // 2. Docker 이미지를 Nexus로 푸시 (이미지가 있는 경우)
                 String nexusImageRepository = null;
                 if (request.getImageRepository() != null && !request.getImageRepository().trim().isEmpty()) {
@@ -84,9 +95,11 @@ public Map<String, Object> registerHelmChart(HelmChartRegistrationRequest reques
                 }
                 if (request.getRepository().getUrl() == null || request.getRepository().getUrl().trim().isEmpty()) {
                     // Nexus Helm repository URL 사용
-                    String repositoryUrl = getNexusRepositoryUrl();
+                    String repositoryUrl = resolveChartRepositoryUrl(request);
                     request.getRepository().setUrl(repositoryUrl);
-                    request.getRepository().setName("nexus-helm");
+                    if (request.getRepository().getName() == null || request.getRepository().getName().trim().isEmpty()) {
+                        request.getRepository().setName("nexus-helm");
+                    }
                     request.getRepository().setOfficial(false);
                     log.info("Set Nexus repository URL: {}", repositoryUrl);
                 }
@@ -256,7 +269,25 @@ private HelmChart saveHelmChartToTable(HelmChartRegistrationRequest request, Map
             }
 
             // HelmChart 엔티티 생성
-            HelmChart helmChart = createBaseHelmChart(request, user);
+            Optional<HelmChart> existingHelmChart = findExistingHelmChart(request);
+            HelmChart helmChart = existingHelmChart.orElse(null);
+            if (helmChart == null) {
+                helmChart = createBaseHelmChart(request, user);
+            }
+            if (existingHelmChart.isPresent()) {
+                log.info("Updating existing Helm Chart: id={}, packageId={}, chartName={}, chartVersion={}",
+                        helmChart.getId(), request.getPackageId(), request.getName(), request.getVersion());
+            }
+
+            helmChart.setPackageId(request.getPackageId());
+            helmChart.setChartName(request.getName());
+            helmChart.setChartVersion(request.getVersion());
+            helmChart.setTag(request.getTag());
+            helmChart.setAppVersion(request.getAppVersion());
+            helmChart.setCategory(resolveCategory(request.getCategory(), null, request.getName()));
+            if (user != null) {
+                helmChart.setUser(user);
+            }
 
             // ArtifactHub 데이터 추출 및 설정
             extractAndSetArtifactHubData(helmChart, chartData);
@@ -264,7 +295,8 @@ private HelmChart saveHelmChartToTable(HelmChartRegistrationRequest request, Map
             // HELM_CHART 테이블에 저장
             HelmChart savedHelmChart = helmChartRepository.save(helmChart);
 
-            log.info("Helm Chart details saved to HELM_CHART table: packageId={} (helmChartId: {})",
+            log.info("Helm Chart details {} in HELM_CHART table: packageId={} (helmChartId: {})",
+                    existingHelmChart.isPresent() ? "updated" : "saved",
                     request.getPackageId(), savedHelmChart.getId());
 
             return savedHelmChart;
@@ -367,7 +399,25 @@ private HelmChart saveHelmChartToTableDirect(HelmChartRegistrationRequest reques
             }
 
             // HelmChart 엔티티 생성 (요청 데이터 직접 사용)
-            HelmChart helmChart = createBaseHelmChart(request, user);
+            Optional<HelmChart> existingHelmChart = findExistingHelmChart(request);
+            HelmChart helmChart = existingHelmChart.orElse(null);
+            if (helmChart == null) {
+                helmChart = createBaseHelmChart(request, user);
+            }
+            if (existingHelmChart.isPresent()) {
+                log.info("Updating existing Helm Chart: id={}, packageId={}, chartName={}, chartVersion={}",
+                        helmChart.getId(), request.getPackageId(), request.getName(), request.getVersion());
+            }
+
+            helmChart.setPackageId(request.getPackageId());
+            helmChart.setChartName(request.getName());
+            helmChart.setChartVersion(request.getVersion());
+            helmChart.setTag(request.getTag());
+            helmChart.setAppVersion(request.getAppVersion());
+            helmChart.setCategory(resolveCategory(request.getCategory(), null, request.getName()));
+            if (user != null) {
+                helmChart.setUser(user);
+            }
 
             // 요청 데이터에서 추가 정보 설정
             helmChart.setDescription(request.getDescription());
@@ -411,15 +461,17 @@ private HelmChart saveHelmChartToTableDirect(HelmChartRegistrationRequest reques
             }
             
             // Repository URL은 항상 Nexus URL로 설정
-            helmChart.setChartRepositoryUrl(getNexusRepositoryUrl());
-            log.info("Set Nexus repository URL: {}", getNexusRepositoryUrl());
+            String chartRepositoryUrl = resolveChartRepositoryUrl(request);
+            helmChart.setChartRepositoryUrl(chartRepositoryUrl);
+            log.info("Set Helm chart repository URL: {}", chartRepositoryUrl);
             helmChart.setValuesFile(request.getDocumentationUrl());
             // helmChart.setLicense(request.getLicense());
 
             // HELM_CHART 테이블에 저장
             HelmChart savedHelmChart = helmChartRepository.save(helmChart);
 
-            log.info("Helm Chart details saved to HELM_CHART table: packageId={} (helmChartId: {})",
+            log.info("Helm Chart details {} in HELM_CHART table: packageId={} (helmChartId: {})",
+                    existingHelmChart.isPresent() ? "updated" : "saved",
                     request.getPackageId(), savedHelmChart.getId());
 
             return savedHelmChart;
@@ -436,7 +488,7 @@ private HelmChart saveHelmChartToTableDirect(HelmChartRegistrationRequest reques
      */
     private HelmChart createBaseHelmChart(HelmChartRegistrationRequest request, User user) {
         // Repository URL 설정 - 항상 Nexus Helm Repository URL 사용
-        String repositoryUrl = getNexusRepositoryUrl();
+        String repositoryUrl = resolveChartRepositoryUrl(request);
         log.info("Using Nexus repository URL: {}", repositoryUrl);
 
         // imageRepository 설정 - 외부 경로를 내부 Nexus 경로로 변환
@@ -466,6 +518,157 @@ private HelmChart createBaseHelmChart(HelmChartRegistrationRequest request, User
     /**
      * Nexus Repository URL을 가져옵니다.
      */
+    private Optional<HelmChart> findExistingHelmChart(HelmChartRegistrationRequest request) {
+        String chartName = request.getName();
+        String chartVersion = firstNonBlank(request.getVersion(), request.getTag());
+        if (isBlank(chartName) || isBlank(chartVersion)) {
+            return Optional.empty();
+        }
+
+        List<HelmChart> candidates = helmChartRepository.findByChartNameAndChartVersion(chartName, chartVersion);
+        if (candidates == null || candidates.isEmpty()) {
+            return Optional.empty();
+        }
+
+        if (!isBlank(request.getPackageId())) {
+            Optional<HelmChart> packageMatched = candidates.stream()
+                    .filter(candidate -> request.getPackageId().equals(candidate.getPackageId()))
+                    .findFirst();
+            if (packageMatched.isPresent()) {
+                return packageMatched;
+            }
+        }
+
+        return Optional.of(candidates.get(0));
+    }
+
+    private String resolveCategory(String requestedCategory, ArtifactHubPackage.Package detailInfo, String chartName) {
+        String category = normalizeCategory(requestedCategory);
+        if (!isBlank(category)) {
+            return category;
+        }
+
+        if (detailInfo != null && detailInfo.getCategory() != null) {
+            category = normalizeCategory(detailInfo.getCategory().name());
+            if (!isBlank(category)) {
+                return category;
+            }
+        }
+
+        category = findCatalogCategoryByName(chartName);
+        if (!isBlank(category)) {
+            return category;
+        }
+
+        category = findPackageCategoryByName(chartName);
+        if (!isBlank(category)) {
+            return category;
+        }
+
+        return null;
+    }
+
+    private String findCatalogCategoryByName(String chartName) {
+        if (isBlank(chartName)) {
+            return null;
+        }
+
+        List<SoftwareCatalog> catalogs = catalogRepository.findByNameIgnoreCase(chartName);
+        if (catalogs == null) {
+            return null;
+        }
+
+        return catalogs.stream()
+                .map(SoftwareCatalog::getCategory)
+                .map(this::normalizeCategory)
+                .filter(category -> !isBlank(category))
+                .findFirst()
+                .orElse(null);
+    }
+
+    private String findPackageCategoryByName(String chartName) {
+        if (isBlank(chartName)) {
+            return null;
+        }
+
+        List<PackageInfo> packageInfos = packageInfoRepository.findCategoryCandidatesByPackageName(chartName);
+        if (packageInfos == null) {
+            return null;
+        }
+
+        return packageInfos.stream()
+                .map(PackageInfo::getCategories)
+                .map(this::firstCategory)
+                .map(this::normalizeCategory)
+                .filter(category -> !isBlank(category))
+                .findFirst()
+                .orElse(null);
+    }
+
+    private String firstCategory(String categories) {
+        if (isBlank(categories)) {
+            return null;
+        }
+        return categories.split(",")[0];
+    }
+
+    private String normalizeCategory(String category) {
+        if (isBlank(category)) {
+            return null;
+        }
+
+        String normalized = category.trim()
+                .replace("&", "AND")
+                .replaceAll("[^a-zA-Z0-9]+", "_")
+                .replaceAll("^_+|_+$", "")
+                .replaceAll("_+", "_")
+                .toUpperCase(Locale.ROOT);
+
+        if ("AI_ML".equals(normalized)) {
+            return "AI_MACHINE_LEARNING";
+        }
+        if ("MONITORING_LOGGING".equals(normalized)) {
+            return "MONITORING_AND_LOGGING";
+        }
+
+        return normalized;
+    }
+
+    private String resolveChartRepositoryUrl(HelmChartRegistrationRequest request) {
+        try {
+            String nexusRepositoryUrl = getNexusRepositoryUrl();
+            if (!isBlank(nexusRepositoryUrl)) {
+                return nexusRepositoryUrl;
+            }
+        } catch (Exception e) {
+            log.warn("Nexus Helm repository is not available. Falling back to requested repository URL: {}", e.getMessage());
+        }
+
+        if (request.getRepository() != null && !isBlank(request.getRepository().getUrl())) {
+            return request.getRepository().getUrl();
+        }
+
+        return "";
+    }
+
+    private String firstNonBlank(String... values) {
+        if (values == null) {
+            return null;
+        }
+
+        for (String value : values) {
+            if (!isBlank(value)) {
+                return value;
+            }
+        }
+
+        return null;
+    }
+
+    private boolean isBlank(String value) {
+        return value == null || value.trim().isEmpty();
+    }
+
     private String getNexusRepositoryUrl() {
         try {
             OssDto nexusInfo = nexusIntegrationService.getNexusInfoFromDB();
@@ -528,7 +731,13 @@ private void extractAndSetArtifactHubData(HelmChart helmChart, Map<String, Objec
         setStringValue(helmChart::setChartName, chartData.get("name"));
         setStringValue(helmChart::setChartVersion, chartData.get("version"));
         setStringValue(helmChart::setPackageId, chartData.get("package_id"));
-        setStringValue(helmChart::setCategory, chartData.get("category"));
+        String resolvedCategory = resolveCategory(
+                chartData.get("category") != null ? chartData.get("category").toString() : helmChart.getCategory(),
+                null,
+                helmChart.getChartName());
+        if (!isBlank(resolvedCategory)) {
+            helmChart.setCategory(resolvedCategory);
+        }
         setStringValue(helmChart::setImageRepository, chartData.get("image_repository"));
         setStringValue(helmChart::setDescription, chartData.get("description"));
         setStringValue(helmChart::setNormalizedName, chartData.get("normalized_name"));
@@ -540,11 +749,18 @@ private void extractAndSetArtifactHubData(HelmChart helmChart, Map<String, Objec
         Map<String, Object> repository = (Map<String, Object>) chartData.get("repository");
         if (repository != null) {
             // Repository URL은 항상 Nexus URL로 설정
-            helmChart.setChartRepositoryUrl(getNexusRepositoryUrl());
+            try {
+                String nexusRepositoryUrl = getNexusRepositoryUrl();
+                if (!isBlank(nexusRepositoryUrl)) {
+                    helmChart.setChartRepositoryUrl(nexusRepositoryUrl);
+                    log.info("Set Nexus repository URL: {}", nexusRepositoryUrl);
+                }
+            } catch (Exception e) {
+                log.warn("Nexus Helm repository is not available. Keeping current repository URL: {}", e.getMessage());
+            }
             setStringValue(helmChart::setRepositoryName, repository.get("name"));
             setStringValue(helmChart::setRepositoryDisplayName, repository.get("display_name"));
             helmChart.setRepositoryOfficial(false); // Nexus는 공식 저장소가 아님
-            log.info("Set Nexus repository URL: {}", getNexusRepositoryUrl());
         }
 
         // 불린 값 설정
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerOperationService.java b/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerOperationService.java
index 5a2fb2ff..99c52e01 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerOperationService.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerOperationService.java
@@ -82,7 +82,7 @@ public ContainerDeployResult runDockerContainer(String host, Map<String, String>
             HostConfig hostConfig = HostConfig.newHostConfig().withPortBindings(portBindings);
 
             // 이미지 타입에 따른 적절한 명령어 설정
-            String[] cmd = getCommandForImage(imageName);
+            String[] cmd = getCommandForDebugKeepAlive(isDebugKeepAliveEnabled(deployParams));
             
             // 노출할 포트들 추출
             ExposedPort[] exposedPorts = portBindings.getBindings().keySet().toArray(new ExposedPort[0]);
@@ -250,39 +250,18 @@ private boolean waitForContainerToStart(DockerClient dockerClient, String contai
     }
     
     /**
-     * 이미지 타입에 따른 적절한 명령어를 반환합니다.
+     * 디버그 keep-alive 모드일 때만 Docker CMD를 override합니다.
      */
-    private String[] getCommandForImage(String imageName) {
-        String lowerImageName = imageName.toLowerCase();
-        
-        if (lowerImageName.contains("elasticsearch")) {
-            // Elasticsearch는 기본 명령어 사용 (환경변수는 컨테이너 생성시 설정)
-            return null; // 기본 명령어 사용
-        } else if (lowerImageName.contains("redis")) {
-            // Redis 클러스터링 명령어 설정
-            return new String[]{"redis-server", "--cluster-enabled", "yes", "--cluster-config-file", "nodes.conf", "--cluster-node-timeout", "5000", "--appendonly", "yes", "--bind", "0.0.0.0", "--port", "6379"};
-        } else if (lowerImageName.contains("mariadb") || lowerImageName.contains("mysql")) {
-            // MariaDB/MySQL은 기본 명령어 사용
-            return null;
-        } else if (lowerImageName.contains("ruby")) {
-            // Ruby 컨테이너는 대화형 모드로 실행
-            return new String[]{"ruby", "-e", "loop { sleep 1 }"};
-        } else if (lowerImageName.contains("python")) {
-            // Python 컨테이너는 대화형 모드로 실행
-            return new String[]{"python", "-c", "import time; [time.sleep(1) for _ in iter(int, 1)]"};
-        } else if (lowerImageName.contains("node")) {
-            // Node.js 컨테이너는 대화형 모드로 실행
-            return new String[]{"node", "-e", "setInterval(() => {}, 1000)"};
-        } else if (lowerImageName.contains("nginx")) {
-            // Nginx는 기본 명령어 사용
-            return new String[]{"nginx", "-g", "daemon off;"};
-        } else if (lowerImageName.contains("apache")) {
-            // Apache는 기본 명령어 사용
-            return new String[]{"httpd", "-D", "FOREGROUND"};
-        } else {
-            // 기본적으로 컨테이너가 계속 실행되도록 함
+    private boolean isDebugKeepAliveEnabled(Map<String, String> deployParams) {
+        return deployParams != null && Boolean.parseBoolean(deployParams.getOrDefault("debugKeepAlive", "false"));
+    }
+
+    private String[] getCommandForDebugKeepAlive(boolean debugKeepAlive) {
+        if (debugKeepAlive) {
             return new String[]{"tail", "-f", "/dev/null"};
         }
+
+        return null;
     }
     
     /**

From edf98c685a2027093f19516be94c33902e84b0b3 Mon Sep 17 00:00:00 2001
From: jmin <jmjeong1@strato.co.kr>
Date: Tue, 7 Jul 2026 13:38:12 +0900
Subject: [PATCH 2/2] Validate Docker remote API setup state

---
 doc/AM_VM_Docker_Remote_API_fix_20260707.html | 442 ++++++++++++++++++
 doc/AM_VM_Docker_Remote_API_fix_20260707.md   | 203 ++++++++
 .../docker/service/DockerSetupService.java    |  89 +++-
 .../service/DockerSetupServiceTest.java       | 119 +++++
 4 files changed, 839 insertions(+), 14 deletions(-)
 create mode 100644 doc/AM_VM_Docker_Remote_API_fix_20260707.html
 create mode 100644 doc/AM_VM_Docker_Remote_API_fix_20260707.md
 create mode 100644 src/test/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupServiceTest.java

diff --git a/doc/AM_VM_Docker_Remote_API_fix_20260707.html b/doc/AM_VM_Docker_Remote_API_fix_20260707.html
new file mode 100644
index 00000000..8355f6ef
--- /dev/null
+++ b/doc/AM_VM_Docker_Remote_API_fix_20260707.html
@@ -0,0 +1,442 @@
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>AM VM Docker Remote API 설정 검증 수정 요약</title>
+  <style>
+    :root {
+      --bg: #f6f8fb;
+      --panel: #ffffff;
+      --ink: #172033;
+      --muted: #5f6c80;
+      --line: #d9e0ea;
+      --blue: #2563eb;
+      --green: #15803d;
+      --red: #b42318;
+      --amber: #b45309;
+      --code: #101828;
+      --code-bg: #eef2f7;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--ink);
+      font-family: "Segoe UI", "Apple SD Gothic Neo", "Malgun Gothic", Arial, sans-serif;
+      line-height: 1.6;
+    }
+
+    main {
+      max-width: 1180px;
+      margin: 0 auto;
+      padding: 36px 24px 56px;
+    }
+
+    header {
+      margin-bottom: 22px;
+    }
+
+    h1 {
+      margin: 0 0 8px;
+      font-size: 30px;
+      line-height: 1.25;
+      letter-spacing: 0;
+    }
+
+    h2 {
+      margin: 34px 0 14px;
+      font-size: 22px;
+      letter-spacing: 0;
+    }
+
+    h3 {
+      margin: 0 0 8px;
+      font-size: 16px;
+      letter-spacing: 0;
+    }
+
+    p {
+      margin: 0 0 12px;
+    }
+
+    .meta {
+      color: var(--muted);
+      font-size: 14px;
+    }
+
+    .summary {
+      display: grid;
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+      gap: 14px;
+      margin: 24px 0;
+    }
+
+    .box {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 16px;
+      box-shadow: 0 1px 2px rgba(16, 24, 40, 0.04);
+    }
+
+    .box strong {
+      display: block;
+      margin-bottom: 6px;
+      font-size: 14px;
+      color: var(--muted);
+    }
+
+    .box .big {
+      font-size: 20px;
+      font-weight: 700;
+      line-height: 1.35;
+    }
+
+    .ok {
+      color: var(--green);
+      font-weight: 700;
+    }
+
+    .warn {
+      color: var(--amber);
+      font-weight: 700;
+    }
+
+    .fail {
+      color: var(--red);
+      font-weight: 700;
+    }
+
+    .blue {
+      color: var(--blue);
+      font-weight: 700;
+    }
+
+    .flow {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 16px;
+      align-items: stretch;
+    }
+
+    .step {
+      display: flex;
+      gap: 12px;
+      padding: 12px 0;
+      border-bottom: 1px solid var(--line);
+    }
+
+    .step:last-child {
+      border-bottom: 0;
+    }
+
+    .num {
+      flex: 0 0 auto;
+      width: 28px;
+      height: 28px;
+      border-radius: 50%;
+      display: grid;
+      place-items: center;
+      background: #e8eefc;
+      color: var(--blue);
+      font-weight: 700;
+      font-size: 13px;
+    }
+
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      overflow: hidden;
+      box-shadow: 0 1px 2px rgba(16, 24, 40, 0.04);
+    }
+
+    th,
+    td {
+      padding: 12px 14px;
+      border-bottom: 1px solid var(--line);
+      text-align: left;
+      vertical-align: top;
+    }
+
+    th {
+      background: #eef3fb;
+      color: #2b3548;
+      font-size: 14px;
+    }
+
+    tr:last-child td {
+      border-bottom: 0;
+    }
+
+    code {
+      padding: 2px 6px;
+      border-radius: 5px;
+      background: var(--code-bg);
+      color: var(--code);
+      font-family: Consolas, "Courier New", monospace;
+      font-size: 0.92em;
+    }
+
+    .chips {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+      margin-top: 10px;
+    }
+
+    .chip {
+      border: 1px solid var(--line);
+      background: #f9fbff;
+      border-radius: 999px;
+      padding: 5px 10px;
+      font-size: 13px;
+      color: #344054;
+    }
+
+    .checklist {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 14px;
+    }
+
+    ul {
+      margin: 8px 0 0 20px;
+      padding: 0;
+    }
+
+    li {
+      margin: 5px 0;
+    }
+
+    footer {
+      margin-top: 34px;
+      color: var(--muted);
+      font-size: 13px;
+    }
+
+    @media (max-width: 860px) {
+      main {
+        padding: 24px 14px 44px;
+      }
+
+      .summary,
+      .flow,
+      .checklist {
+        grid-template-columns: 1fr;
+      }
+
+      h1 {
+        font-size: 24px;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>AM VM Docker Remote API 설정 검증 수정 요약</h1>
+      <div class="meta">작성일: 2026-07-07 · 대상: <code>DockerSetupService</code> · 다음 릴리즈 배포 후 Azure VM 검증 필요</div>
+    </header>
+
+    <section class="summary" aria-label="핵심 요약">
+      <div class="box">
+        <strong>문제의 본질</strong>
+        <div class="big">Remote API 설정 실패를 기존 <code>dockerd</code> 상태로 성공 오판 가능</div>
+      </div>
+      <div class="box">
+        <strong>수정 방향</strong>
+        <div class="big">Docker 설치 여부와 Remote API 설정 여부를 분리</div>
+      </div>
+      <div class="box">
+        <strong>지원 범위</strong>
+        <div class="big">systemd <code>docker.service</code> 기반 Docker만 자동 설정</div>
+      </div>
+    </section>
+
+    <h2>한 줄 결론</h2>
+    <div class="box">
+      <p><span class="blue">Docker가 이미 있으면 재설치하지 않고</span>, Remote API만 systemd 방식으로 설정한다. 이때 <code>docker.service</code>가 없거나 <code>systemctl restart docker</code>가 실패하면 성공으로 넘기지 않고 실패 처리한다.</p>
+    </div>
+
+    <h2>배포 경로</h2>
+    <section class="flow">
+      <div class="box">
+        <h3>준비 단계</h3>
+        <div class="step">
+          <div class="num">1</div>
+          <div>AM이 Tumblebug <code>cmd/infra</code> API로 VM 명령 실행</div>
+        </div>
+        <div class="step">
+          <div class="num">2</div>
+          <div>VM에서 <code>docker --version</code>과 <code>dockerd -H tcp://0.0.0.0:2375</code> 확인</div>
+        </div>
+        <div class="step">
+          <div class="num">3</div>
+          <div>Remote API가 없으면 systemd <code>docker.service</code> 방식으로 설정 시도</div>
+        </div>
+      </div>
+
+      <div class="box">
+        <h3>실제 컨테이너 배포 단계</h3>
+        <div class="step">
+          <div class="num">1</div>
+          <div>AM이 VM Public IP 조회</div>
+        </div>
+        <div class="step">
+          <div class="num">2</div>
+          <div>Docker client가 <code>tcp://{VM_PUBLIC_IP}:2375</code>로 접속</div>
+        </div>
+        <div class="step">
+          <div class="num">3</div>
+          <div>Docker Remote API로 이미지 pull, 컨테이너 생성, 컨테이너 시작 수행</div>
+        </div>
+      </div>
+    </section>
+
+    <h2>상태별 처리 결과</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>VM 상태</th>
+          <th>AM 동작</th>
+          <th>판정</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Docker 없음</td>
+          <td><code>get-docker.sh</code> 설치 후 systemd 기반 Remote API 설정</td>
+          <td><span class="ok">기존 설치 흐름 유지</span></td>
+        </tr>
+        <tr>
+          <td>Docker 있음 + Remote API 있음</td>
+          <td>설치, 설정, restart 없이 skip</td>
+          <td><span class="ok">배포 가능 상태로 인정</span></td>
+        </tr>
+        <tr>
+          <td>Docker 있음 + Remote API 없음</td>
+          <td>Docker 재설치 없이 Remote API 설정만 시도</td>
+          <td><span class="ok">이번 수정의 핵심 분기</span></td>
+        </tr>
+        <tr>
+          <td>Remote API 설정 중 <code>docker.service</code> 없음</td>
+          <td><code>override.conf</code> 작성 전에 실패 처리</td>
+          <td><span class="fail">지원 불가 VM 상태</span></td>
+        </tr>
+        <tr>
+          <td><code>systemctl restart docker</code> 실패</td>
+          <td>최종 <code>dockerd</code> 검증으로 넘어가지 않고 실패 처리</td>
+          <td><span class="fail">설정 적용 실패</span></td>
+        </tr>
+      </tbody>
+    </table>
+
+    <h2>코드 변경 포인트</h2>
+    <section class="checklist">
+      <div class="box">
+        <h3>1. 설치 여부와 Remote API 여부 분리</h3>
+        <p><code>Docker version</code>과 <code>Remote API enabled</code>를 별도 boolean으로 판단한다.</p>
+        <div class="chips">
+          <span class="chip">dockerInstalled</span>
+          <span class="chip">remoteApiEnabled</span>
+        </div>
+      </div>
+      <div class="box">
+        <h3>2. 기존 Docker 재설치 방지</h3>
+        <p>Docker가 이미 있으면 <code>installDocker()</code>를 다시 호출하지 않고 <code>configureInstalledDockerOnVM()</code>으로 이동한다.</p>
+      </div>
+      <div class="box">
+        <h3>3. systemd 지원 범위 명확화</h3>
+        <p>Remote API 설정 전 <code>systemctl cat docker.service</code>로 systemd 관리 대상인지 확인한다.</p>
+      </div>
+      <div class="box">
+        <h3>4. 실패 마커 검사</h3>
+        <p>override 작성, daemon reload, Docker restart 결과를 마커로 검사해 실패를 숨기지 않는다.</p>
+      </div>
+    </section>
+
+    <h2>성공/실패 마커</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>단계</th>
+          <th>성공 마커</th>
+          <th>실패 마커</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>systemd docker.service 확인</td>
+          <td><code>DOCKER_SERVICE_FOUND</code></td>
+          <td><code>DOCKER_SERVICE_NOT_FOUND</code></td>
+        </tr>
+        <tr>
+          <td>Remote API override 작성</td>
+          <td><code>DOCKER_REMOTE_CONFIGURED</code></td>
+          <td><code>DOCKER_REMOTE_CONFIG_FAILED</code></td>
+        </tr>
+        <tr>
+          <td>Docker restart</td>
+          <td><code>DOCKER_RESTARTED</code></td>
+          <td><code>DOCKER_RESTART_FAILED</code></td>
+        </tr>
+      </tbody>
+    </table>
+
+    <h2>릴리즈 후 테스트 체크리스트</h2>
+    <section class="checklist">
+      <div class="box">
+        <h3>정상 Azure VM 신규 배포</h3>
+        <ul>
+          <li>VM spec: <code>Standard_D2als_v6</code></li>
+          <li>테스트 앱: nginx 등 단순 컨테이너</li>
+          <li>로그: <code>DOCKER_SERVICE_FOUND</code>, <code>DOCKER_REMOTE_CONFIGURED</code>, <code>DOCKER_RESTARTED</code></li>
+          <li>결과: AM 배포 상태 SUCCESS 또는 Running 계열</li>
+        </ul>
+      </div>
+      <div class="box">
+        <h3>이미 Remote API가 켜진 VM</h3>
+        <ul>
+          <li>초기 체크에 <code>Docker version</code>과 <code>Remote API enabled</code> 포함</li>
+          <li>설치/restart 없이 skip</li>
+          <li>기존 배포 성공 동작 유지</li>
+        </ul>
+      </div>
+      <div class="box">
+        <h3>docker.service 없는 VM</h3>
+        <ul>
+          <li><code>Docker systemd service is not available</code> 메시지 확인</li>
+          <li><code>override.conf</code> 작성 단계로 진행하지 않음</li>
+          <li>성공으로 오판하지 않음</li>
+        </ul>
+      </div>
+      <div class="box">
+        <h3>restart 실패 VM</h3>
+        <ul>
+          <li><code>Failed to restart Docker service after remote API configuration</code> 메시지 확인</li>
+          <li>기존 <code>dockerd</code> 상태만 보고 성공 처리하지 않음</li>
+          <li>실패 원인을 AM 로그에서 식별 가능</li>
+        </ul>
+      </div>
+    </section>
+
+    <h2>주의 사항</h2>
+    <div class="box">
+      <p><span class="warn">Docker Remote API 2375는 TLS 없는 평문 API</span>다. 운영 환경에서는 AM 서버에서만 접근 가능하도록 CSP 보안그룹 또는 방화벽으로 제한해야 한다.</p>
+      <p>이번 수정은 <code>docker.service</code>가 없는 모든 Docker 실행 방식을 지원하는 변경이 아니다. AM이 지원하는 systemd Docker 전제를 명확히 하고, 그 전제 밖이면 성공으로 오판하지 않도록 하는 변경이다.</p>
+    </div>
+
+    <footer>
+      관련 소스: <code>DockerSetupService.java</code>, <code>DockerSetupServiceTest.java</code>
+    </footer>
+  </main>
+</body>
+</html>
diff --git a/doc/AM_VM_Docker_Remote_API_fix_20260707.md b/doc/AM_VM_Docker_Remote_API_fix_20260707.md
new file mode 100644
index 00000000..dae48510
--- /dev/null
+++ b/doc/AM_VM_Docker_Remote_API_fix_20260707.md
@@ -0,0 +1,203 @@
+# AM VM Docker Remote API 설정 검증 수정 내역
+
+작성일: 2026-07-07
+
+## 배경
+
+AM의 VM 애플리케이션 배포는 두 단계로 나뉜다.
+
+- Docker 준비 단계: AM -> Tumblebug `cmd/infra` -> VM 명령 실행
+- 컨테이너 배포 단계: AM -> VM Docker Remote API `tcp://{VM_PUBLIC_IP}:2375`
+
+따라서 VM 배포가 가능하려면 VM에 Docker runtime이 있고, AM 서버가 접근 가능한 Docker Remote API가 열려 있어야 한다.
+
+이번 이슈는 Azure VM에서 `dockerd -H tcp://0.0.0.0:2375` 프로세스는 떠 있지만 `docker.service` systemd 유닛이 없는 상태에서 발견되었다. 이 상태에서는 당장 Docker Remote API가 동작할 수는 있지만, AM이 작성하는 systemd override 설정은 `systemctl restart docker`가 성공해야 실제 `dockerd`에 반영된다.
+
+## 기존 문제
+
+대상 파일:
+
+- `src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupService.java`
+
+기존 구현은 다음 문제가 있었다.
+
+- Docker runtime이 이미 설치되어 있어도 Remote API만 꺼져 있으면 Docker 설치 경로를 다시 탈 수 있었다.
+- `configureDockerForRemoteAccess()`가 `/etc/systemd/system/docker.service.d/override.conf`를 작성하지만, `docker.service` 유닛 존재 여부를 확인하지 않았다.
+- `restartDocker()`가 `sudo systemctl restart docker` 실행 결과를 로그만 남기고 실패로 처리하지 않았다.
+- `verifyDockerConfiguration()`은 현재 떠 있는 `dockerd` 프로세스에 `-H tcp://0.0.0.0:2375` 옵션이 있는지만 확인했다.
+- 따라서 과거에 수동으로 띄워진 `dockerd`가 Remote API를 이미 열고 있으면, 방금 작성한 systemd override가 적용되지 않았는데도 성공처럼 보일 수 있었다.
+
+## 수정 내용
+
+### 0. Docker 설치 여부와 Remote API 설정 여부 분리
+
+초기 체크 결과를 다음 두 조건으로 분리한다.
+
+- Docker runtime 설치 여부: `Docker version`
+- Docker Remote API 활성화 여부: `Remote API enabled`
+
+Docker runtime은 이미 있는데 Remote API만 꺼져 있으면 `get-docker.sh` 설치 경로를 다시 타지 않는다. 이 경우 AM이 지원하는 systemd `docker.service` 기반 Remote API 설정만 시도한다.
+
+### 1. systemd docker.service 확인 추가
+
+Remote API 설정을 systemd override 방식으로 적용하기 전에 다음 명령으로 `docker.service` 유닛 존재 여부를 확인한다.
+
+```bash
+systemctl cat docker.service
+```
+
+성공 마커:
+
+```text
+DOCKER_SERVICE_FOUND
+```
+
+실패 마커:
+
+```text
+DOCKER_SERVICE_NOT_FOUND
+```
+
+`docker.service`가 없으면 AM이 systemd override를 적용할 수 없는 VM 상태로 보고 배포 준비를 실패 처리한다.
+
+### 2. Remote API override 작성 실패 감지
+
+`override.conf` 작성과 `systemctl daemon-reload`를 하나의 명령 그룹으로 실행하고, 성공/실패 마커를 검사한다.
+
+성공 마커:
+
+```text
+DOCKER_REMOTE_CONFIGURED
+```
+
+실패 마커:
+
+```text
+DOCKER_REMOTE_CONFIG_FAILED
+```
+
+### 3. Docker restart 실패 감지
+
+`sudo systemctl restart docker` 결과를 마커로 검사한다.
+
+성공 마커:
+
+```text
+DOCKER_RESTARTED
+```
+
+실패 마커:
+
+```text
+DOCKER_RESTART_FAILED
+```
+
+restart가 실패하면 이후 `verifyDockerConfiguration()`으로 넘어가지 않고 실패 처리한다.
+
+## 유지되는 동작
+
+초기 체크에서 이미 아래 두 조건이 모두 만족되면 기존처럼 설치/설정/restart를 수행하지 않는다.
+
+- `docker --version` 확인 가능
+- 현재 `dockerd` 프로세스에 `-H tcp://0.0.0.0:2375` 옵션 존재
+
+즉 이미 AM 배포 가능 상태인 VM을 불필요하게 재설정하지 않는다.
+
+Docker runtime이 없으면 기존처럼 Docker 설치 후 systemd 기반 Remote API 설정을 시도한다.
+
+Docker runtime은 있지만 Remote API가 없으면 Docker 재설치 없이 systemd 기반 Remote API 설정만 시도한다.
+
+## 영향 범위
+
+직접 영향:
+
+- VM 타입 애플리케이션 배포 전 Docker runtime 준비 단계
+- `DockerDeploymentService` -> `DockerSetupService.checkAndInstallDocker()`
+
+직접 영향 없음:
+
+- Kubernetes Helm 배포
+- Ingress NGINX 설치 경로
+- `KubernetesDeployService` -> `HelmChartService.ensureIngressController()`
+
+단, 화면에서는 `PREPARING_RUNTIME`, `PREPARING_METRICS_SERVER`, `PREPARING_INGRESS_NGINX`가 모두 `Initializing` 계열로 보일 수 있으므로 로그와 배포 타입을 같이 확인해야 한다.
+
+## 추가된 단위 테스트
+
+추가 파일:
+
+- `src/test/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupServiceTest.java`
+
+검증 항목:
+
+- Docker Remote API가 이미 켜져 있으면 설정/restart 경로를 타지 않는다.
+- Docker runtime이 이미 있고 Remote API만 꺼져 있으면 Docker 재설치 없이 systemd 설정 경로를 탄다.
+- 설정 경로에서 `docker.service`가 없으면 `override.conf` 작성 전에 실패한다.
+- 설정 경로에서 `systemctl restart docker`가 실패하면 최종 Remote API 검증으로 넘어가지 않는다.
+
+## 다음 릴리즈 배포 후 테스트 필요 항목
+
+새 AM 버전 배포 후 개발 서버 또는 검증 서버에서 아래 항목을 확인한다.
+
+### 1. 정상 Azure VM 신규 배포
+
+대상 예시:
+
+- CSP: Azure
+- VM spec: `Standard_D2als_v6`
+- 배포 타입: VM Docker 애플리케이션
+- 테스트 애플리케이션: nginx 등 단순 컨테이너
+
+기대 결과:
+
+- AM 배포 상태가 `SUCCESS` 또는 Running 계열로 전환된다.
+- AM 로그에 다음 마커가 순서대로 나타난다.
+  - `DOCKER_SERVICE_FOUND`
+  - `DOCKER_REMOTE_CONFIGURED`
+  - `DOCKER_RESTARTED`
+  - `Docker configuration verified successfully`
+- VM에서 `systemctl cat docker.service`가 성공한다.
+- VM에서 `ps aux | grep dockerd` 결과에 `-H tcp://0.0.0.0:2375`가 포함된다.
+
+### 2. 이미 Docker Remote API가 켜진 VM
+
+기대 결과:
+
+- 초기 Docker 체크 결과가 `Docker version`과 `Remote API enabled`를 포함하면 AM은 설치/설정/restart를 수행하지 않는다.
+- 로그에 `Docker is already installed and configured for remote access`가 남는다.
+- 기존 배포 성공 동작은 유지된다.
+
+### 3. docker.service가 없는 비정상 VM
+
+재현 가능한 테스트 VM이 있을 때만 수행한다.
+
+기대 결과:
+
+- AM이 성공으로 오판하지 않고 실패 처리한다.
+- 실패 메시지에 `Docker systemd service is not available`가 포함된다.
+- `override.conf` 작성 및 `systemctl restart docker` 단계로 진행하지 않는다.
+
+### 4. restart 실패 VM
+
+재현 가능한 테스트 VM이 있을 때만 수행한다.
+
+기대 결과:
+
+- `systemctl restart docker` 실패 시 AM이 실패 처리한다.
+- 실패 메시지에 `Failed to restart Docker service after remote API configuration`가 포함된다.
+- 과거에 떠 있던 `dockerd -H tcp://0.0.0.0:2375`만 보고 성공 처리하지 않는다.
+
+### 5. 보안그룹 확인
+
+Docker Remote API `2375`는 TLS 없는 평문 API이므로 운영 환경에서는 AM 서버에서만 접근 가능하도록 CSP 방화벽/보안그룹을 제한해야 한다.
+
+## 판정 기준
+
+이번 수정은 Docker runtime 자동 설치 범위를 넓히는 변경이 아니다.
+
+판정 기준은 다음과 같다.
+
+- AM이 관리 가능한 systemd Docker 상태이면 Remote API 설정을 적용하고 restart 성공까지 확인한다.
+- AM이 관리할 수 없는 Docker 상태이면 성공처럼 통과하지 않고 명확히 실패시킨다.
+- 이미 Docker Remote API가 정상인 VM은 기존처럼 재설정하지 않는다.
+- Docker runtime이 이미 있는 VM은 Remote API 설정만 보정하며 Docker를 다시 설치하지 않는다.
diff --git a/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupService.java b/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupService.java
index d7784805..68b06069 100644
--- a/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupService.java
+++ b/src/main/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupService.java
@@ -22,12 +22,18 @@ public void checkAndInstallDocker(String namespace, String mciId, String vmId) t
             String result = cbtumblebugRestApi.executeMciCommand(namespace, mciId, checkDockerCommand, null, vmId);
             log.info("Docker check result: '{}'", result);
             
+            boolean dockerInstalled = result != null && result.contains("Docker version");
+            boolean remoteApiEnabled = result != null && result.contains("Remote API enabled");
+
             if (result == null || result.trim().isEmpty()) {
                 log.warn("Docker check command returned empty result. Assuming Docker needs to be installed...");
                 installAndConfigureDockerOnVM(namespace, mciId, vmId);
-            } else if (!result.contains("Docker version") || !result.contains("Remote API enabled")) {
+            } else if (!dockerInstalled) {
                 log.warn("Docker is not installed or remote API is not enabled. Installing/configuring Docker...");
                 installAndConfigureDockerOnVM(namespace, mciId, vmId);
+            } else if (!remoteApiEnabled) {
+                log.warn("Docker is installed but remote API is not enabled. Configuring Docker remote access...");
+                configureInstalledDockerOnVM(namespace, mciId, vmId);
             } else {
                 log.info("Docker is already installed and configured for remote access on VM: {}", vmId);
             }
@@ -44,12 +50,7 @@ private void installAndConfigureDockerOnVM(String namespace, String mciId, Strin
             if (hasSudoAccess(namespace, mciId, vmId)) {
                 log.info("Sudo access available, proceeding with full installation");
                 installDocker(namespace, mciId, vmId);
-                configureDockerForRemoteAccess(namespace, mciId, vmId);
-                setDockerPermissions(namespace, mciId, vmId);
-                enableBridgeNfCallIptables(namespace, mciId, vmId);
-                configureVmMaxMapCount(namespace, mciId, vmId);
-                configureSSHForDockerAccess(namespace, mciId, vmId);
-                restartDocker(namespace, mciId, vmId);
+                configureDockerWithSystemd(namespace, mciId, vmId);
             } else {
                 log.warn("Sudo access not available (Azure VM), trying limited installation");
                 installDockerLimited(namespace, mciId, vmId);
@@ -60,6 +61,33 @@ private void installAndConfigureDockerOnVM(String namespace, String mciId, Strin
             throw new ApplicationException("Failed to install or configure Docker: " + e.getMessage());
         }
     }
+
+    private void configureInstalledDockerOnVM(String namespace, String mciId, String vmId) throws ApplicationException {
+        log.info("Starting Docker remote API configuration for namespace: {}, mciId: {}, vmId: {}", namespace, mciId, vmId);
+        try {
+            if (hasSudoAccess(namespace, mciId, vmId)) {
+                log.info("Sudo access available, configuring installed Docker through systemd");
+                configureDockerWithSystemd(namespace, mciId, vmId);
+            } else {
+                log.warn("Sudo access not available (Azure VM), trying limited Docker remote API configuration");
+                installDockerLimited(namespace, mciId, vmId);
+            }
+            verifyDockerConfiguration(namespace, mciId, vmId);
+        } catch (Exception e) {
+            log.error("Error configuring Docker remote access", e);
+            throw new ApplicationException("Failed to configure Docker remote access: " + e.getMessage());
+        }
+    }
+
+    private void configureDockerWithSystemd(String namespace, String mciId, String vmId) throws Exception {
+        ensureDockerSystemdServiceAvailable(namespace, mciId, vmId);
+        configureDockerForRemoteAccess(namespace, mciId, vmId);
+        setDockerPermissions(namespace, mciId, vmId);
+        enableBridgeNfCallIptables(namespace, mciId, vmId);
+        configureVmMaxMapCount(namespace, mciId, vmId);
+        configureSSHForDockerAccess(namespace, mciId, vmId);
+        restartDocker(namespace, mciId, vmId);
+    }
     
     /**
      * sudo 권한이 있는지 확인합니다.
@@ -138,16 +166,34 @@ private void installDocker(String namespace, String mciId, String vmId) throws E
         log.info("Docker installation result: {}", result);
     }
 
+    private void ensureDockerSystemdServiceAvailable(String namespace, String mciId, String vmId) throws Exception {
+        String serviceCheckCommand =
+            "(systemctl cat docker.service >/dev/null 2>&1) && echo 'DOCKER_SERVICE_FOUND' || echo 'DOCKER_SERVICE_NOT_FOUND'";
+
+        String result = cbtumblebugRestApi.executeMciCommand(namespace, mciId, serviceCheckCommand, null, vmId);
+        log.info("Docker systemd service check result: {}", result);
+
+        requireCommandSuccess(
+            result,
+            "DOCKER_SERVICE_FOUND",
+            "DOCKER_SERVICE_NOT_FOUND",
+            "Docker systemd service is not available. Docker remote API configuration requires docker.service");
+    }
+
     private void configureDockerForRemoteAccess(String namespace, String mciId, String vmId) throws Exception {
         String configureDockerCommand = 
-            "sudo mkdir -p /etc/systemd/system/docker.service.d && " +
-            "echo '[Service]' | sudo tee /etc/systemd/system/docker.service.d/override.conf && " +
-            "echo 'ExecStart=' | sudo tee -a /etc/systemd/system/docker.service.d/override.conf && " +
-            "echo 'ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock' | sudo tee -a /etc/systemd/system/docker.service.d/override.conf && " +
-            "sudo systemctl daemon-reload";
+            "(sudo mkdir -p /etc/systemd/system/docker.service.d && " +
+            "printf '%s\\n' '[Service]' 'ExecStart=' 'ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock' | sudo tee /etc/systemd/system/docker.service.d/override.conf >/dev/null && " +
+            "sudo systemctl daemon-reload) 2>&1 && echo 'DOCKER_REMOTE_CONFIGURED' || echo 'DOCKER_REMOTE_CONFIG_FAILED'";
         
         String result = cbtumblebugRestApi.executeMciCommand(namespace, mciId, configureDockerCommand, null, vmId);
         log.info("Docker remote access configuration result: {}", result);
+
+        requireCommandSuccess(
+            result,
+            "DOCKER_REMOTE_CONFIGURED",
+            "DOCKER_REMOTE_CONFIG_FAILED",
+            "Failed to configure Docker remote API through systemd override");
     }
 
     private void configureSSHForDockerAccess(String namespace, String mciId, String vmId) throws Exception {
@@ -188,9 +234,15 @@ private void configureVmMaxMapCount(String namespace, String mciId, String vmId)
     }
 
     private void restartDocker(String namespace, String mciId, String vmId) throws Exception {
-        String restartCommand = "sudo systemctl restart docker";
+        String restartCommand = "(sudo systemctl restart docker) 2>&1 && echo 'DOCKER_RESTARTED' || echo 'DOCKER_RESTART_FAILED'";
         String result = cbtumblebugRestApi.executeMciCommand(namespace, mciId, restartCommand, null, vmId);
         log.info("Docker restart result: {}", result);
+
+        requireCommandSuccess(
+            result,
+            "DOCKER_RESTARTED",
+            "DOCKER_RESTART_FAILED",
+            "Failed to restart Docker service after remote API configuration");
     }
 
     private void verifyDockerConfiguration(String namespace, String mciId, String vmId) throws Exception {
@@ -216,4 +268,13 @@ private void verifyDockerConfiguration(String namespace, String mciId, String vm
         
         log.info("Docker configuration verified successfully");
     }
-}
\ No newline at end of file
+
+    private void requireCommandSuccess(String result, String successMarker, String failureMarker, String message) {
+        String commandResult = result == null ? "" : result;
+        if (commandResult.contains(successMarker) && !commandResult.contains(failureMarker)) {
+            return;
+        }
+
+        throw new ApplicationException(message + ". Result: " + commandResult);
+    }
+}
diff --git a/src/test/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupServiceTest.java b/src/test/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupServiceTest.java
new file mode 100644
index 00000000..078d82cf
--- /dev/null
+++ b/src/test/java/kr/co/mcmp/softwarecatalog/docker/service/DockerSetupServiceTest.java
@@ -0,0 +1,119 @@
+package kr.co.mcmp.softwarecatalog.docker.service;
+
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.argThat;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import kr.co.mcmp.ape.cbtumblebug.api.CbtumblebugRestApi;
+import kr.co.mcmp.softwarecatalog.application.exception.ApplicationException;
+
+@ExtendWith(MockitoExtension.class)
+class DockerSetupServiceTest {
+
+    private static final String NAMESPACE = "ns01";
+    private static final String MCI_ID = "mci01";
+    private static final String VM_ID = "vm01";
+
+    @Mock
+    private CbtumblebugRestApi cbtumblebugRestApi;
+
+    private DockerSetupService dockerSetupService;
+
+    @BeforeEach
+    void setUp() {
+        dockerSetupService = new DockerSetupService(cbtumblebugRestApi);
+    }
+
+    @Test
+    void checkAndInstallDockerSkipsConfigurationWhenDockerRemoteApiAlreadyEnabled() {
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("docker --version") && command.contains("Remote API enabled")), isNull(), eq(VM_ID)))
+                .thenReturn("Docker version 27.0.0\nRemote API enabled");
+
+        dockerSetupService.checkAndInstallDocker(NAMESPACE, MCI_ID, VM_ID);
+
+        verify(cbtumblebugRestApi, times(1))
+                .executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                        command.contains("docker --version") && command.contains("Remote API enabled")), isNull(), eq(VM_ID));
+        verify(cbtumblebugRestApi, never())
+                .executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                        command.contains("systemctl restart docker")), isNull(), eq(VM_ID));
+    }
+
+    @Test
+    void checkAndInstallDockerFailsWhenDockerServiceIsNotManagedBySystemd() {
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("docker --version") && command.contains("Remote API enabled")), isNull(), eq(VM_ID)))
+                .thenReturn("Docker version 27.0.0\nRemote API not enabled");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("sudo -n true")), isNull(), eq(VM_ID)))
+                .thenReturn("SUDO_OK");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("systemctl cat docker.service")), isNull(), eq(VM_ID)))
+                .thenReturn("DOCKER_SERVICE_NOT_FOUND");
+
+        assertThatThrownBy(() -> dockerSetupService.checkAndInstallDocker(NAMESPACE, MCI_ID, VM_ID))
+                .isInstanceOf(ApplicationException.class)
+                .hasMessageContaining("Docker systemd service is not available");
+
+        verify(cbtumblebugRestApi, never())
+                .executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                        command.contains("get-docker.sh")), isNull(), eq(VM_ID));
+        verify(cbtumblebugRestApi, never())
+                .executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                        command.contains("override.conf")), isNull(), eq(VM_ID));
+    }
+
+    @Test
+    void checkAndInstallDockerFailsWhenDockerRestartFailsAfterRemoteApiConfiguration() {
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("docker --version") && command.contains("Remote API enabled")), isNull(), eq(VM_ID)))
+                .thenReturn("Docker version 27.0.0\nRemote API not enabled");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("sudo -n true")), isNull(), eq(VM_ID)))
+                .thenReturn("SUDO_OK");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("systemctl cat docker.service")), isNull(), eq(VM_ID)))
+                .thenReturn("DOCKER_SERVICE_FOUND");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("override.conf")), isNull(), eq(VM_ID)))
+                .thenReturn("DOCKER_REMOTE_CONFIGURED");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("chmod 666")), isNull(), eq(VM_ID)))
+                .thenReturn("permissions updated");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("bridge-nf-call-iptables")), isNull(), eq(VM_ID)))
+                .thenReturn("sysctl updated");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("vm.max_map_count")), isNull(), eq(VM_ID)))
+                .thenReturn("vm.max_map_count=262144");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("PubkeyAcceptedAlgorithms")), isNull(), eq(VM_ID)))
+                .thenReturn("sshd restarted");
+        when(cbtumblebugRestApi.executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                command.contains("systemctl restart docker")), isNull(), eq(VM_ID)))
+                .thenReturn("Failed to restart docker.service: Unit docker.service not found.\nDOCKER_RESTART_FAILED");
+
+        assertThatThrownBy(() -> dockerSetupService.checkAndInstallDocker(NAMESPACE, MCI_ID, VM_ID))
+                .isInstanceOf(ApplicationException.class)
+                .hasMessageContaining("Failed to restart Docker service");
+
+        verify(cbtumblebugRestApi, never())
+                .executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                        command.contains("get-docker.sh")), isNull(), eq(VM_ID));
+        verify(cbtumblebugRestApi, never())
+                .executeMciCommand(eq(NAMESPACE), eq(MCI_ID), argThat(command ->
+                        command.startsWith("ps aux | grep dockerd")), isNull(), eq(VM_ID));
+    }
+}