내 홈랩 AI 개발 플랫폼

1 week ago 8

홈랩 서비스 관리를 위해 OpenCode Web UI에 Git 접근을 붙이고, AI 변경은 PR 검토 뒤 GitOps가 배포하는 흐름으로 구성함
약 12개의 docker compose 스택을 Arcane으로 옮겨 GitOps로 관리하며, AI 도구를 서비스 유지보수에 활용함
컨테이너 업데이트 때 릴리스 노트 확인, 브레이킹 체인지 점검, 수동 확인에 몇 시간이 걸렸지만, 이제 릴리스 노트 요약을 몇 분 안에 읽어 버전 업그레이드가 쉬워지고 안전해짐
OpenCode는 서버로 실행되며 터미널, 파일 브라우저, Git diff, git worktree를 제공하고, 여러 기기에서 지속 코딩 세션을 동기화함
AI는 실제 서비스에 직접 접근하지 못하고 Git 브랜치만 푸시할 수 있어, 검토되지 않은 코드가 배포되지 않는 구조가 됨

홈랩 관리 흐름

OpenCode Web UI에 Git 접근을 부여해 홈랩 관리를 쉽게 만들었고, OpenCode가 Git에 변경을 푸시하면 사람이 PR을 승인한 뒤 GitOps가 변경을 배포함
OpenCode는 서버로 실행되며, 지속 코딩 세션이 여러 기기에서 동기화됨
관리 중인 서비스는 약 12개의 docker compose 스택이며, 최근 Arcane으로 옮겨 GitOps로 관리하고 배포함
AI 도구 활용의 첫 사용 사례는 컨테이너 업데이트였음
- 이전에는 각 서비스의 릴리스 노트를 찾고, 브레이킹 체인지를 확인하고, 업데이트를 실행하고, 각 서비스 문제를 수동으로 확인해야 했음
- 이 과정에는 몇 시간이 걸렸지만, 이제 릴리스 노트 요약을 몇 분 안에 읽어 버전 업그레이드가 쉬워지고 안전해짐
- 대부분의 컨테이너에 healthcheck를 추가하는 데 AI를 사용해 문제를 더 빨리 발견할 수 있게 됨

Truenas 호스트에 기본 개발 도구가 있는 간단한 VM을 만들고, OpenCode 웹서버를 systemd unit으로 추가함
이 환경은 내장 터미널, 파일 브라우저, Git diff, git worktree 지원을 제공해 여러 코딩 세션을 동시에 관리할 수 있음
OpenCode의 모바일 웹 UI는 질문·답변 팝업이 매우 좋았음
Git 서버에는 OpenCode 전용 사용자와 전용 SSH 키를 부여함
- OpenCode는 프로젝트를 클론하고 브랜치를 푸시할 수 있음
- 배포 브랜치에는 직접 푸시할 수 없음
워크플로는 AI를 PR 검토 뒤에 두며, OpenCode가 변경을 작성하고 사람이 PR에서 직접 병합함
- 이 구조는 검토되지 않은 코드가 배포되는 일을 막음
VM은 인터넷과 Git 서버에는 접근할 수 있지만, 실제 서비스에는 접근할 수 없음
- 영향 범위가 작기 때문에 빌드 도구나 테스트 의존성을 설치해야 할 때 OpenCode에 VM root 권한을 부여해도 괜찮다고 판단함
이 구조는 사전 설치된 도구, 접근 가드레일, 감사 로그가 있는 개발자용 임시 컨테이너 형태의 프로덕션 개발자 플랫폼으로 확장될 수 있음
현재 구성은 필요한 기능을 제공하면서도 구성 요소가 너무 많지 않음

기본 작업 흐름은 OpenCode에서 기능 또는 개선을 계획하는 단계로 시작함
- 계획에는 명세, 구현 계획, 자체 리뷰가 들어감
가능한 경우 변경을 테스트하거나 검증함
마음에 들지 않는 부분은 OpenCode와 반복적으로 수정함
OpenCode가 변경을 기능 브랜치에 푸시함
해당 브랜치로 PR을 열고, 만족하면 PR을 병합함
병합 뒤에는 GitOps가 배포를 이어받음
- docker 서비스 변경은 Arcane이 처리함
- Home Assistant 설정 변경은 GitOps 플러그인이 처리함
- 블로그 변경은 Cloudflare Pages worker가 처리함

서비스들을 Truenas에서 Arcane GitOps 프로젝트로 옮겼으며, 주된 목적은 Truenas에서 실행하던 모든 docker compose 스택을 Git 기반 저장소로 관리하는 것이었음
OpenCode를 함께 추가하자 이 방식이 예상보다 잘 작동함
휴대폰에서 모든 컨테이너의 네트워킹을 업데이트할 수 있어, 퍼져 있는 구성 관리가 훨씬 쉬워짐
이전에는 모든 compose 스택을 훑고 네트워크 연결을 추적하는 데 몇 시간이 걸렸음
지금은 OpenCode에 코드베이스와 목표를 지정하고, 생성된 PR 변경을 확인한 뒤 병합할 수 있음

가장 큰 빈 부분은 CI 피드백임
GitHub에서는 코딩 에이전트가 Actions 로그를 보고 실패한 테스트, 린터 오류, 스택 트레이스, IaC plan 변경을 진단할 수 있음
이 방식은 단위 테스트가 다루지 못하는 변경에도 빠른 피드백 루프를 유지하는 데 도움이 됨
Forgejo에서는 이 흐름이 더 어려움
- Forgejo Actions는 공개 API를 통해 job 로그를 노출하지 않음
- 문서화되지 않은 API가 있지만, 그 API를 기반으로 구성하고 싶지는 않음
현재 설정은 AI가 변경 대상 서비스에 직접 접근하지 못한 채, 어떤 기기에서든 홈 인프라 변경을 만들 수 있게 함
컴퓨터에서 변경을 시작하고, 휴대폰에서 PR을 검토하고, GitOps가 배포를 처리하게 할 수 있음