AssetPilot/.TemporaryDocument/DOCKER_GUIDE.md

Asset Pilot - Docker 설치 가이드

🐳 Docker 방식의 장점

• ✅ 독립된 컨테이너로 깔끔한 환경 관리
• ✅ PostgreSQL과 애플리케이션 분리
• ✅ 한 번의 명령으로 전체 시스템 실행
• ✅ 쉬운 백업 및 복구
• ✅ 포트 충돌 없음
• ✅ 업데이트 및 롤백 간편

---

📋 사전 준비

1. Docker 설치

Orange Pi (Ubuntu/Debian)

# Docker 설치 스크립트
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 로그아웃 후 재로그인 또는
newgrp docker

# Docker 서비스 시작
sudo systemctl start docker
sudo systemctl enable docker

Docker Compose 설치 (이미 포함되어 있을 수 있음)

# Docker Compose 버전 확인
docker compose version

# 없다면 설치
sudo apt-get update
sudo apt-get install docker-compose-plugin

2. 설치 확인

docker --version
docker compose version

---

🚀 설치 및 실행

1단계: 파일 업로드

Orange Pi에 asset_pilot_docker.tar.gz 파일을 전송:

# Windows에서 (PowerShell)
scp asset_pilot_docker.tar.gz orangepi@192.168.1.100:~/

# Linux/Mac에서
scp asset_pilot_docker.tar.gz orangepi@192.168.1.100:~/

2단계: 압축 해제

# SSH 접속
ssh orangepi@192.168.1.100

# 압축 해제
tar -xzf asset_pilot_docker.tar.gz
cd asset_pilot_docker

3단계: 환경 설정

# .env 파일 편집 (비밀번호 변경)
nano .env

.env 파일 내용:

DB_PASSWORD=your_secure_password_here  # 여기를 변경하세요!

저장: Ctrl + X → Y → Enter

4단계: Docker 컨테이너 실행

# 백그라운드에서 실행
docker compose up -d

# 실행 상태 확인
docker compose ps

출력 예시:

NAME                IMAGE                    STATUS         PORTS
asset_pilot_app     asset_pilot_docker-app   Up 30 seconds  0.0.0.0:8000->8000/tcp
asset_pilot_db      postgres:16-alpine       Up 30 seconds  0.0.0.0:5432->5432/tcp

5단계: 데이터베이스 초기화

# 앱 컨테이너 내부에서 초기화 스크립트 실행
docker compose exec app python init_db.py

6단계: 접속 확인

웹 브라우저에서:

http://[Orange_Pi_IP]:8000

예: http://192.168.1.100:8000

---

🔧 Docker 관리 명령어

컨테이너 관리

# 전체 시작
docker compose up -d

# 전체 중지
docker compose down

# 전체 재시작
docker compose restart

# 특정 서비스만 재시작
docker compose restart app        # 앱만
docker compose restart postgres   # DB만

# 상태 확인
docker compose ps

# 로그 확인 (실시간)
docker compose logs -f

# 특정 서비스 로그만
docker compose logs -f app
docker compose logs -f postgres

데이터베이스 관리

# PostgreSQL 컨테이너 접속
docker compose exec postgres psql -U asset_user -d asset_pilot

# SQL 쿼리 실행 예시
# \dt          # 테이블 목록
# \d assets    # assets 테이블 구조
# SELECT * FROM assets;
# \q           # 종료

애플리케이션 관리

# 앱 컨테이너 내부 접속
docker compose exec app /bin/bash

# 컨테이너 내부에서 Python 스크립트 실행
docker compose exec app python init_db.py

---

📊 데이터 관리

백업

데이터베이스 백업

# 백업 생성
docker compose exec postgres pg_dump -U asset_user asset_pilot > backup_$(date +%Y%m%d).sql

# 또는
docker compose exec -T postgres pg_dump -U asset_user asset_pilot > backup.sql

전체 볼륨 백업

# 볼륨 백업 (고급)
docker run --rm -v asset_pilot_docker_postgres_data:/data \
  -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz /data

복원

