Sunucuya kurulum

Gerekenler

• Linux (macOS'ta da aynı şekilde çalışır). Windows geliştirici kullanımı için destekleniyor; sunucu için sondaki notlara bakın.
• git ve ivralo repo'suna erişim. Repo private ve PyPI'da hiçbir şey yok; erişimi istek üzerine veriyoruz (bize yazın). Varsayılan kaynak git+ssh://'dir ve kurulumu çalıştıran kullanıcının ssh anahtarını kullanır.
• OpenAI protokolüyle konuşan bir model endpoint'i: vLLM, llama.cpp sunucusu ya da bir LiteLLM proxy'si.
• Sunucuya klonlanmış servis repo'su. ivralo'nun incelediği çalışma alanı bu repo'dur.

uv'yi ve PostgreSQL'i, aşağıda anlatıldığı gibi kurulum kendisi halleder.

Tek komut

Repo'daki scripts/install.sh dosyasının bir kopyasıyla:

sh scripts/install.sh \
  --model-url http://gpu-box:8000/v1 --model my-model \
  --workspace /srv/shop --token \
  --git-name "ivralo" --git-email ivralo@corp.example

Script üç şey yapar:

1. uv yoksa uv'yi kendi kurucusuyla kurar. İndirip çalıştırdığı, ivralo dışındaki tek şey budur.
2. ivralo'yu, içinde bir PostgreSQL taşıyan pg extra'sıyla birlikte, Python 3.13 üzerinde global bir komut olarak kurar: uv tool install --python 3.13 --force "ivralo[pg] @ <kaynak>". Platform için extra'nın wheel'i yoksa ivralo'yu extra olmadan kurar ve bunu belirtir.
3. Verdiğiniz diğer bütün argümanlarla ivralo init --server çalıştırır; başka bir dizin belirtmezseniz --home ~/ivralo kullanılır.

Aynı adımlar, elle

curl -LsSf https://astral.sh/uv/install.sh | sh        # yalnızca uv eksikse
uv tool install --python 3.13 --force 'ivralo[pg] @ git+ssh://git@github.com/kemalcalak/ivralo.git'
ivralo init --server --yes --home ~/ivralo \
  --model-url http://gpu-box:8000/v1 --model my-model \
  --workspace /srv/shop --token \
  --git-name "ivralo" --git-email ivralo@corp.example

Bir sürüme sabitlemek için kaynağın sonuna @v0.1.2 ekleyin. uv tool update-shell, uv'nin araç dizinini shell profilinize ekler. init de ivralo'yu çalıştıran kullanıcının profiline eklenecek export IVRALO_HOME=... satırını basar.

Gizli değerleri hiçbir zaman komut satırına yazmayın; orada süreç listesinde ya da shell geçmişinde kalırlar. Onları komutun ortamına koyun, init de ana dizinin .env'ine yazsın:

IVRALO_OPENAI_COMPATIBLE_KEY=... GITHUB_ACCESS_TOKEN=... ivralo init --server ...

--server ne yapar

ivralo init --server, soruları böyle bir makineye göre önceden cevaplanmış bir ivralo init'tir:

• Hiçbir şey sormaz (--yes). Tek istisna, projenin kurulum adımının çalıştırılıp çalıştırılmayacağıdır; bunu da yalnızca elle yazılmış bir --yes cevaplar.
• Tarayıcı kurmaz, Ollama modeli çekmez, git hook'larını ayarlamaz. --browser, --pull ve --hooks ile bunları tek tek geri açabilirsiniz.
• IVRALO_WEB=false yazar; --embed-model ile bir embedding modeli belirtmediyseniz IVRALO_KNOWLEDGE=false da yazar.
• IVRALO_MODE=server yazar (Server modu ve incident'lar).
• PostgreSQL'i kendisi bulur (--postgres auto).

Bunların her biri ana dizinin .env'inde bir satırdır. Sizin değiştirdiğiniz satırlara asla dokunulmaz; bu yüzden komutu yeniden çalıştırmak her şeyi sıfırlamaz, yalnızca yükseltir.

Git kimliği ve forge kimlik bilgisi

Server modunda başında kimse olmayan bir çalıştırma commit atabilir ve kendi açtığı branch'ten taslak bir pull request açabilir. Bu yüzden kurulum iki şey daha ister.

ivralo git'te kim olarak görünür. ivralo'ya ait bir ad ve e-posta; asla sizinki değil. ivralo kendi commit'lerini bir insanın commit'lerinden bu adresle ayırt eder; bu yüzden init, operatörün global user.email'ini de repo'nunkini de kabul etmez. İkisi de <home>/gitconfig dosyasına yazılır; sizin git yapılandırmanız yalnızca okunur. --yes ile çalışırken bu iki seçenek verilmemişse satır kırmızı çıkar.

ivralo forge'a nasıl giriş yapar. Tek bir forge vardır: github.com ya da Enterprise sunucusu için IVRALO_GITHUB_URL'deki host. origin bu host'ta https kullanmalıdır; ssh remote'u kabul edilmez. Kimlik bilgisi şu sırayla aranır:

1. ana dizinin .env'inde zaten bulunan GITHUB_ACCESS_TOKEN;
2. init'in çalıştığı ortamdaki GITHUB_ACCESS_TOKEN; bulunursa .env'e yazılır;
3. yalnızca bir terminalde ve evet dedikten sonra, gh'nin kendi oturumu (--yes ile asla);
4. bir terminalde, gizli girilen token'ın kendisi.

Token olarak, ivralo'nun çalıştığı repo'larda yalnızca contents: write ve pull requests: write yetkileri olan fine-grained bir token kullanın. init token'ı bir kez kontrol eder: kime ait olduğuna, scope'larına ve repo'ya erişip erişemediğine bakar. admin:*, delete_repo ya da workflow içeren bir token reddedilir ve yazılmaz. Hiç kimlik bilgisi yoksa ivralo yine inceler ve raporlar, yalnızca pull request açmaz.

Projenin kurulum adımı

Dil sunucusu da projenin kendi kontrolleri de taze bir klonda bulunmayan proje bağımlılıklarına ihtiyaç duyar. Bu yüzden init --server, repo'ya güvenildikten sonra repo'nun kurulum adımını çalıştırır. Adımı repo'nun kendi dosyalarından şu sırayla bulur: IVRALO.md'de # Commands altındaki bir install: satırı, bir CI workflow'u, Dockerfile, README.md ile CONTRIBUTING.md'deki kod blokları, kökteki bir JSON dosyasının packageManager alanı. Çıktıdaki satır, hangi komutun çalıştığını ve nereden okunduğunu gösterir.

Adım her komut gibi shell politikasından geçer; başında kimse yokken yalnızca elle yazılmış bir --yes ile çalışır. IVRALO.md bir dil sunucusu tanımlıyorsa init ardından kod dizinini oluşturur; tanımlı bir sunucu hiç sembol üretmediyse kırmızı satırla ve 1 çıkış koduyla biter. Adımın zaman sınırı IVRALO_INSTALL_TIMEOUT ile ayarlanır, varsayılanı 1800 saniye.

Kontrol etmek

export IVRALO_HOME=~/ivralo
ivralo doctor

forge bölümü git kimliğini, forge kimlik bilgisini ve modu gösterir; providers bölümü model endpoint'inden model listesini çeker. Her sorun, düzeltmesiyle birlikte tek satırda verilir (ivralo doctor).

API'ye ssh tüneliyle erişmek

ivralo serve, yerel API'yi yalnızca 127.0.0.1 üzerinde, varsayılan olarak 61017 portunda ve --token'ın oluşturduğu token'ın arkasında açar. Başka bir adrese bağlamak için bir seçenek yoktur. Kendi makinenizden erişmek için portu yönlendirin:

ssh -L 61017:127.0.0.1:61017 you@server        # kendi makinenizde
ivralo serve                                    # sunucuda, repo'nun içinde
TOKEN=$(ssh you@server cat ~/ivralo/api-token)  # ve kendi makinenizden kullanın

ivralo serve siz durdurana kadar ön planda çalışır; servis olarak sürekli ayakta tutmak sizin servis yöneticinizin işidir.

Yükseltmek

Aynı komutu ya da script'i yeniden çalıştırın. uv tool install --force programı yeniler; init ana dizindeki .env'e, skill'lere, token'a ve diğer her şeye dokunmaz, yalnızca verdiğiniz ayarları yeniden yazar. Ana dizindeki skill rafını sizin yerinize hiçbir şey güncellemez; yeni sürüm raftakinden fazla skill getiriyorsa bunu doctor'ın environment bölümünde görürsünüz.