메뉴
HN
Hacker News 43일 전

홈랩을 위한 나만의 AI 개발 플랫폼 구축하기

IMP
6/10
핵심 요약

개발자가 자체 홈랩(Home server) 환경에서 AI 코딩 에이전트인 OpenCode와 GitOps를 연동하여 인프라 관리를 자동화한 사례를 공유했습니다. AI가 직접 코드를 수정하고 PR을 생성하면 관리자가 이를 검토해 병합하는 방식으로, 컨테이너 업데이트와 네트워크 설정 변경을 매우 빠르고 안전하게 처리할 수 있습니다. 모바일 등 기기에 동기화되는 웹 UI를 통해 언제 어디서나 AI의 도움을 받아 복잡한 홈랩 인프라를 쉽게 유지보수할 수 있다는 점이 핵심입니다.

번역된 본문

홈랩(가정용 서버)을 더 쉽게 관리하기 위해 Git 접근 권한을 가진 OpenCode Web UI를 구축했습니다. OpenCode가 Git에 코드를 푸시(Push)하고, 제가 PR(풀 리퀘스트)을 승인하면, GitOps가 해당 변경 사항을 배포하는 구조입니다. 무엇보다 가장 좋은 점은 OpenCode가 서버로 실행되어 여러 기기에 동기화되는 영구적인 코딩 세션을 유지한다는 것입니다. 제 홈랩 설정은 곧 공유할 예정입니다. 제가 관리하는 서비스를 위해 약 12개 정도의 Docker Compose 스택이 있습니다. 최근에는 GitOps를 통해 이들을 관리하고 배포할 수 있도록 Arcane으로 이동했습니다.

여기서 자연스러운 다음 단계는 서비스 유지보수를 돕기 위해 AI 도구를 활용하는 것이었습니다. 가장 먼저 떠오른 사용 사례는 컨테이너 업데이트를 AI로 지원받는 것이었습니다. 이전에는 각 서비스의 릴리스 노트를 찾아보고 호환성을 깨뜨리는 변경 사항(Breaking changes)이 있는지 확인한 다음, 업데이트를 실행하고 문제가 없는지 각 서비스를 수동으로 확인하느라 시간을 보냈습니다. 이 작업만 몇 시간이 걸렸습니다. 하지만 이제는 몇 분 안에 릴리스 노트의 요약을 읽을 수 있어 버전 업그레이드가 훨씬 쉽고 안전해졌습니다. 게다가 AI를 사용하여 대부분의 컨테이너에 헬스 체크(Healthchecks)를 추가하여 문제를 더 빨리 파악할 수 있게 했습니다.

OpenCode 저는 주로 Claude Code를 사용했지만, 최근 AI 제공업체들이 토큰 제한을 통해 고객의 가치를 너무 짜내고 있어서 이 참에 다른 대안을 찾아보게 되었습니다. 특정 업체에 종속되지 않고 주요 플러그인을 지원하는 것이 필요했습니다. 그 결과 OpenCode를 선택했습니다. 쓸만한 다른 코딩 환경들도 있었겠지만, 제가 테스트해 본 것들 중에서는 이것이 가장 마음에 들었습니다. 그러다 이 도구에 기본 웹 서버와 웹 UI가 내장되어 있다는 것을 발견했고, 이를 통해 좋은 아이디어를 떠올렸습니다.

AI 개발 플랫폼 TrueNAS 호스트에 기본 개발 도구가 설치된 단순한 가상 머신(VM)을 하나 만들고, OpenCode 웹 서버를 systemd 단위로 추가했습니다. 이 환경은 기본 터미널, 파일 브라우저, Git diff(차이점) 기능뿐만 아니라 여러 코딩 세션을 동시에 관리할 수 있는 git worktree 기능을 갖춘 훌륭한 환경입니다. 게다가, 제가 본 모바일 웹 UI 중에서 OpenCode의 질문/답변 팝업이 가장 완성도가 높았습니다.

저는 Git 서버에서 OpenCode 전용 사용자 계정과 전용 SSH 키를 발급해 주었습니다. 이 계정은 프로젝트를 클론(Clone)하고 브랜치를 푸시할 수는 있지만, 배포 브랜치(Deploy branch)에는 직접 푸시할 수 없도록 제한했습니다. 저의 워크플로우는 AI를 철저히 PR 리뷰 뒤에 배치합니다. OpenCode가 코드를 수정하면, 제가 PR을 통해 직접 병합(Merge)하는 식입니다. 재미있기도 하지만, 더 중요한 것은 검토되지 않은 코드가 배포되는 것을 막아준다는 점입니다. 이 VM은 인터넷과 제 Git 서버에는 접근할 수 있지만, 실제 서비스 환경에는 닿을 수 없도록 격리했습니다. 피해 반경(Blast radius)이 작기 때문에, OpenCode가 빌드 도구나 테스트 종속성을 설치해야 할 때 이 VM에서 루트(Root) 권한을 부여해도 안심할 수 있습니다.

이러한 방식을 엔터프라이즈용 개발자 플랫폼으로 발전시킬 수도 있을 것이라 생각합니다. 사전 설치된 도구, 접근 제어 가드레일, 감사 로그(Audit logs)를 갖춘 임시(Ephemeral) 컨테이너를 개발자에게 제공하는 식이죠. 하지만 제게는 너무 복잡한 설정 없이도 제 역할을 충분히 해내고 있습니다.

