Git Image WebBuilder

컨테이너 이미지 빌드, 레지스트리 푸시, Kubernetes 워크로드 롤아웃을 웹 UI로 수행하는 도구.

구성도

                         ┌─────────────────────────────────────────────┐
                         │          Git Image WebBuilder               │
                         │          :8888 (Flask + gunicorn)           │
                         │                                             │
                         │  ┌─────────┐ ┌─────────┐ ┌───────────────┐ │
                         │  │ Sources │ │ Builder │ │   Scripts     │ │
                         │  │         │ │         │ │               │ │
                         │  │Registry │ │Build    │ │Registered     │ │
                         │  │Git Svr  │ │Push     │ │Ad-hoc (SSH)   │ │
                         │  └─────────┘ │Rollout  │ └───────────────┘ │
                         │              └────┬────┘                   │
                         │   ┌───────────────┼───────────────┐        │
                         │   │  SQLite DB    │  Build Logs   │        │
                         │   │  (builder.db) │  (data/)      │        │
                         │   └───────────────┴───────────────┘        │
                         └──────┬──────────┬──────────┬───────────────┘
                                │          │          │
                 ┌──────────────┘          │          └──────────────┐
                 │                         │                         │
                 ▼                         ▼                         ▼
    ┌────────────────────┐   ┌──────────────────────┐   ┌──────────────────┐
    │   Git Server       │   │   Docker Daemon      │   │  K8s Cluster     │
    │                    │   │                      │   │                  │
    │  Forgejo / GitHub  │   │  docker build        │   │  kubectl rollout │
    │  Gitea / GitLab    │   │  docker push         │   │  restart         │
    │                    │   │                      │   │  status / pods   │
    │  SSH clone ──┐     │   │         │            │   │                  │
    │  HTTP clone ─┤     │   │         ▼            │   └──────────────────┘
    └──────────────┘     │   │  ┌──────────────┐    │
                         │   │  │  Registry    │    │
                         │   │  │  Harbor /    │    │
                         │   │  │  DockerHub   │    │
                         │   │  └──────────────┘    │
                         │   └──────────────────────┘
                         │
                ┌────────┴─────────┐
                │  Build Pipeline  │
                │                  │
                │  1. git clone    │
                │  2. Dockerfile ? │
                │  3. docker login │
                │  4. docker build │
                │  5. docker push  │
                │  6. rollout      │
                │     (optional)   │
                └──────────────────┘

빠른 시작

바닐라 설치 (.run)

chmod +x git_image_webbuilder_1.0.0.run
sudo ./git_image_webbuilder_1.0.0.run

대화형 설치가 진행된다. 기본 설정:

항목	기본값
설치 경로	/opt/image_builder
포트	8888
바인드	0.0.0.0

설치 후 접속: http://<서버IP>:8888

Docker 실행

베이스 이미지 + 앱 이미지 두 단계다. 베이스에 런타임(python·git·ssh·docker-cli· buildx·kubectl)이 전부 들어 있고, 앱 이미지 Dockerfile 에는 COPY 밖에 없다 — 폐쇄망에 코드만 들여와도 앱 이미지를 다시 만들 수 있다.

./scripts/build-base.sh                 # 런타임 베이스 (인터넷 필요, 1회)
docker-compose up -d                    # 또는 ./scripts/docker-build.sh --no-push

접속: http://<서버IP>:1800

이미지를 파일로 넘길 때:

./scripts/build-base.sh   --save /경로   # <경로>/image-builder-base-compact_<빌드시각>.tar.gz
./scripts/docker-build.sh --save /경로   # <경로>/image-builder_<빌드시각>.tar.gz
docker load -i image-builder_20260824163510.tar.gz

태그는 <빌드 시각 YYYYMMDDHHMMSS> + latest 를 항상 같이 붙인다.

