From 0a589bd3a2bdc4fbb724e66be008475e3b6953c8 Mon Sep 17 00:00:00 2001
From: Godopu <godopu16@gmail.com>
Date: Tue, 25 Aug 2026 11:19:53 +0900
Subject: [PATCH] docs: add Ubuntu sqlite3 installation and bind-mount volume
 custom guides to README.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Document host bind-mount configuration (./volumes/data:/app/data) in README.md §5.5
- Add Ubuntu / Linux prerequisite tools installation guide (sudo apt install sqlite3 curl make) in README.md §6
- Document zero-install SQLite dump restore command via docker compose exec in README.md §7.3
- Add /volumes/ and database ignores to root .gitignore
---
 .gitignore |  7 +++++++
 README.md  | 36 +++++++++++++++++++++++++++++++++---
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 34d875a..11dd939 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,13 @@
 
 # Binary zip archives
 *.zip
+
+# Local SQLite databases and bind-mount volumes
+/volumes/
+*.db
+*.db-wal
+*.db-shm
+!backend/db/backup/*.sql
 # >>> MAM managed block (managed by install.sh — do not edit) >>>
 /.venv/
 /.mam/
diff --git a/README.md b/README.md
index 377c1bd..00093d6 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ graph TD
             Repo["Repository Layer & Transaction Order Normalizer"]
         end
 
-        subgraph Storage ["Persistent Volume Storage (anl-sqlite-storage)"]
+        subgraph Storage ["Persistent Storage (anl-sqlite-storage / ./volumes/data)"]
             SQLiteDB[("SQLite Database<br/>/app/data/anl.db")]
         end
     end
@@ -157,7 +157,26 @@ docker compose logs -f
 - **⚡ 백엔드 REST API**: [`http://localhost:8080/api/v1`](http://localhost:8080/api/v1)
 - **💓 API 헬스체크**: [`http://localhost:8080/api/v1/health`](http://localhost:8080/api/v1/health)
 
-### 5) 컨테이너 관리 및 중지
+### 5) 📂 호스트 디렉터리 바인드 마운트 (`./volumes/data`)로 변경하는 방법
+기본 명명된 볼륨 대신 호스트 로컬 폴더에 SQLite DB를 직접 마운트하여 관리하고 싶다면:
+
+1. `docker-compose.yml`의 `anl-backend` 볼륨 설정을 수정합니다:
+   ```yaml
+   services:
+     anl-backend:
+       # ...
+       volumes:
+         - ./volumes/data:/app/data
+   ```
+2. 파일 맨 아래의 `volumes:` 섹션을 주석 처리하거나 제거합니다.
+3. 호스트 디렉터리 생성 및 DB 배치:
+   ```bash
+   mkdir -p volumes/data
+   cp backend/db/backup/anl.db volumes/data/anl.db
+   ```
+4. 컨테이너 재시작: `docker compose down && docker compose up -d`
+
+### 6) 컨테이너 관리 및 중지
 ```bash
 # 서비스 재시작
 docker compose restart
@@ -175,6 +194,16 @@ docker compose down -v
 
 Docker 없이 로컬 개발 환경에서 프론트엔드와 백엔드를 각각 직접 실행하고 개발하는 방법입니다.
 
+### 🐧 사전 필수 도구 설치 (Ubuntu / Linux)
+Ubuntu 환경에서 `sqlite3`, `curl`, `make`가 설치되어 있지 않다면 먼저 설치합니다:
+```bash
+sudo apt update
+sudo apt install -y sqlite3 curl make
+```
+*(macOS의 경우: `brew install sqlite make`)*
+
+---
+
 ### 🅰️ Backend (Go REST API) 개발 가이드
 
 #### 사전 요구사항
@@ -256,7 +285,8 @@ make backup-db
 
 ### 3) 신규 환경 또는 Docker 컨테이너 복원 방법
 
-#### 🐳 Docker 배포 환경에서 복원 (추천)
+#### 🐳 Docker 배포 환경에서 복원 (추천: 호스트에 sqlite3 미설치 시에도 가능)
+컨테이너 내부의 `sqlite3` CLI를 사용하므로, 호스트에 별도 도구 설치 없이 즉시 복원됩니다:
 ```bash
 docker compose exec -T anl-backend sqlite3 /app/data/anl.db < backend/db/backup/anl_dump.sql
 ```