Collie 설치

호스트 요구 사항, 두 가지 진입 방법, 최초 실행 설정입니다. 보안을(를) 먼저 읽으십시오. Collie는 의도적으로 머신에 대한 원격 셸 액세스를 노출합니다.

요구 사항

지원 호스트: Linux 및 macOS. Windows는 실험적입니다. Windows을(를) 참조하십시오.

참고. tmux나 zellij의 최소 요구 버전은 없습니다. 어댑터는 tmux 3.4, tmux 3.6b, zellij 0.44.2를 대상으로 테스트했습니다. 한 가지 tmux 예외 상황이 처리되어 있습니다. window-size manual을(를) 사용하는 서버에서 3.7 미만의 tmux는 윈도우 생성 시 비정상 종료되므로, Collie가 요청을 차단하고 tmux set -g window-size latest을(를) 실행하도록 안내합니다.

소프트 의존 항목이며, 옆에 명시된 기능에만 필요합니다:

설치

세 가지 방법:

• —
  신규 설치 — 설치 스크립트 또는 소스에서 동일한 결과 생성.
• —
  Herdr를 통한 설치 — Collie가 Herdr 플러그인으로 설치되며, 플러그인 액션으로 구동됩니다.
• —
  패키지 사용 — 패키지 관리자가 Collie를 설치하고 업데이트를 관리합니다.

Herdr는 Collie가 미러링할 수 있는 세 가지 멀티플렉서 중 하나이며, 프로그램의 의존성이 아닙니다. 어떤 것을 미러링할지는 이 다음 단계입니다.

신규 설치

설치 스크립트는 최신 릴리스를 ~/.local/share/collie(COLLIE_DIR)에 다운로드하고 바이너리를 ~/.local/bin/collie에 링크합니다.

curl -fsSL https://colliepwa.dev/install.sh | sh

가장 최신의 안정 릴리스를 가져오며 이미 존재하는 설치본은 수정하지 않습니다. 기존 설치본 수정은 collie update의 역할입니다. 표준 소스는 저장소의 scripts/install.sh입니다. POSIX sh 한 페이지 분량이며 sudo을(를) 요구하지 않습니다.

curl -fsSL https://raw.githubusercontent.com/AltanS/collie/main/scripts/install.sh | less
curl -fsSL https://raw.githubusercontent.com/AltanS/collie/main/scripts/install.sh | sh

~/.local/bin이 PATH에 없으면 바이너리를 직접 실행하십시오:

~/.local/share/collie/current/bin/collie version

특정 버전을 고정하거나 기존 설치를 복구하려면(collie가 실행되지 않을 때 참조):

curl -fsSL https://colliepwa.dev/install.sh | COLLIE_TAG=v1.0.0 sh

프리릴리스의 경우 --beta을(를) 전달하십시오. 최신 프리릴리스를 가져오며, 최종 릴리스가 출시될 때까지 해당 메이저 버전의 프리릴리스를 추적하여 설치합니다(시험판).

소스에서 동일한 결과 빌드

# 1. Clone and checkout latest stable tag
git clone https://github.com/AltanS/collie.git ~/.local/share/collie
cd ~/.local/share/collie
git checkout --detach "$(git tag --list 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)"

# 2. Build runtime and UI
bash scripts/collie-ctl.sh build

# 3. Verify
bin/collie version

# 4. Optional: link to PATH
bin/collie link

그 다음 시작하십시오. start이 ~/.config/collie/을 생성하고 선택한 멀티플렉서를 .env에 기록하므로, 사전에 수동으로 시드할 필요가 없습니다:

bin/collie start

Herdr를 통한 설치

먼저 Herdr 서버를 시작하십시오(herdr 또는 herdr server &).

GitHub에서:

herdr plugin install AltanS/collie
herdr plugin action invoke start --plugin herdr.collie

로컬 소스에서:

