Collie kurulumu

Sunucu gereksinimleri, iki giriş yolu ve ilk çalıştırma kurulumu. Önce Güvenlik belgesini okuyun: Collie, tasarım gereği makinenize uzaktan kabuk erişimi açar.

Gereksinimler

Desteklenen sunucular: Linux ve macOS. Windows deneyseldir; bkz. Windows.

Not. Belirli bir asgari tmux veya zellij sürümü zorunlu tutulmaz. Uyarlayıcılar tmux 3.4, tmux 3.6b ve zellij 0.44.2 ile test edilmiştir. Bir tmux istisnai durumu ele alınmıştır: window-size manual kullanan bir sunucuda, 3.7 altındaki tmux sürümleri pencere oluştururken çöker; bu nedenle Collie isteği engeller ve tmux set -g window-size latest çalıştırmanızı bildirir.

Yalnızca yanlarındaki özellikler için gerekli olan esnek bağımlılıklar:

Yükleme

Üç giriş yolu:

• —
  Sıfırdan yükleme - yükleme betiği veya kaynak koddan aynı sonuç.
• —
  Herdr aracılığıyla - Collie bir Herdr eklentisi olarak yüklenir ve eklenti eylemleriyle yönetilir.
• —
  Bir paketten - paket yöneticiniz Collie'yi yükler ve güncellemelerini yönetir.

Herdr, Collie programının yansıtabileceği üç çoğullayıcıdan biridir, programın bir bağımlılığı değildir. Hangisini yansıtacağınız bundan sonraki adım konusudur.

Sıfırdan yükleme

Kurulum betiği en son sürümü ~/.local/share/collie içine (COLLIE_DIR) indirir ve ikili dosyayı ~/.local/bin/collie konumuna bağlar:

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

En yeni kararlı sürümü alır ve zaten mevcut olan bir kuruluma dokunmayı reddeder; collie update bunun içindir. Kanonik kaynak, depodaki scripts/install.sh dosyasıdır: tek sayfalık POSIX sh kodudur ve asla sudo istemez.

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

Eğer ~/.local/bin PATH üzerinde değilse, ikili dosyayı doğrudan çalıştırın:

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

Bir sürümü sabitlemek veya mevcut bir kurulumu kurtarmak için (bkz. collie çalışmadığında):

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

Ön sürümler için --beta iletin: en yeni ön sürümü alır ve nihai sürüm çıkana kadar kurulum bu ana sürümün ön sürümlerini izler (Ön sürümler).

Kaynak koddan aynı sonuç

# 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

Ardından başlatın. start, ~/.config/collie/ oluşturur ve çoğullayıcı seçiminizi bunun .env dosyasına yazar, bu nedenle önceden elle doldurulacak bir şey yoktur:

bin/collie start

Herdr aracılığıyla

Önce Herdr sunucusunu başlatın (herdr veya herdr server &).

GitHub üzerinden:

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

Yerel kaynak koddan:

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

Herdr eylemleri aracılığıyla yönetin. Bir ön sürüm için etiketi herdr plugin install AltanS/collie --ref <tag> --yes ile kurun; tercihin tamamı bundan ibarettir (Ön sürümler).

Bir paketten

Collie'nin sisteminiz için paketlendiği yerlerde, diğer her şeyi kurduğunuz şekilde kurun. Paket, sürümün zaten yayımladığı derlenmiş ikili dosyayı taşır, bu nedenle makinenizde hiçbir şey derlenmez: Bun yok, git yok, derleme yok. Tüm sürüm dizini tek bir önek altına yerleşir ve PATH üzerindeki collie bu dizine bir sembolik bağ olur.

Bir paket Herdr eklentisi değildir ve PATH üzerindeki her collie eylemi her iki şekilde de aynı şekilde çalışır. Collie'nin düğmelerini Herdr içine almak için kurulu dizin ağacını bir kez bağlayın:

herdr plugin link /opt/collie