워크플로우 제 기본 워크플로우는 다음과 같습니다:

  1. OpenCode에서 기능이나 개선 사항을 기획합니다 (사양, 구현 계획 및 자체 리뷰).
  2. 가능하면 변경 사항을 직접 테스트하거나 검증합니다.
  3. 마음에 들지 않는 부분에 대해 OpenCode와 반복적으로 수정 작업(Iterate)을 합니다.
  4. OpenCode가 변경 사항을 기능 브랜치(Feature branch)에 푸시합니다.
  5. 해당 브랜치에 대한 PR을 엽니다.
  6. 결과가 만족스러우면 PR을 병합합니다.
  7. 이후부터는 GitOps가 이어받습니다. (Docker 서비스 변경은 Arcane이, Home Assistant 설정 변경은 GitOps 플러그인이, 블로그 변경은 Cloudflare Pages 워커가 처리)

저는 서비스들을 TrueNAS에서 Arcane GitOps 프로젝트로 마이그레이션했습니다. 이는 주로 이전에 TrueNAS에서 실행하던 모든 Docker Compose 스택에 대해 Git 기반의 스토리지를 사용하기 위함이었습니다. 그리고 이것이 OpenCode를 추가하는 것과 얼마나 잘 작동하는지에 놀랐습니다. 예를 들어, 휴대폰에서 모든 컨테이너의 네트워킹 설정을 업데이트할 수 있어 무분별하게 퍼져 있는 서비스들을 훨씬 쉽게 관리할 수 있게 되었습니다. 예전에는 네트워크 연결을 추적하느라 모든 Compose 스택을 뒤지느라 몇 시간이 걸렸습니다. 하지만 이제는 목표를 정해 코드베이스를 가리키면 OpenCode가 작업하고, 결과물인 PR 변경 사항을 확인한 뒤 병합하기만 하면 됩니다.

다만 아직 가장 부족한 부분은 CI(지속적 통합) 피드백입니다. GitHub에서는 Actions 로그를 코딩 에이전트에 던져주어 실패한 테스트, 린터(Linter) 오류, 스택 트레이스, IaC(Infrastructure as Code) 계획 변경 등을 AI가 직접 진단하도록 하는 것을 좋아합니다. 이는 변경 사항을 적용할 때 빠른 피드백 루프를 유지하는 데 큰 도움이 됩니다.

원문 보기
원문 보기 (영어)
I set up OpenCode Web UI with Git access to make my homelab easier to manage. OpenCode pushes to Git, I approve the PRs, GitOps deploys the changes. Best of all, OpenCode runs as a server with persistent coding sessions synced across devices. I’ll share my homelab setup soon. There are about a dozen docker compose stacks for the services that I manage. I recently moved them to Arcane so I can manage/deploy them with GitOps. The next logical step was using AI tooling to help maintain my services. The first use that came to mind was using AI to help with container updates. Previously, I would spend time looking up the release notes for each of the services, checking for any breaking changes, running the updates, and manually checking each of the services for issues. I would spend a few hours on this. Now I can read a summary of the release notes in a few minutes, making version upgrades easier and safer. On top of that, I’ve used AI to add healthchecks to most of the containers to make it faster to spot issues. OpenCode I mainly used Claude Code, but AI providers have been really squeezing the value out of customers recently through token limits, so I took the opportunity to look into other options. I wanted something that was vendor agnostic and supported by the major plugins. I ended on OpenCode . There are probably other decent coding environments, but this was my favorite of the ones I tried. Then I found it ships with a built in webserver and web UI , which gave me an idea. AI Dev Platform I set up a simple VM on the Truenas host with basic dev tooling and added OpenCode webserver as a systemd unit. It’s a solid environment with a built in terminal, file browser, and git diffs, as well as git worktree support for managing multiple coding sessions at the same time. Plus, OpenCode had the best the question/answer popups in the mobile web UI that I’ve seen. I gave OpenCode its own user on my Git server with dedicated SSH keys. It can clone projects and push branches, but it cannot push straight to the deploy branch. My workflow keeps the AI behind PR review. OpenCode writes the change and I merge it myself in a PR. I think it’s cute, but more importantly, it keeps unreviewed code from getting deployed. The VM has internet access and access to my Git server, but it cannot reach my actual services. Because the blast radius is small, I am comfortable giving OpenCode root on the VM when it needs to install build tools or test dependencies. I could see building this into a production developer platform. Ephemeral containers available to developers with preinstalled tooling, access guardrails, and audit logs. But for me, it does what I need it to without too many moving parts. Workflow My basic workflow is: Plan out a feature or improvement in OpenCode (spec, implementation plan, and self-reviews) I’ll test or verify changes if possible Iterate with OpenCode on things I don’t like OpenCode pushes changes to a feature branch I’ll open a PR for this branch I’ll merge the PR once I’m happy GitOps takes over from there - Arcane for docker service changes, GitOps plugin for Home Assistant config changes, Cloudflare Pages worker for blog changes I migrated my services from Truenas to Arcane GitOps projects. This was mainly to have git-backed storage for all the docker compose stacks I was running in Truenas previously. I was surprised how well this worked in conjunction with adding OpenCode. Being able to update the networking across all containers, for example, from my phone makes the sprawl much easier to manage. Before it would take hours to comb through all of the compose stacks, tracing out network connectivity. Now I can point OpenCode at the codebase with a goal, check the resulting PR changes, and merge. The main missing piece is CI feedback. On GitHub, I like pointing a coding agent at Actions logs so it can diagnose failing tests, linter errors, stack traces, and IaC plan changes. This helps maintain a fast feedback loop for changes that unit tests don’t cover. Forgejo makes that harder. Forgejo Actions does not expose job logs through the public API. There are undocumented APIs, but I would rather not build around those. This setup lets me make home infra changes from any device without giving AI direct access to the services it’s changing. I can start a change from my computer, review the PR from my phone, and let GitOps handle the deploy.