앱 이미지 tar 에는 베이스 레이어가 함께 들어 있어 그것만으로도 기동된다. 베이스 tar 은 폐쇄망에서 앱 이미지를 다시 굽고 싶을 때 필요하다 (FROM 이 가리킬 태그가 있어야 한다).

릴리즈용이라 테스트 도구는 넣지 않는다 (pip·gcc/make·sudo·테스트 라이브러리 없음). 앱은 컨테이너 안에서 비특권 계정으로 돌고, entrypoint 가 호스트 docker.sock 의 gid 를 맞춰 준다.

Kubernetes

raw 매니페스트와 Helm chart 를 등가로 제공한다.

# raw
./scripts/deploy.sh apply development

# Helm
helm install image-builder ./helm -n development --create-namespace \
  --set image.tag=0.1.0-20260823

접속: Ingress builder.ai.nova.office 또는 NodePort http://<node-ip>:30088

• replica 는 1 고정 (진행 상태가 프로세스 메모리 + PVC 가 RWO)
• 빌드에 호스트 docker.sock 을 마운트한다 — 노드 docker 에 대한 완전 권한
• HTTPS 뒤에 둘 경우 COOKIE_SECURE=1 필요
• 튜너블은 ConfigMap image-builder-config (Helm 은 values.yaml 의 config:)

자세한 내용은 manual.md 1.7 절 참조.

서비스 관리

# systemd (설치 시 등록한 경우)
systemctl start   image-builder
systemctl stop    image-builder
systemctl restart image-builder
systemctl status  image-builder

# 수동
/opt/image_builder/bin/run.sh start|stop|restart|status

제거

sudo ./git_image_webbuilder_1.0.0.run uninstall

주요 기능

• 로그인: 파일 기반 id/password. 첫 기동 시 admin 계정이 임의 비밀번호로 생성되어 로그와 <데이터경로>/initial_admin_password.txt 에 기록된다. 헤더에서 변경 가능.
• Home: 로그인 후 첫 화면. 빌드/롤아웃/스크립트 수행 이력을 한 목록으로 표시 (종류별 필터, 10초 자동 갱신, 행 클릭 시 해당 앱/스크립트로 이동)
• Sources: Registry 등록/인증, Git Server 등록/인증 (GitHub/Forgejo/Gitea/GitLab)
• Builder: 앱 등록 → 브랜치 선택 → Dockerfile 확인 → 빌드 → 푸시 → 롤아웃
• Rollout: 워크로드 status 로 완료를 판정하고, 관측 시간 안에 확인되지 않으면 실패로 단정하지 않고 확인 대기로 두고 더 기다릴지 물어본다 (추측하지 않는다)
• 오류 표시: 액션이 실패하면 모달로 보여준다(토스트는 5초면 사라진다). SSH 연결 실패에는 실제 명령과 출력을 그대로 볼 수 있는 로그 보기가 붙는다.
• SSH Key: Sources 탭에서 키를 붙여넣거나 업로드해 두고, Git 서버·스크립트 등록 화면에서 이름으로 골라 쓴다 (경로를 손으로 적지 않는다)
• Scripts: 스크립트 등록/실행, Ad-hoc 실행 (SSH/로컬, sudo)
• Instant Build: Dockerfile 을 붙여넣고 태그를 지정해 바로 빌드/푸시 (git 저장소 불필요)
• History: 빌드/롤아웃/스크립트 실행 이력

사전 요구사항

바이너리	필수	용도
python3 (3.10+)	필수	앱 실행 (3.9 는 import 단계에서 실패)
pip3	필수	Python 패키지
docker	필수	이미지 빌드/푸시
git	필수	소스 clone
kubectl	선택	롤아웃 (없으면 빌드/푸시만 가능)

인스톨러가 누락 바이너리를 자동 설치한다 (폐쇄망 시 가이드 제공).

상세 매뉴얼

manual.md 참조.

라이선스

Git-source Image builder web © 2026 TheKnowledges.net — 출처 표기 하에 자유롭게 이용 및 배포 가능.