Herdr, /opt taraması yapmaz, bu nedenle paketi kendi başına asla bulamaz. Eklentinin update ve update-major eylemleri daha sonra işlemi reddeder ve bunun yerine paket yöneticinizi belirtir. Bu bir hata değil, doğru olandır: bu dizin ağacını güncelleme görevi paket yöneticinize aittir.

Arch

collie-bin henüz AUR üzerinde değildir. AUR yeni hesap kayıtlarını durdurdu ve kayıtlar yeniden açıldığında paket kendi hesabımızdan yayımlanacaktır. O zamana kadar, bu deponun bir kopyasından derleyin:

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

makepkg, mimariniz için sürüm arşivini indirir, sha256 değerini sürümün bütünlük bildirimine göre doğrular ve arşivi açar. Bun yok, başka hiçbir şeyin git kopyası yok, derleme yok.

AUR üzerine girdiğinde, bir AUR yardımcısı aynı PKGBUILD kurulumunu yapar:

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

Daha sonraki güncellemeler, kurulum yaptığınız komutun aynısı olan paru -S collie-bin veya yay -S collie-bin komutlarıdır. sudo pacman -Syu collie-bin yalnızca paketi barındıran bir depoda çalışır, örneğin Omarchy.

Paket, sürüm ağacını /opt/collie konumuna ve içine bir sembolik bağ olarak /usr/bin/collie kurar. README.md, CHANGELOG.md ve docs/ dosyaları /usr/share/doc/collie-bin/ içine, lisans ise /usr/share/licenses/collie-bin/ içine yerleşir. collie sağlar ve bununla çakışır, bu nedenle paket ile gelecekteki bir kaynak paketi aynı anda kurulamaz. Hiçbir systemd birimini etkinleştirmez: her kurulumdan sonra yaptığı gibi collie start, kendi --user biriminizi yazar.

Not. Her yükseltmeden sonra collie restart çalıştırın. pacman dosyaları değiştirir ve hiçbir şeyi yeniden başlatmaz; bu nedenle hizmeti siz yeniden başlatana kadar hizmet, silinmiş bir ikili dosya üzerinden eski yapıyı sunmaya devam eder. collie doctor bunu restart-pending olarak bildirir ve telefon çalıştırılacak komutla birlikte "Collie diskte değiştirildi. Yeniden başlatın." uyarısını gösterir.

Üç adımda kaldırın:

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

collie uninstall hizmeti durdurur, systemd --user birimini kaldırır ve Collie'nin kendi tailscale serve eşlemesini devre dışı bırakır; pacman ardından /opt/collie ve /usr/bin/collie kaldırır ve başka hiçbir şeye dokunmaz. Size ait iki dizin kalır ve silinmelerini istediğinizde bunları elle silersiniz: ~/.local/state/collie/ (veya $COLLIE_STATE_DIR) altındaki durum ve Herdr bulunan bir ana makinede ~/.config/herdr/plugins/config/herdr.collie/ olan, .env dosyanızı barındıran yapılandırma dizini.

Omarchy

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

Omarchy hem tmux hem de Herdr içerir ve Collie kurulum başına bir çoğullayıcıyı yansıtır; bu nedenle ilk başlatmada hangisinin yönetileceğini belirtmeniz gerekir. Gördüğü iki seçenek arasında tahmin yürütmeyi reddeder. start, bu adı Collie'nin .env dosyasına yazar; bu dosya Herdr bulunan bir ana makinede ~/.config/herdr/plugins/config/herdr.collie/.env yolundadır ve sonraki başlatmalar collie start olur.

Bu işlem, collie-bin Omarchy'nin kendi paket deposuna girdiğinde çalışır ve onu ekleyen çekme isteği henüz birleştirilmemiştir. Birleştirilene kadar, yukarıdaki herhangi bir Arch makinesinde olduğu gibi aynı paketi packaging/aur üzerinden makepkg -si ile derleyin.

