Lyra Kurulum

Önkoşullar

• Ubuntu 22.04+ / Debian 12+ (apt + systemd zorunlu)
• x86_64 veya aarch64 (better-sqlite3 ve NodeSource paketleri bu mimariler için)
• root erişimi (sudo ya da doğrudan root shell)
• Node.js, git, build-essential gibi paketleri kendin kurmana gerek yok — install.sh eksikse kurar.

1. Tek komut

git clone https://github.com/eminerolll/andromeda-lyra.git lyra
cd lyra
sudo ./install.sh

veya kodu klonlamadan:

curl -fsSL https://raw.githubusercontent.com/eminerolll/andromeda-lyra/main/install.sh | sudo LYRA_REPO=https://github.com/eminerolll/andromeda-lyra.git bash

Neden root? Script sistem paketlerini kurar, /opt/lyra'ya yazar, systemd unit'i ve sudoers dosyasını oluşturur, servisi yönetir. Root olmadan çalıştırırsan hiçbir şey yapmadan doğru komutu söyleyip çıkar.

Erişim yöntemi — kurulum bunu sana sorar

Paketler kurulduktan sonra, sihirbaz başlamadan önce tek bir soru gelir:

  Bu panele nasil erisecegini sec:

    1) Cloudflare domain'im var          (onerilen)
       API token + domain -> tunnel SIMDI kurulur, sihirbaz
       https://lyra.alanadin.com gibi bir adreste acilir.
       Hicbir port acilmaz; NAT/bulut firewall'u arkasinda da calisir.

    2) Bu makine disaridan erisilebilir
       Sihirbaz http://<ip>:80 adresinde acilir.

    3) Ne domain'im var ne de port acabiliyorum
       Sihirbaz burada, terminalde calisir (CLI).

Bu soru gerçek bir kurulum hatasından doğdu: Oracle Cloud / AWS / GCP / Azure gibi sağlayıcılarda gelen portlar Security List / Security Group / NSG katmanında varsayılan olarak kapalıdır. Makine içinde firewall kapalı olsa bile http://<ip> dışarıdan açılmaz — kurulum sana erişemeyeceğin bir adres vermiş olur.

install.sh bunu önceden anlamak için 169.254.169.254 metadata servisine kısa (~1.5 sn) bir sorgu atar. Bulut tespit edilirse uyarır ve 2. seçeneği varsayılan yapmaz; ağ yoksa ya da cevap gelmezse sessizce eski davranışa döner (fiziksel/ev sunucusunda 80 genelde açıktır).

1. seçenekte tunnel sihirbazdan önce kurulur: token ve domain doğrulanır, tunnel + ingress + DNS oluşturulur, cloudflared servis olur. Token geçersizse hiçbir şey kurulmadan hata verilir ve menüye dönülür — yarım kurulmuş sistem kalmaz. Sonra sihirbaz https://<panel-host> üzerinde açılır ve Cloudflare adımını atlar. Bu modda port 80 hiç kullanılmaz: sihirbaz Lyra'nın kendi portunda (3000, 127.0.0.1) çalışır, çünkü cloudflared zaten oraya bağlıdır.

Script bittiğinde ekrana şuna benzer bir kutu basar:

────────────────────────────────────────────────────────────
  Tarayicidan kuruluma devam et:

    https://lyra.alanadin.com          <- 1. secenek
    http://5.75.222.111                <- 2. secenek

  Kurulum token'i (tarayiciya yapistir):

    ABCD-EFGH-JKLM-NPQR
────────────────────────────────────────────────────────────

Bu adresi laptop'unun tarayıcısında aç, token'ı yapıştır, sihirbazı bitir. (3. seçenekte tarayıcı yok — sihirbaz aynı terminalde başlar.)

Ortam değişkenleri

Bayraklar

Yeniden kurulumda çıkan iki tuzak. lyra uninstall sunucudaki cloudflared servisine ve Cloudflare hesabındaki tunnel'a bilerek dokunmaz (uzaktaki kaynağı sessizce silmiyoruz). Bu yüzden ikinci kurulumda:

• Sunucuda duran cloudflared servisi cloudflared service install'ı patlatır → --replace-cloudflared ver ya da önce sudo cloudflared service uninstall çalıştır.
• Aynı adda tunnel zaten vardır → --cf-tunnel-existing reuse ile devral, recreate ile sil-yeniden yarat, ya da --cf-tunnel-name ile başka bir ad kullan. Kopya tunnel üretmiyoruz.

Tunnel'ın aktif bağlantısı varsa hiçbir bayrakla devralınmaz: o tunnel başka bir makinede canlı olabilir ve devralmak o sistemin erişimini keser. Önce oradaki cloudflared'i durdur.

Non-interactive kurulum örneği (bulut sunucu, tunnel ile):

sudo LYRA_CF_API_TOKEN="$CF_TOKEN" bash install.sh --yes \
  --access cf-api --domain ornek.com

Eksik bir alan varsa kurulum hiç başlamadan hangi bayrağın gerektiğini söyleyip çıkar; varsayılana kaçmaz. --access cli interaktif terminal ister, --yes ile birlikte kullanılamaz.

curl | sudo bash akışında stdin script'in kendisi olduğu için soru sorulmaz — otomatik olarak non-interactive çalışır ve erişim yöntemi direct olur (bugünkü davranış). Bulut tespit edilirse bu durumda da uyarı basılır.

API token'ı --cf-api-token ile verirsen install.sh onu çocuk process'in argümanına koymaz: 0600 geçici bir dosyaya yazıp yolunu geçirir ve her durumda (hata/iptal dâhil) siler.

2. Kurulum ne yapar, nereye yazar

Sıralama bilinçli: systemd unit ve sudoers, sihirbazdan önce kurulur. Sihirbaz bitince Lyra kurulum modu drop-in'ini ve geçici sudoers dosyasını kendisi siler, daemon-reload yapar ve kendini yeniden başlatır. Yani "kurulum bitti, birileri restart etsin" varsayımı yok.

install.sh idempotenttir: ikinci kez çalıştırdığında repo'yu günceller, .env ve veritabanına dokunmaz, kurulum zaten tamamlanmışsa sihirbazı atlayıp sadece servisi yeniden başlatır.

3. Tarayıcıdaki sihirbaz

Servisler adımı

Lyra yönettiği servisleri kendisi kurar; SSH'a dönüp elle kurman gerekmez.

• code-server varsayılan açık, diğerleri kapalı.
• Zaten kurulu olan servis "kurulu" görünür ve tekrar kurulmaz.
• Sunucunun gerçek RAM/disk/mimari değerleri adımın başında yazar; seçim boş RAM'i aşarsa uyarılırsın, engellenmezsin.
• arm64 (Oracle A1 gibi): dört servisin de arm64 paketi var. Desteklenmeyen bir mimaride seçenek sebebiyle birlikte devre dışı kalır, gizlenmez.
• Docker otomatik kurulmaz: yoksa dbgate devre dışı kalır ve sebebi yazar.
• Bir servisin kurulumu patlarsa diğerleri ve kurulumun geri kalanı devam eder; hata kendi adımında görünür.

Güvenlik: kurulan her servis yalnızca 127.0.0.1'e bind edilir ve kendi auth'u kapalıdır — dışarıya tek kapı Lyra'nın login + 2FA + ban katmanıdır. mongod yapılandırması değiştirilmez, yalnızca bindIp doğrulanır; loopback dışındaysa servis başlatılmaz ve durum bildirilir.

Son adım /api/setup/progress'i yoklar: her arka plan adımının durumunu (bekliyor / çalışıyor / tamam / hata) gerçek hata mesajıyla gösterir. Bir adım başarısız olursa kurulum modu açık bırakılır ve ekranda ne yapılacağı yazar — "hazır ✓" deyip seni boşluğa yollamaz.

Yeniden başlatma sırasında tarayıcının bağlantısı kopar; bu hata değil, "servis yeniden başlıyor" olarak gösterilir. Sihirbaz Lyra'nın yeni adresinde /healthz yanıt verene kadar bekler, sonra yönlendirir.