# 백업 파일 복원
cat backup.sql | docker compose exec -T postgres psql -U asset_user -d asset_pilot

CSV 데이터 가져오기 (Windows 앱에서)

# 1. CSV 파일을 컨테이너로 복사
docker cp user_assets.csv asset_pilot_app:/app/

# 2. import_csv.py 생성 (아래 스크립트 참고)
docker compose exec app python import_csv.py user_assets.csv

---

🔄 업데이트

애플리케이션 업데이트

# 1. 새 코드 받기 (파일 업로드 또는 git pull)

# 2. 이미지 재빌드
docker compose build app

# 3. 재시작
docker compose up -d app

PostgreSQL 업데이트

# 주의: 데이터 백업 필수!
# 1. 백업 생성
docker compose exec -T postgres pg_dump -U asset_user asset_pilot > backup.sql

# 2. docker-compose.yml에서 버전 변경 (예: postgres:17-alpine)

# 3. 컨테이너 재생성
docker compose down
docker compose up -d

---

🗑️ 완전 삭제

# 컨테이너 중지 및 삭제
docker compose down

# 볼륨까지 삭제 (데이터 완전 삭제!)
docker compose down -v

# 이미지도 삭제
docker rmi asset_pilot_docker-app postgres:16-alpine

---

🛠️ 문제 해결

컨테이너가 시작되지 않음

# 로그 확인
docker compose logs

# 특정 서비스 로그
docker compose logs app
docker compose logs postgres

# 컨테이너 상태 확인
docker compose ps -a

데이터베이스 연결 오류

# PostgreSQL 컨테이너 헬스체크
docker compose exec postgres pg_isready -U asset_user -d asset_pilot

# 연결 테스트
docker compose exec postgres psql -U asset_user -d asset_pilot -c "SELECT 1;"

포트 충돌

# 8000번 포트 사용 확인
sudo lsof -i :8000

# docker-compose.yml에서 포트 변경 (예: 8001:8000)

디스크 공간 부족

# 사용하지 않는 Docker 리소스 정리
docker system prune -a

# 볼륨 확인
docker volume ls

---

📱 원격 접근 설정

Nginx 리버스 프록시 (선택적)

# Nginx 설치
sudo apt install nginx

# 설정 파일 생성
sudo nano /etc/nginx/sites-available/asset_pilot

설정 내용:

server {
    listen 80;
    server_name your_domain.com;  # 또는 IP 주소

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /api/stream {
        proxy_pass http://localhost:8000/api/stream;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
    }
}

활성화:

sudo ln -s /etc/nginx/sites-available/asset_pilot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

---

🔐 보안 권장사항

1. .env 파일 보호

chmod 600 .env

2. 방화벽 설정

# 8000번 포트만 허용 (외부 접근 시)
sudo ufw allow 8000/tcp

# PostgreSQL 포트는 외부 차단 (기본값)
sudo ufw deny 5432/tcp

3. 정기 백업

# cron으로 매일 자동 백업
crontab -e

# 추가 (매일 새벽 3시)
0 3 * * * cd /home/orangepi/asset_pilot_docker && docker compose exec -T postgres pg_dump -U asset_user asset_pilot > backup_$(date +\%Y\%m\%d).sql

---

📊 시스템 리소스 모니터링

# 컨테이너 리소스 사용량
docker stats

# 특정 컨테이너만
docker stats asset_pilot_app asset_pilot_db

---

✅ 설치 체크리스트

• Docker 설치 완료
• Docker Compose 설치 완료
• 프로젝트 파일 압축 해제
• .env 파일 비밀번호 설정
• docker compose up -d 실행
• 컨테이너 상태 확인 (docker compose ps)
• 데이터베이스 초기화 (docker compose exec app python init_db.py)
• 웹 브라우저 접속 확인 (http://[IP]:8000)
• 데이터 수집 동작 확인

---

🎉 완료!

모든 과정이 완료되면 다음 URL로 접속하세요:

http://[Orange_Pi_IP]:8000

문제가 발생하면 로그를 확인하세요:

docker compose logs -f