Güncellemeler daha sonra makineyi güncellemek için zaten çalıştırdığınız komut olan sudo pacman -Syu ile gelir. Bir AUR yardımcısı dahil edilmez çünkü pkgs.omarchy.org gerçek bir pacman deposudur. Her iki durumda da aynı PKGBUILD ve aynı /opt/collie düzeni geçerlidir.

Not. Güncellemeler paket yöneticinizden gelir ve Collie burada kendi kendini güncellemez. Bunun yerine collie update işlemi reddeder. Telefondaki güncelleme şeridinde "Collie x.y.z available via pacman." yazar ve paket yöneticisi bu klasörün sahibi olduğu için Güncellemeler sayfası bir güncelleme düğmesi yerine kopyalanacak komutu gösterir. Collie, depo yazımı olan sudo pacman -Syu collie-bin biçimini belirtir; AUR kurulumunda ise yardımcınızı çalıştırın. Yükseltmeden sonra yukarıdaki nedenden ötürü collie restart komutunu çalıştırın: pacman hiçbir şeyi yeniden başlatmaz.

Bir crew içinde bu makine telefondan hiçbir zaman güncelleme almaz: crew onu "paket yöneticisi bekleniyor" olarak listeler ve yalnızca üzerinde yardımcınızı çalıştırdığınızda eşitlenir.

Yukarıdaki Arch adımlarında olduğu gibi aynı üç adımla kaldırın.

Nix

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

Flake; x86_64-linux, aarch64-linux ve aarch64-darwin için packages.<system>.collie dışa aktarır. Sürümün kendi bütünlük bildirimindeki sha256 ile ilgili platformun sürüm tarball dosyasını çeker, Linux üzerinde ikili dosyanın yorumlayıcısını yamalar ve sürüm ağacını, içine bir sembolik bağ olarak bin/collie ile birlikte <store-path>/lib/collie dizinine kurar. Kurulum yapmadan bir kez nix run github:AltanS/collie#collie -- doctor ile çalıştırın.

Kasıtlı olarak bir kaynak derlemesi yoktur: bağımlılıkları yüklemek ağ gerektirir ve bir Nix derivation ağ erişimine sahip değildir, bu nedenle paket, sürümün zaten yayınladığı ve sağlama toplamını aldığı ikili dosyayı sarmalar.

Henüz bir NixOS modülü yoktur, yalnızca flake paketi mevcuttur; bu nedenle nix profile izlenecek yoldur: yukarıdaki gibi profilinize kurun veya flake çıktısını bir home-manager ya da environment.systemPackages listesine kendiniz ekleyin.

Not. Güncellemeler nix üzerinden gelir ve Collie burada kendi kendini güncellemez. collie update reddeder ve bunun yerine nix profile upgrade collie belirtir; telefon ise güncelleme düğmesinin olacağı yerde bu komutla birlikte yeni sürümü gösterir.

Bir crew içinde bu makine telefondan hiçbir zaman güncelleme almaz: crew onu "paket yöneticisi bekleniyor" olarak listeler ve yalnızca üzerinde nix çalıştırdığınızda eşitlenir.

Önce collie stop ile kaldırın, ardından:

nix profile remove collie

Bu işlem profilinizden yalnızca depo yolunu kaldırır, başka hiçbir şeye dokunmaz. Kendi dosyalarınız kalır: ~/.local/state/collie (veya $COLLIE_STATE_DIR) içindeki durum, ~/.config/collie içindeki yapılandırma ve collie start tarafından yazılan ~/.config/systemd/user/collie.service konumundaki systemd --user birimi. Bu birimi ve bağlantı noktası eşlemesini kaldırmak için paketi silmeden önce collie uninstall çalıştırın.

mise

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

mise use -g, aracı ~/.config/mise/config.toml içine yazar ve sürümün bin/ dosyasını PATH ortamınıza ekler. github arka ucu ilgili platformun sürüm tarball dosyasını çeker, bu sayede işlem Bun olmadan ve derleme gerekmeden Linux ve macOS üzerinde çalışır. Tüm ağaç web/dist ve herdr-plugin.toml dahil olmak üzere ~/.local/share/mise/installs/github-altan-s-collie/<version>/ altına yerleşir ve collie kendi kök dizinini oradan çözer.