git clone https://github.com/AltanS/collie.git && cd collie
herdr plugin link "$(pwd)"
herdr plugin action invoke start --plugin herdr.collie

Herdr 작업을(를) 통해 관리하십시오. 프리릴리스의 경우 herdr plugin install AltanS/collie --ref <tag> --yes을(를) 사용하여 태그를 설치하며, 이것이 참여(opt-in)의 전부입니다(시험판).

패키지 사용

시스템에 맞게 Collie가 패키지로 제공되는 경우, 일반적인 프로그램을 설치하는 방식으로 설치하십시오. 패키지에는 릴리스에 이미 게시된 컴파일된 바이너리가 포함되어 있으므로 시스템에서 아무것도 빌드하지 않습니다. Bun도, git도, 컴파일 작업도 필요하지 않습니다. 전체 릴리스 폴더는 단일 prefix 아래에 배치되며, PATH에 collie 심볼릭 링크가 생성되어 해당 위치를 가리킵니다.

패키지는 Herdr 플러그인이 아니며, PATH에 있는 모든 collie 동사는 어느 쪽이든 동일하게 작동합니다. Herdr 내부에서 Collie 버튼을 사용하려면 설치된 트리를 한 번 링크하십시오.

herdr plugin link /opt/collie

Herdr는 /opt을(를) 검색하지 않으므로 패키지를 스스로 찾지 못합니다. 플러그인의 update 및 update-major 작업은 거부되며 대신 패키지 관리자 이름을 표시합니다. 이는 오류가 아니라 올바른 동작입니다. 이 트리는 패키지 관리자가 업데이트해야 합니다.

Arch

collie-bin은(는) 아직 AUR에 없습니다. AUR의 신규 계정 등록이 일시 중지되었으며, 등록이 재개되면 당사 계정에서 패키지를 게시할 예정입니다. 그전까지는 이 리포지토리의 클론에서 빌드하십시오.

git clone https://github.com/AltanS/collie.git && cd collie/packaging/aur
makepkg -si
collie start

makepkg은(는) 사용자의 아키텍처에 맞는 릴리스 tarball을 다운로드하고, 릴리스의 무결성 매니페스트와 sha256을 대조하여 압축을 풉니다. Bun이나 다른 항목의 git 클론이 필요 없으며 컴파일도 하지 않습니다.

AUR에 등록된 후의 경우, AUR 헬퍼가 동일한 PKGBUILD을(를) 설치합니다.

paru -S collie-bin     # or: yay -S collie-bin
collie start

이후 업데이트는 설치 시 사용한 것과 동일한 명령인 paru -S collie-bin 또는 yay -S collie-bin입니다. sudo pacman -Syu collie-bin은(는) Omarchy와 같이 리포지토리에 패키지가 포함된 경우에만 작동합니다.

패키지는 릴리스 트리를 /opt/collie에 설치하고 /usr/bin/collie을(를) 그 안의 심볼릭 링크로 설치합니다. README.md, CHANGELOG.md, docs/은(는) /usr/share/doc/collie-bin/에 위치하며 라이선스는 /usr/share/licenses/collie-bin/에 위치합니다. collie을(를) 제공하고 이와 충돌하므로, 해당 패키지와 향후 소스 패키지를 동시에 설치할 수 없습니다. systemd 유닛은 활성화하지 않습니다. 다른 설치 후와 마찬가지로 collie start이(가) 자체 --user 유닛을 작성합니다.

참고. 업그레이드 후에는 항상 collie restart을(를) 실행하십시오. pacman은(는) 파일을 교체할 뿐 아무것도 재시작하지 않으므로, 서비스를 재시작할 때까지 삭제된 바이너리를 기반으로 이전 빌드를 계속 제공합니다. collie doctor은(는) 이를 restart-pending(으)로 보고하며, 휴대전화에는 실행할 명령과 함께 "Collie was replaced on disk. Restart it."이 표시됩니다.

세 단계로 제거하십시오.