Projeler dizini

Sihirbaz projeler dizinini sorar ve Lyra'nın çalıştığı Linux kullanıcısının home'unu önerir (panel kullanıcı adıyla ilgisi yok). Dizin yoksa oluşturulur; yazılamıyorsa kurulum net bir hatayla durur.

4. Erişim modları

🌍 Public (VPS + domain)

• Önce DNS A kaydını sunucuya yönlendir: lyra.example.com → <vps-ip>
• Wizard'da domain + email gir; DNS otomatik doğrulanır
• Caddy otomatik kurulur, Let's Encrypt sertifikası alır
• UFW aktifse 80/443 açılır
• Final: https://lyra.example.com

Servis subdomain'leri: code-server / dosya yöneticisi / DB arayüzü için Caddy code.<domain>, files.<domain>, db.<domain> blokları da üretir ve her biri için ayrı sertifika ister. Sihirbaz bu kayıtları da kontrol eder ve eksik olanları listeler. Bu kayıtları Lyra oluşturmaz — DNS sağlayıcında kendin açmalısın. Eksik olanlar için sertifika alınamaz; apex domain (panelin kendisi) etkilenmez, o çalışmaya devam eder. Kayıtları sonradan eklersen:

sudo systemctl reload caddy

Servisler ayrıca domain gerektirmeyen path yollarından da erişilebilir (/code/, /files/, /dev/<port>/).

🏠 LAN

• Lyra 0.0.0.0:3000'e bind olur
• UFW aktifse Lyra portu sadece sunucunun bağlı olduğu yerel ağlara açılır (ufw allow from <subnet> to any port 3000)
• Erişim: http://<sunucu-ip>:3000

🔒 Localhost

• Lyra 127.0.0.1:3000'e bind olur, firewall'a dokunulmaz
• Uzak sunucuysa SSH tünel:

  ssh -L 3000:127.0.0.1:3000 user@sunucu
  # tarayicida http://localhost:3000
  

• Laptop tarafı için lyra-connect script'i var

⚙️ Cloudflare Tunnel (NAT arkası / DDoS koruma)

• CF Dashboard: Zero Trust → Tunnels → Create
• Public hostname: lyra.example.com → http://localhost:3000
• Connector token'ı wizard'a yapıştır
• cloudflared otomatik kurulur, tunnel başlatılır
• Public IP gerekmez, firewall'da port açılmaz

🔧 Manuel

• Lyra 127.0.0.1:3000'e bind olur, başka hiçbir şey yapmaz
• Önüne kendi nginx/traefik/HAProxy'ni koyarsın, TLS senin sorumluluğun

5. Sudo ve güvenlik

Lyra iki sudoers dosyası kullanır:

/etc/sudoers.d/lyra (kalıcı, dar): port tarayıcı (ss -tlnp), Caddyfile/cloudflared config yazma, ilgili servisleri reload etme, kendi unit'ini restart etme. Her satır sabit yollara bağlı; blanket NOPASSWD: ALL yok.