Aynı mise use satırı ve daha yeni bir etiketle yeni bir sürüm alın veya en son sürümü mise'ın seçmesine izin verin:

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

Önemli olan bayrak --bump bayrağıdır. Sabitlenmiş bir 1.5.6 tek bir sürümlük bir aralıktır, bu nedenle yalın bir mise upgrade aracın güncel olduğunu bildirir ve hiçbir şeyi taşımaz.

Yeniden başlatma isteğe bağlı değildir. Her sürüm kendi dizinini alır ve collie start çalıştırıldığı dizini servis tanımına sabitler, bu nedenle siz yeniden başlatana kadar servis eski sürümü eski dizinden sunmaya devam eder. collie restart bu tanımı yeni yolla yeniden yazar: Linux üzerinde systemd --user birimi, macOS üzerinde ~/Library/LaunchAgents plist dosyası. Her ikisinde de tek bir komut.

Not. Yalnızca SSH üzerinden yönetilen bir Mac, bir aracıyı içine yükleyecek bir gui/<uid> alanına sahip değildir. Bu durumda collie start bunu bildirir ve hata durumunda yeniden başlatma ile oturum açmada çalıştırma özelliği olmadan, denetimsiz bir arka plan köprüsü çalıştırır. collie restart onu yine de yeni dizine taşır.

Not. collie update burada işlemi reddeder ve hiçbir paket yöneticisi belirtmez: cannot tell how this Collie was installed der. Bir mise ağacı ev dizininizin içinde durur, kendine ait bir .git taşımaz ve üzerinde bir versions/ düzeni barındırmaz; bu nedenle Collie bunu ne bir depo kopyası ne de bir paket olarak okur. Bu kurulumda güncellemelerin sahibi mise'dır ve onu taşıyan şey yukarıdaki iki komuttur.

Önce collie uninstall ile kaldırın, ardından:

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

uninstall o sürümün dizinini siler, unuse yapılandırmadan ilgili satırı kaldırır. Her iki komut için de aracı tam github: adıyla belirtin; kısa collie adı upgrade için çalışır, uninstall için çalışmaz. Kendi dosyalarınız kalır: ~/.local/state/collie (veya $COLLIE_STATE_DIR) içindeki durum ve ~/.config/collie içindeki yapılandırma.

PKGBUILD, Nix ifadesi ve bunlara ait notlar bu depodaki packaging/ içinde yer alır. macOS henüz bir pakete sahip değildir; en yakın seçenek aarch64-darwin flake çıktısıdır.

Çoğullayıcınızı adlandırın

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

Collie tek bir arka ucu yansıtır: COLLIE_MUX=herdr (varsayılan), tmux veya zellij. Yukarıdaki dosyayı ilk başlatmadan önce oluşturmak kararı baştan vermenizi sağlar; bu dosya bağımsız olarak ~/.config/collie/.env veya herdr plugin config-dir herdr.collie komutunun yazdırdığı yoldur. Ardından arka ucu ve uç noktasını ayarlayın:

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

Not. Önce bunu kurmanız gerekmez. İlk start, canlı bir Herdr soketi, çalışan bir tmux sunucusu ve zellij oturumları arar, bulduklarını ekrana yazar ve yanıtınızı .env yapılandırmasına yazarak onu oluşturur. Soru sorabileceği bir terminal yoksa, bulduğu tek arka ucu seçer ve hangisi olduğunu belirtir; hiçbiri yoksa veya birden fazlaysa başlamayı reddeder ve COLLIE_MUX gösterir.

Dikkat. Bu cp komutunu bir başlatma sonrasında çalıştırmayın: başlatmanın az önce yazdığı COLLIE_MUX üzerine .env.example yazar.

Ardından dosyayı düzenleyin. Bkz. Collie'yi bir çoklayıcıya yönlendirme.

Başlatın

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

start şunları yapar:

1. 01
   Eksikse web/dist derler.