collie uninstall
herdr plugin unlink herdr.collie   # only if you linked it
sudo pacman -Rns collie-bin

collie uninstall은(는) 서비스를 중지하고 systemd --user 유닛을 제거하며 Collie 자체 tailscale serve 매핑을 해제합니다. 그런 다음 pacman이 /opt/collie 및 /usr/bin/collie만 제거합니다. 사용자의 디렉터리 두 개는 유지되며, 삭제하려는 경우 수동으로 삭제합니다. 디렉터리는 ~/.local/state/collie/(또는 $COLLIE_STATE_DIR) 아래의 상태 디렉터리와 .env을(를) 보관하는 구성 디렉터리이며, Herdr가 있는 호스트에서는 ~/.config/herdr/plugins/config/herdr.collie/입니다.

Omarchy

sudo pacman -S collie-bin
COLLIE_MUX=herdr collie start

Omarchy는 tmux와 Herdr를 모두 제공하며, Collie는 설치당 하나의 멀티플렉서를 미러링하므로 첫 시작 시 제어할 멀티플렉서를 지정해야 합니다. 인식되는 두 멀티플렉서 중 임의로 추측하지 않습니다. start은(는) 해당 이름을 Collie의 .env에 작성하며, Herdr가 있는 호스트에서는 ~/.config/herdr/plugins/config/herdr.collie/.env이고 이후 시작 시에는 collie start입니다.

이 기능은 collie-bin이(가) Omarchy 자체 패키지 리포지토리에 포함된 후 작동하며, 이를 추가하는 풀 리퀘스트는 아직 병합되지 않았습니다. 병합되기 전까지는 위의 다른 Arch 호스트와 마찬가지로 packaging/aur에서 makepkg -si(으)로 동일한 패키지를 빌드하십시오.

이후 업데이트는 머신을 업데이트할 때 이미 실행하는 명령인 sudo pacman -Syu(으)로 진행됩니다. pkgs.omarchy.org은(는) 실제 pacman 리포지토리이므로 AUR 헬퍼가 관여하지 않습니다. 어느 쪽이든 동일한 PKGBUILD 및 동일한 /opt/collie 레이아웃입니다.

참고. 업데이트는 패키지 관리자에서 제공되며, Collie는 여기서 자체 업데이트를 수행하지 않습니다. 대신 collie update이(가) 거부됩니다. 휴대전화의 업데이트 표시줄에 "Collie x.y.z available via pacman."이 표시되고, 패키지 관리자가 해당 폴더를 관리하므로 업데이트 페이지에는 업데이트 버튼 대신 복사할 명령이 표시됩니다. Collie는 리포지토리 표기법인 sudo pacman -Syu collie-bin 형식을 지정합니다. AUR 설치에서는 헬퍼를 대신 실행하십시오. 위에서 언급한 이유로 업그레이드 후 collie restart을(를) 실행하십시오. pacman은 아무것도 재시작하지 않습니다.

pack 환경에서 이 머신은 휴대전화를 통한 업데이트를 절대 수신하지 않습니다. pack은 해당 머신을 "waits for the package manager"로 표시하며, 머신에서 직접 도우미를 실행해야만 버전이 동기화됩니다.

위의 Arch와 동일한 세 단계로 제거하십시오.

Nix

nix profile install github:AltanS/collie#collie
collie start

이 flake는 x86_64-linux, aarch64-linux, aarch64-darwin 플랫폼용 packages.<system>.collie 패키지를 내보냅니다. 릴리스의 자체 무결성 매니페스트에 있는 sha256을 기반으로 해당 플랫폼의 릴리스 tarball을 가져오고, Linux에서는 바이너리의 인터프리터 경로를 패치하며, <store-path>/lib/collie 경로에 릴리스 트리를 설치하고 bin/collie 심볼릭 링크를 생성합니다. 설치하지 않고 일회성으로 실행하려면 nix run github:AltanS/collie#collie -- doctor 명령을 사용하십시오.