/etc/sudoers.d/lyra-setup (geçici, tam yetki): kurulum fazı Caddy ve cloudflared'i apt/dpkg ile kurar, apt kaynak listesi ve GPG anahtarı yazar, firewall ve systemd'yi değiştirir. Bunları komut listesiyle daraltmak anlamsız (apt-get install * zaten tam root'tur), o yüzden kurulum fazı açıkça ayrıcalıklı ve kısa ömürlüdür: sihirbaz bitince Lyra dosyayı siler. Normal mode ilk açılışında da bir temizlik denemesi yapılır.

Kurulumu yarıda bırakırsan dosya geride kalır — elle sil:

sudo rm -f /etc/sudoers.d/lyra-setup
sudo rm -f /etc/systemd/system/lyra.service.d/setup-mode.conf
sudo systemctl daemon-reload && sudo systemctl restart lyra

systemd unit'inde ProtectHome bilinçli olarak yok: Lyra projeler dizinine repo klonlar, commit atar, .env ve not dosyası yazar. NoNewPrivileges de yok — setuid sudo onun altında çalışmaz, o zaman port tarayıcı ve reverse proxy yönetimi ölürdü. ProtectSystem=full duruyor; /var/lib/lyra, /etc/caddy, /etc/cloudflared ve projeler dizini ReadWritePaths ile yazılabilir tutulur.

Kurulum fazı istisnası: ProtectSystem=full, /usr ve /usr/local'ı salt-okunur mount eder. Sihirbaz ise Caddy/cloudflared'i ve seçilen servisleri (code-server .deb, filebrowser binary'si, mongod paketi) Lyra'nın process ağacında kurar — bu ağaç aynı mount namespace'ini miras alır, dolayısıyla sudo bile yazamaz ve dpkg "Read-only file system" ile düşer. Bu yüzden geçici setup-mode.conf drop-in'i ProtectSystem=off taşır. ReadWritePaths ile yol yol açmak yerine bu seçildi: dpkg'nin yazma kümesi açık uçlu (/usr/bin, /usr/lib, /usr/share, /etc, /var/lib/dpkg, maintainer script'leri) ve üçüncü parti kurucular her sürümde yeni yol ekleyebilir. Gevşeme yalnızca kurulum fazındadır: drop-in sihirbaz bitince silinir, servis tekrar ProtectSystem=full altına girer. Kurulum sonrası servis eklemenin yolu için §6 (lyra install-service).

6. Servis komutları

install.sh kurulum sırasında /usr/local/bin/lyra symlink'ini oluşturur. Günlük işler bu komutla yapılır:

lyra status                  # servis durumu, erişim modu, panel adresi, DB boyutu
lyra logs                    # journalctl -u lyra -f
lyra logs -n 100 --no-pager  # ekstra argümanlar journalctl'e geçer
sudo lyra update             # kod + bağımlılık + migration + restart
sudo lyra update --skip-pull # kodu sen kopyaladın, git'e dokunma
lyra reset-admin             # şifre / 2FA / ban sıfırlama
lyra connect <user@host>     # laptop tarafı SSH tunnel yardımcısı
lyra install-service --list  # kurulum sonrası servis kurulumu (aşağıya bak)
sudo lyra uninstall          # kaldırma (aşağıya bak)
lyra --help

lyra komutu yeni bir işlev eklemez; mevcut script'leri ve modülleri çağırır (lib/health.js, lib/service-installer.js, scripts/reset-admin.js, uninstall.sh, lyra-connect). Root gerektiren alt komutları (update, uninstall, install-service) root olmadan çalıştırırsan ne yapman gerektiğini söyleyip çıkar.

Kurulum sonrası servis kurmak

Sihirbazda bir servisi seçmeyi unuttun ya da kurulum o adımda patladı — panelden tekrar denemek işe yaramaz. Sebep: sihirbaz bittiğinde kurulum modu drop-in'i silinir ve lyra.service yeniden ProtectSystem=full altına girer; /usr ve /usr/local o servis için salt-okunur mount edilir. Panel içinden kurulum denersen dpkg şunu der:

unable to create '/usr/bin/code-server.dpkg-new': Read-only file system

Bu bir izin sorunu değil, mount namespace kısıtı — sudo da kurtarmaz. Çözüm, kurulumu Lyra'nın process ağacının dışında, ayrı bir root process olarak çalıştırmak:

lyra install-service --list              # ne kurulabilir, kurulamıyorsa neden
sudo lyra install-service code-server
sudo lyra install-service filebrowser

Komut sihirbazın kullandığı kurucunun aynısını çağırır (lib/service-installer.js): servis yine yalnızca 127.0.0.1'e bind edilir, kurulum başarılıysa panele (Ayarlar > Servisler) kendisi kaydedilir. Kontrol:

lyra status                     # "Kayitli servisler" bölümünde görünür
systemctl status code-server@<kullanici>
ss -tlnp | grep 8080

Kurulabilir tipler: code-server, filebrowser, dbgate (Docker gerekir), mongod. Bir tip listede "kurulamaz" görünüyorsa sebebi yanında yazar (mimari, eksik Docker, o dağıtım için apt deposu yok).

Doğrudan systemd ile:

sudo systemctl status lyra
sudo systemctl restart lyra
sudo journalctl -u lyra -f

Unit'i elden geçirmek istersen:

sudo node /opt/lyra/src/scripts/generate-systemd.js --print   # icerigi gor
sudo node /opt/lyra/src/scripts/generate-systemd.js \
     --user <kullanici> --workdir /opt/lyra/src \
     --home /var/lib/lyra --port 3000 --projects-dir /home/<kullanici>/projects
sudo systemctl daemon-reload && sudo systemctl restart lyra

Sudoers dosyasını yeniden üretmek için:

sudo node /opt/lyra/src/scripts/generate-sudoers.js --print   # icerigi gor
sudo node /opt/lyra/src/scripts/generate-sudoers.js --user <kullanici>

Headless kurulum (terminal sihirbazı)

Tarayıcıya hiç erişemiyorsan (kapalı ağ, SSH-only, otomasyon) sihirbazın terminal sürümü aynı işi yapar. Tarayıcı sihirbazıyla aynı soruları sorar ve aynı kodu çalıştırır: doğrulama, Cloudflare ön-kontrolü, veritabanı seed'i ve kurulum sonrası adımlar src/lib/setup-core.js içinde ortaktır. İki ayrı kurulum gerçekliği yok.

En kolay yolu kurulum sırasında 3. seçeneği işaretlemektir: install.sh sihirbazı orada, o terminalde başlatır — kopyalayacağın komut yok.

Sonradan çalıştırmak istersen: install.sh 1. ya da 2. seçenekle çalıştıysa Lyra kurulum modunda bir portu tutuyordur; önce onu durdur:

sudo systemctl stop lyra
cd /opt/lyra/src
sudo -u <kullanici> LYRA_HOME=/var/lib/lyra node scripts/setup-cli.js

Tunnel kurulumda hazırlandıysa terminal sihirbazı da erişim modu adımını atlar ve "Cloudflare: yapilandirildi" der.

Yerel bir checkout'tan:

npm run setup -- --cli

Sihirbaz sırayla: erişim modu → moda özel alanlar (domain/e-posta, CF token) → uygulama adı + projeler dizini → yönetici hesabı (şifre ≥ 12) → 2FA → servisler → entegrasyonlar → özet + onay. QR kod yerine TOTP secret'ı ve otpauth:// URI'si terminale basılır; kodu doğrulamadan 2FA açılmaz.

Tam non-interactive (Ansible, cloud-init, CI)

sudo -u <kullanici> LYRA_HOME=/var/lib/lyra \
  LYRA_ADMIN_PASSWORD='cok-uzun-bir-sifre' \
  node /opt/lyra/src/scripts/setup-cli.js --yes \
    --mode cf-api --domain ornek.com --cf-api-token "$CF_TOKEN" \
    --app-name "Lyra" --projects-dir /home/<kullanici>/projects \
    --user admin --no-2fa

Eksik zorunlu alan varsa kurulum başlamaz; hangi bayrağın eksik olduğu tek tek yazılır. Sessizce varsayılana kaçılmaz. Tam liste: node scripts/setup-cli.js --help.

CLI sihirbazı kurulum sonrası geçişi (drop-in silme, daemon-reload, systemctl restart lyra) kendisi yapar ve sonucu doğrular — tarayıcı modundaki systemd-run gecikmesi burada gerekmez, çünkü sihirbaz servisin kendisi değil ayrı bir process'tir.

npm run setup (tarayıcı modu) hâlâ çalışır ama sihirbazı ön planda başlatır; port 80 için sudo ister ve sonundaki restart adımı ancak systemd unit'i kuruluysa iş görür. Önerilen yol install.sh. (Tunnel önceden kurulduysa npm run setup de port 80 istemez: Lyra'nın kendi portunu kullanır.)