2. 02
   Köprüyü systemd --user (veya launchd/nohup) altında başlatır.
3. 03
   tailscale serve --bg 8787 çalıştırır (HTTPS :443 → 127.0.0.1:8787). Bunun için tailnet ağınızda HTTPS'in etkin olması gerekir (yönetici konsolu → "Enable HTTPS"); etkin değilse Collie bunu bildirir ve durur.
4. 04
   Bağlantı başlığını yazdırır.

İlk çalıştırma: görecekleriniz

bin/collie start çıktısı (Herdr çalıştırmaları JSON döndürür; günlükleri herdr plugin log list --plugin herdr.collie ile görüntüleyin):

$ 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

Sağlık kontrolü başarısız olursa (⚠ Collie isn't answering on :8787 yet), bkz. Sorun giderme.

stop servisi durdurur; uninstall servisi ve proxy'yi kaldırır. Köprü, oturum açıldığında başlayan ve hata durumunda yeniden başlatılan (ARCHITECTURE.md §3), macOS üzerinde bir launchd aracısı olan bir systemd --user servisi olarak çalışır; Linux'ta loginctl enable-linger $USER yeniden başlatma sonrasında çalışmasını sağlar (Yeniden başlatmalardan sonra çalışmayı sürdürme).

Yapılandırma içinde kullanıcı erişimini ve eşleme (bin/collie pair) üzerinden cihaz erişimini yapılandırın.

Telefonunuzda açın

Başlıktaki tailnet URL'sini açın (bin/collie url ile istediğiniz zaman alın veya bin/collie qr ile bir QR kodu oluşturun). İstemciniz aynı tailnet üzerinde olmalıdır.

1. 01
   Cihazı eşleyin: Ana makinede bin/collie pair çalıştırın. İstemcide kod doldurulmuş şekilde Ayarlar → Eşlenen cihazlar bölümünü açmak için yazdırılan QR kodunu tarayın veya istemcide Ayarlar → Eşlenen cihazlar bölümünü açıp kodu yazın (Bir cihazı eşleyin).
2. 02
   Uygulamayı yükleyin: Tarayıcı sunuyorsa Ayarlar içindeki Yükleme seçeneğine dokunun veya iOS/iPadOS üzerinde paylaşım sayfasını kullanın.

Not. Android'de veya masaüstünde: Chrome ve Edge uygulamanın yüklenebilir olduğuna karar verdikleri anda bir yükleme düğmesi sunar; Collie bu teklifi Ayarlar'ın en üstünde bir Yükleme kartı olarak gösterir.

Not. iPhone veya iPad'de: Safari bu teklifi asla sunmaz (orada yükleme her zaman paylaşım sayfası üzerinden yapılır), bu nedenle aynı kart yalnızca geçerli oldukları sırada bu adımları gösterir.

PWA'yı yüklemek HTTPS gerektirir; COLLIE_SERVE_MODE=http service worker'ları devre dışı bırakır, bu nedenle telefon bu modda yalnızca tarayıcı sekmesini kullanabilir. Bir dev derlemesi (sürüm etiketinde bulunmayan herhangi bir checkout), turuncu bir simgeyle Collie (dev) olarak yüklenir; böylece ana ekranınızda bir sürüm yüklemesinin yanında aynı görünümle yer almaz.

Gerçekten çalışıyor mu?

Durumu ve günlükleri doğrulayın:

$ 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).

Erişimi kısıtlamak için .env içinde COLLIE_TRUSTED_USER=you@example.com ayarlayın ve bin/collie restart çalıştırın (Yapılandırma). Eksik gösterge paneli içeriği için bkz. Sorun giderme.

Güncel tutun

Tek bir komut geçerli ana sürümü günceller.

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

Güncellemeler geçerli ana sürüm için geçerlidir; bir üst ana sürüme geçmek collie update --major veya Herdr ile yönetilen bir kurulumda update-major eylemidir. Bu işlem, geri almalar ve kaldırma için bkz. Yönetim ve güncelleme.