의도적으로 소스 빌드를 지원하지 않습니다. 종속 항목을 설치하려면 네트워크 연결이 필요하지만 Nix derivation에는 네트워크 접근 권한이 없으므로, 패키지는 릴리스에 이미 게시되어 체크섬 검증을 마친 바이너리를 래핑합니다.

아직 NixOS 모듈이 없으며 flake 패키지만 제공되므로 nix profile 경로를 사용해야 합니다. 위와 같이 프로필에 설치하거나, home-manager 또는 environment.systemPackages 목록에 flake 출력을 직접 추가하십시오.

참고. 업데이트는 nix를 통해 제공되며, Collie는 이 환경에서 자체 업데이트를 수행하지 않습니다. collie update 명령은 업데이트를 거부하고 대신 nix profile upgrade collie 명령을 안내하며, 휴대전화 화면에는 업데이트 버튼 대신 해당 명령과 함께 새 버전이 표시됩니다.

pack 환경에서 이 머신은 휴대전화를 통한 업데이트를 절대 수신하지 않습니다. pack은 해당 머신을 "waits for the package manager"로 표시하며, 머신에서 직접 nix를 실행해야만 버전이 동기화됩니다.

먼저 collie stop 명령으로 제거한 다음, 아래를 실행하십시오.

nix profile remove collie

해당 명령은 프로필에서 스토어 경로만 제거하며 다른 것은 건드리지 않습니다. 사용자의 고유 파일은 유지됩니다. ~/.local/state/collie(또는 $COLLIE_STATE_DIR)의 상태 데이터, ~/.config/collie의 설정 파일, 그리고 collie start 명령이 작성한 ~/.config/systemd/user/collie.service 위치의 systemd --user 유닛이 유지됩니다. 패키지를 제거하기 전에 collie uninstall 명령을 실행하여 해당 유닛과 포트 매핑을 먼저 정리하십시오.

mise

mise use -g github:AltanS/collie@1.5.6
collie start

mise use -g은(는) 도구를 ~/.config/mise/config.toml에 작성하고 릴리스의 bin/을(를) PATH에 추가합니다. github 백엔드가 해당 플랫폼의 릴리스 tarball을 가져오므로 Linux 및 macOS에서 Bun과 컴파일 없이 작동합니다. 전체 트리는 web/dist 및 herdr-plugin.toml을(를) 포함하여 ~/.local/share/mise/installs/github-altan-s-collie/<version>/ 아래에 배치되며, collie은(는) 여기에서 자체 루트를 확인합니다.

동일한 mise use 라인과 최신 태그를 사용하여 새 버전을 가져오거나 mise가 최신 버전을 선택하도록 하십시오.

mise upgrade --bump github:AltanS/collie
collie restart

중요한 플래그는 --bump입니다. 고정된 1.5.6은(는) 단일 버전 범위이므로, 일반 mise upgrade은(는) 도구가 최신 상태라고 보고하며 아무것도 변경하지 않습니다.

재시작은 필수입니다. 모든 버전은 자체 디렉터리를 가지며, collie start은(는) 실행된 디렉터리를 서비스 정의에 기록하므로 재시작할 때까지 서비스가 이전 디렉터리에서 이전 버전을 계속 제공합니다. collie restart은(는) 해당 정의를 새 경로로 덮어씁니다. Linux에서는 systemd --user 유닛, macOS에서는 ~/Library/LaunchAgents plist입니다. 두 환경 모두 하나의 명령으로 처리됩니다.

참고. SSH로만 관리되는 Mac에는 에이전트를 로드할 gui/<uid> 도메인이 없습니다. 이 경우 collie start이(가) 이를 알리고 관리되지 않는 백그라운드 브리지를 대신 실행하며, 실패 시 재시작되지 않고 로그인 시에도 실행되지 않습니다. collie restart은(는) 여전히 새 디렉터리로 전환합니다.