Sadece tunnel kurulumu

install.sh'in 1. seçenekte çalıştırdığı adım tek başına da çağrılabilir — sihirbazın Cloudflare adımıyla aynı kodu kullanır:

sudo -u <kullanici> LYRA_HOME=/var/lib/lyra \
  node /opt/lyra/src/scripts/setup-cli.js --provision-tunnel

Token/zone doğrulanır, tunnel + ingress + DNS kurulur, cloudflared servis olur ve access_mode, base_domain, panel_host, public_access ayarları yazılır. Doğrulama başarısız olursa hiçbir kalıcı ayar yazılmaz. Sonrasında her iki sihirbaz da bu adımı atlar.

Ayarları sonradan değiştirme

Setup sonrası Lyra dashboard'da sağ üstteki dişli ikonuyla Settings modal'ını aç. 6 sekme:

• Genel: app adı, projeler dizini, ikincil disk
• Erişim: bind address, public mode, base domain, subdomain'ler
• Servisler: kayıtlı systemd unit'leri ekle/sil/aktif et
• Güvenlik: rate limit, ban ayarları, session TTL
• Entegrasyonlar: Telegram, GitHub, Cloudflare token'ları
• Hesap: şifre değiştir, 2FA aç/kapat

bind_address veya public_access değişirse Lyra restart ister.

Güncelleme

sudo lyra update

Git deposunu --ff-only çeker, npm ci --omit=dev çalıştırır, migration'ları uygular ve servisi yeniden başlatıp ayağa kalktığını doğrular. .env ve veritabanına dokunmaz.

Kodu elle kopyaladıysan (tar/scp/rsync — git deposu yok): lyra update bunu fark eder ve yarım iş yapmaz; çekilecek remote olmadığını söyleyip çıkar. Yeni sürümü aynı dizine kopyaladıktan sonra:

sudo lyra update --skip-pull

Bu, kod çekme adımını atlar; bağımlılıklar, migration ve restart yine çalışır.

install.sh ile de güncellenebilir (unit ve sudoers dosyalarını da yeniler):

cd /opt/lyra
sudo ./install.sh -y

Elle yapmak istersen:

cd /opt/lyra && sudo -u <kullanici> git pull --ff-only
cd src && sudo -u <kullanici> npm ci --omit=dev
sudo -u <kullanici> npm run migrate          # idempotent
sudo systemctl restart lyra

Kaldırma

sudo lyra uninstall              # ne silineceğini listeler, onay ister
sudo lyra uninstall --keep-data  # /var/lib/lyra (DB, oturumlar) kalsın
sudo lyra uninstall --yes        # onay sorma

lyra komutu yoksa doğrudan: sudo bash /opt/lyra/uninstall.sh

Kaldırılanlar: systemd unit'i + drop-in dizini, /etc/sudoers.d/lyra ve lyra-setup, /usr/local/bin/lyra, Lyra'nın yazdığı UFW kuralları (yalnızca lyra / lyra-setup etiketli olanlar), /opt/lyra, /var/lib/lyra.

Bilerek dokunulmayanlar — script bunları siler gibi yapmaz, sadece listeler:

• Cloudflare tunnel'ı ve DNS kayıtları (uzaktaki kaynaklar; dashboard'dan sil)
• cloudflared servisi → sudo cloudflared service uninstall
• Caddy paketi ve /etc/caddy/Caddyfile → sudo apt-get remove caddy
• Projelerin durduğu dizin — asla silinmez
• Node.js ve apt paketleri

Tamamen elle yapmak istersen:

sudo systemctl disable --now lyra
sudo rm -f /etc/systemd/system/lyra.service
sudo rm -rf /etc/systemd/system/lyra.service.d
sudo rm -f /etc/sudoers.d/lyra /etc/sudoers.d/lyra-setup
sudo rm -f /usr/local/bin/lyra
sudo systemctl daemon-reload
sudo rm -rf /opt/lyra /var/lib/lyra

Sorun Giderme