참고. 여기서 collie update은(는) 거부되며, 패키지 관리자 이름을 지정하지 않고 cannot tell how this Collie was installed(이)라고 표시합니다. mise 트리는 홈 디렉터리 내에 위치하며 자체 .git이(가) 없고 상위에 versions/ 레이아웃도 없으므로, Collie는 이를 체크아웃이나 패키지로 인식하지 않습니다. 이 설치 환경에서는 mise가 업데이트를 관리하며, 위의 두 명령으로 전환합니다.

먼저 collie uninstall 명령으로 제거한 다음, 아래를 실행하십시오.

mise uninstall github:AltanS/collie@1.5.6
mise unuse github:AltanS/collie

uninstall은(는) 해당 버전의 디렉터리를 삭제하고, unuse은(는) 구성에서 해당 라인을 제거합니다. 두 작업 모두 도구의 전체 github: 이름을 사용하십시오. 짧은 collie은(는) upgrade에는 작동하지만 uninstall에는 작동하지 않습니다. 사용자의 파일은 유지됩니다. 상태는 ~/.local/state/collie(또는 $COLLIE_STATE_DIR), 구성은 ~/.config/collie에 유지됩니다.

PKGBUILD, Nix 표현식 및 관련 문서는 이 저장소의 packaging/ 경로에 있습니다. macOS용 패키지는 아직 제공되지 않으며, aarch64-darwin flake 출력이 이에 가장 가깝습니다.

멀티플렉서 지정

Collie는 세 가지 백엔드 중 하나를 미러링합니다: COLLIE_MUX=herdr(기본값), tmux, zellij.

참고. 먼저 설정할 필요는 없습니다.

첫 번째 start은(는) 활성화된 Herdr 소켓, 실행 중인 tmux 서버, zellij 세션을 검색하여 찾은 항목을 출력하고, 사용자의 응답을 설정 파일 .env에 작성하여 새로 생성합니다. 입력을 요청할 터미널이 없으면 검색된 유일한 백엔드를 선택하고 이를 알립니다. 검색된 백엔드가 없거나 여러 개인 경우 시작을 거부하고 COLLIE_MUX을(를) 지정합니다.

대신 사전에 결정하려면 첫 시작 전에 해당 파일에 값을 설정하십시오. 독립형의 경우 ~/.config/collie/.env이며, 또는 herdr plugin config-dir herdr.collie이 출력하는 경로입니다:

mkdir -p ~/.config/collie
cp .env.example ~/.config/collie/.env

그 다음 백엔드와 해당 엔드포인트를 설정하십시오:

COLLIE_MUX=tmux                                           # or: zellij
# zellij instead: COLLIE_MUX_ENDPOINT_ZELLIJ=<session>
COLLIE_MUX_ENDPOINT_TMUX=/run/user/1000/collie-tmux.sock

주의. 시작한 후에 해당 cp을(를) 실행하지 마십시오. 시작 시 방금 작성된 COLLIE_MUX 위에 .env.example을(를) 덮어씁니다.

그 후 파일을 편집하십시오. Collie를 multiplexer로 지정하기을(를) 참조하십시오.

시작

herdr plugin action invoke start --plugin herdr.collie   # Herdr-managed
bin/collie start                                         # standalone

start은 다음 작업을 수행합니다:

1. 01
   누락된 경우 web/dist을 빌드합니다.
2. 02
   systemd --user(또는 launchd/nohup) 하에서 브리지를 실행합니다.
3. 03
   tailscale serve --bg 8787을(를) 실행하십시오(HTTPS :443 → 127.0.0.1:8787). 이를 위해 tailnet에서 HTTPS가 활성화되어 있어야 합니다(관리 콘솔 → "Enable HTTPS"). 활성화되어 있지 않으면 Collie가 이를 알리고 중지합니다.
4. 04
   연결 배너를 출력합니다.

첫 실행 — 표시되는 내용

bin/collie start의 출력(Herdr 실행은 JSON을 반환하며, herdr plugin log list --plugin herdr.collie으로 로그를 확인합니다):

$ bin/collie start
building web UI (first run)…                    # linked clone only; a GitHub install already built
…bun install · typecheck · vite build output…
bridge started (systemd --user: collie)
tailscale serve (https) → tailnet :443 -> 127.0.0.1:8787

  ✓ Collie is running  ·  v1.0.0+b158755
    service   systemd --user (collie) · active
    local     http://127.0.0.1:8787
    tailnet   https://myhost.tail1234.ts.net

상태 확인에 실패하면(⚠ Collie isn't answering on :8787 yet), 문제 해결을 참조하십시오.

stop은(는) 서비스를 중지하고, uninstall은(는) 서비스와 프록시를 제거합니다. 브리지는 로그인 시 시작되고 실패 시 다시 시작되는 systemd --user 서비스(macOS의 launchd 에이전트)로 실행됩니다(ARCHITECTURE.md §3). Linux에서는 loginctl enable-linger $USER을(를) 통해 재부팅 후에도 유지되도록 합니다(재부팅 후에도 유지하기).

설정에서 사용자 접근을 구성하고 페어링을(를) 통해 기기 접근을 구성하십시오(bin/collie pair).

휴대폰에서 열기

배너의 tailnet URL을 엽니다(bin/collie url 명령어로 언제든지 다시 확인하거나 bin/collie qr 명령어로 QR 코드를 생성할 수 있습니다). 클라이언트가 동일한 tailnet에 연결되어 있어야 합니다.

1. 01
   기기 페어링하기: 호스트에서 bin/collie pair을(를) 실행합니다. 출력된 QR 코드를 스캔하여 코드가 입력된 상태로 클라이언트의 Settings → Paired devices를 열거나, 클라이언트에서 Settings → Paired devices를 연 뒤 코드(기기 페어링)를 직접 입력합니다.
2. 02
   PWA 설치: Safari(iOS) 또는 Chrome(Android)에서 홈 화면에 추가을(를) 탭하십시오.

PWA를 설치하려면 HTTPS가 필요합니다. COLLIE_SERVE_MODE=http은(는) 서비스 워커를 비활성화하므로, 해당 모드에서는 휴대폰 브라우저 탭만 사용할 수 있습니다.

정상 작동 확인

상태 및 로그 확인:

$ bin/collie status

  ✓ Collie is running  ·  v1.0.0+b158755
    service   systemd --user (collie) · active
    local     http://127.0.0.1:8787
    tailnet   https://myhost.tail1234.ts.net

  serve config:
    https://myhost.tail1234.ts.net (tailnet only)
    |-- / proxy http://127.0.0.1:8787

$ bin/collie logs        # journal timestamps trimmed here
[push] disabled (no VAPID keys configured)
[bridge] listening on http://127.0.0.1:8787  (poll 1500ms)
[bridge] WARNING: COLLIE_TRUSTED_USER is empty — any tailnet device/user that reaches the bridge gets full write access. Set it to your tailnet login (see README → Variant A).

접근을 제한하려면 .env 파일에 COLLIE_TRUSTED_USER=you@example.com을 설정하고 bin/collie restart 명령을 실행합니다(설정). 대시보드 콘텐츠가 표시되지 않는 경우 문제 해결 문서를 참고합니다.

최신 상태 유지

명령어 하나로 현재 메이저 버전을 업데이트합니다.

herdr plugin action invoke update --plugin herdr.collie   # Herdr-managed
bin/collie update                                         # standalone

업데이트는 현재 메이저 버전에 적용됩니다. 다른 메이저 버전으로 전환하려면 collie update --major을(를) 실행하거나 Herdr 관리 설치에서 update-major 작업을 수행해야 합니다. 이에 대한 내용과 롤백 및 제거는 관리 및 업데이트을(를) 참조하십시오.