Kurulum (self-host)

MyWay, Next.js uygulaması + PostgreSQL veritabanından oluşur. En hızlı yol Docker Compose ile ayağa kaldırmaktır.

Gereksinimler

• Docker Engine 24+ ve Docker Compose v2
• 2 vCPU / 2 GB RAM (önerilen 4 GB)
• 10 GB boş disk; yükseltme sırasında geçici olarak ~1 GB fazlası
• Alan adı (opsiyonel: iç ağda sunucunun IP adresiyle de kurulur)

Adımlar

1. 1Satın alma e-postandaki paketi indir ve sunucuna çıkart.
2. 2./scripts/install.sh çalıştır. Hazır imajları yükler (derleme yok) ve adresi, yayın portlarını ve LİSANS ANAHTARINI sorar; adres bir alan adıysa sertifika bildirimleri için bir e-posta da ister. Ardından günlük otomatik yedeği kurmayı önerir (bkz. Yedekleme & yükseltme).
3. 3Adres: alan adın varsa onu yaz. Yoksa Enter’a bas; kurulum sunucunun IP adresini bulup onu kullanır.
4. 4Port: varsayılan 80/443 için Enter. O portları başka bir servis kullanıyorsa 8080/8443 gibi bir çift verebilirsin.
5. 5Uygulama başlar; migrasyonlar otomatik uygulanır.
6. 6Tarayıcıdan adrese gir ve kaydol. Kaydolan ilk kullanıcı otomatik yönetici (superadmin) olur; kurulum betiği bunu ilk kurulumun sonunda hatırlatır, güncellemede bu uyarı çıkmaz.

# extract the package, then:
cd myway-onprem
./scripts/install.sh    # asks for address, ports, LICENSE_KEY (+ certificate email for a domain) and the daily backup, loads images, starts

İç ağa kurulum (alan adı olmadan)

Sunucunun alan adı yoksa kurulum sunucunun IP adresiyle yapılır; betik adresi kendisi bulup önerir. Bu durumda Let’s Encrypt devreye girmez (bir sertifika otoritesi IP adresini doğrulayamaz) ve uygulama kendi ürettiği sertifikayla yayınlanır. Tarayıcı ilk girişte bir kez uyarı gösterir; kalıcı olarak kaldırmak için kurulum dizinine bırakılan myway-root-ca.crt dosyasını istemci bilgisayarlara güvenilen kök sertifika olarak kurun.

Portu değiştirme

Kurulum 80 ve 443 portlarını kullanır. Sunucuda bu portları başka bir servis tutuyorsa kurulumda farklı bir çift verebilirsiniz; seçim saklanır ve sonraki güncellemelerde yeniden sorulmaz. Standart dışı portta Let’s Encrypt doğrulama yapamayacağı için kurulum kendi sertifikasına geçer: güvenilir sertifika istiyorsanız ya 80/443’te kalın ya da MyWay’i TLS’i kendisi sonlandıran mevcut proxy’nizin arkasına alın.

# soruları görmeden kurmak / installing without the prompts
DOMAIN=myway.company.com HTTP_PORT=8080 HTTPS_PORT=8443 ./scripts/install.sh

E-posta gönderimi (opsiyonel)

Kurulum e-posta olmadan da tam çalışır; varsayılan budur. Bu durumda davet bağlantısı ekranda gösterilir ve parolayı Ayarlar > Çalışma Alanı > Üyeler’den yönetici sıfırlar. E-posta göndermek istersen .env.onprem dosyasına kendi SMTP sunucunu tanımlarsın: Exchange, Postfix, Google Workspace, AWS SES; hepsi SMTP konuşur. Dışarıya bağlanan bir servis eklemiş olmazsın, mail kendi sunucundan çıkar.

MAIL_DRIVER=smtp
MAIL_FROM="MyWay <no-reply@yourcompany.com>"
MAIL_SMTP_HOST=smtp.yourcompany.com
MAIL_SMTP_PORT=587          # 465 = implicit TLS, 587/25 = STARTTLS
MAIL_SMTP_USER=username
MAIL_SMTP_PASSWORD=password

Env değişikliği restart ile okunmaz; konteyneri yeniden oluşturman gerekir. Ardından davet e-postası, parola sıfırlama, e-posta adresi doğrulama ve bildirim e-postaları kendiliğinden çalışır. Bağlantılar PUBLIC_URL üzerinden üretilir; bu adresin kullanıcılarınca erişilebilir olduğundan emin ol.

docker compose -f docker-compose.onprem.yml --env-file .env.onprem up -d

Ayarın uygulamaya gerçekten ulaştığını sağlık ucundan doğrulayın: /api/health yanıtındaki mailConfigured alanı true olmalıdır. Yanlış yazılmış ya da konteynere hiç geçmemiş bir e-posta ayarı ekranda hata üretmez, yalnız e-posta gitmez; bu alan o sessiz durumu görünür kılar.

# e-posta ayarı uygulamaya ulaştı mı / did the email settings reach the app
curl -s https://myway.company.com/api/health | grep mailConfigured

# kendi sertifikasıyla çalışan kurulumda (IP adresi ya da standart dışı port)
# on an install with its own certificate (IP address or non-standard ports)
curl -s --cacert myway-root-ca.crt https://10.0.0.5/api/health | grep mailConfigured

Yükleme boyutu sınırı

Ekler ve metne gömülen görseller için üst sınır varsayılan olarak 25 MB’tır, en fazla 500 MB’a çıkarılabilir. Büyük ekler taşıyan bir kurulumda .env.onprem dosyasındaki MAX_UPLOAD_MB ile değiştirilir. Değer megabayt cinsindendir; değişiklik env okunduğu için konteynerin yeniden oluşturulmasını gerektirir. Ürünle gelen ters vekil ayrı bir sınır koymaz; MyWay’i kendi proxy’nizin arkasına aldıysanız onun istek gövdesi sınırını da yükseltin, yoksa yükleme proxy’de kesilir. İzin verilen dosya tipleri sabittir: görsel (PNG, JPG, GIF, WebP), video (MP4, WebM), PDF, Word, Excel, metin (TXT, CSV, Markdown), ZIP ve draw.io; SVG ve HTML de yüklenebilir ama içlerine betik gömülebildiği için her zaman indirilecek dosya olarak sunulur, tarayıcıda açılmaz.

MAX_UPLOAD_MB=100

Zamanlanmış görevler

Bazı işler bir kullanıcı isteğiyle tetiklenmez, birinin saate bakması gerekir. Son tarihin gelmesi bir olay değildir: kimse bir şey yapmadığı için uygulamaya ulaşan bir istek de olmaz. MyWay bu tür iki iş çalıştırır ve v1.32.6 sürümünden beri bunları KURULUM BETİĞİ kendisi kurar; elle crontab girdisi yazmanız gerekmez.

Kurulum betiği girdileri yazar, kurulum sonunda işi bir kez deneyip sonucu ekrana bildirir ve ek yapılandırma istemez: gereken sır tanımlı değilse mevcut kurulum anahtarlarınızdan türetilir. Güncellemede girdiler tazelenir, çiftlenmez; sunucudaki başka zamanlanmış işlere dokunulmaz. v1.64.0’dan önceki sürümlerin kurduğu olay temizliği girdisini güncelleme kendisi kaldırır. İşler her gün 06:00 (son tarih bildirimleri) ve 07:00’de (gözden geçirme hatırlatmaları) çalışır, çıktıları kurulum dizinindeki logs/cron.log dosyasına yazılır; kurmak istemiyorsanız betiği NO_CRON=1 ile çalıştırın (bu durumda günlük otomatik yedek de zamanlanmaz). İşler PUBLIC_URL adresini çağırdığı için sunucu kendi adresine erişebilmelidir. Sağlık ucundaki cronConfigured alanı yalnız yapılandırmayı gösterir; işlerin gerçekten çalışıp çalışmadığını Ayarlar > Sağlık ekranındaki Zamanlanmış işler tablosu gösterir (aşağıdaki Sağlık ekranı bölümüne bakın).

# zamanlanmış görevler kuruldu mu / are the scheduled jobs configured
curl -s https://myway.company.com/api/health | grep cronConfigured

Sağlık ekranı

Ayarlar > Sağlık sekmesini yalnız superadmin görür; kurulumun durumunu tek ekranda özetler. Üstte toplamlar yer alır: görev (açık ve biten), pano (arşivdekiler ayrıca), kullanıcı (koltuk sınırıyla), doküman sayfası, yorum ve ek dosya (toplam boyutuyla). Altında şu an çevrimiçi olanların tamamı (liste kendi içinde kayar), aktiflik (bugün ve bu hafta aktif, hiç görülmemiş, deaktif hesap; e-posta yapılandırılmışsa doğrulanmamış e-posta) ve sistem bilgisi (sürüm, yapı, veri, e-posta ve depolama sürücüsü) gelir.

Zamanlanmış işler tablosu her iş için zamanlamayı, son çalışmayı, sonucu, süreyi ve sonraki çalışmayı gösterir. Sonuç "Başarılı", "Hata", "Gecikti" ya da "Çalışmadı" olur ve altında işin sayaçları (örneğin kaç bildirim gönderildiği) ya da hata mesajı yazar. Son çalışması 26 saatten eski iş "Gecikti", hiç çalışmamış iş "Çalışmadı" olarak işaretlenir; hiçbir iş çalışmamışsa tablonun üstünde ayrıca bir uyarı çıkar. Saatler sunucu saatidir, çünkü cron ana makinenin saat diliminde çalışır. Gece yedeği de bu tabloda "Yedekleme" satırıyla yer alır (bkz. Yedekleme & yükseltme).

app.themyway.app/settings/health

Aynı ekrandaki Uygulama günlüğü kartı, uygulamanın ürettiği uyarı ve hata kayıtlarını listeler; bilgi ve ayrıntı (debug) seviyesindeki satırlar burada tutulmaz, yalnız konteyner logunda kalır. Kayıtlar veritabanında 30 gün saklanır: konteyner logunun aksine yeniden başlatma ve güncellemeden etkilenmez, böylece güncellemeden önce yaşanan bir hata da sonradan bulunur. Liste seviyeye (Tüm seviyeler, Hata, Uyarı) ve tarih-saat aralığına (Başlangıç, Bitiş; bitiş dakikası dahildir, "Tarihi temizle" aralığı kaldırır) göre süzülür; arama kutusu mesajda geçen bir metni ya da bir başvuru kodunun tamamını kabul eder. "Filtrelenenleri dışa aktar" yalnız seviye, metin ve tarih süzgecine uyan kayıtları JSON dosyası olarak indirir (en fazla 5000); destek paketi bundan bağımsızdır ve eksiksizdir. Her satırda zaman, seviye, mesaj ve başvuru kodu görünür; ayrıntısı olan satıra tıklayınca hatanın bağlamı açılır: isteğin yöntemi ve geldiği yol (örneğin PATCH /api/tasks/…, sorgu dizgisi alınmaz). Ayrıntıdaki kullanıcı kimliklerinin yanında kişinin adı yazar. Beklenmeyen veritabanı hatalarında hata kodu, ilgili kısıt, tablo, kolon ve sorgu değerleri de görünür, böylece hatanın hangi kayıtta çıktığı anlaşılır; parola özeti, token ve şifreli anahtar gibi değerler maskeli kalır. Liste 50 kayıtlık sayfalarla gelir, devamı "Daha eski kayıtlar" ile yüklenir.

Kayıt yazılmadan önce adı parola, gizli anahtar, belirteç (token), çerez, Authorization başlığı ya da lisans anahtarı olduğunu söyleyen alanların değeri [redacted] ile değiştirilir; sır taşıyan kolonlara (parola özeti, token, şifreli anahtar) giden sorgu değerleri ve sır biçimindeki değerler maskelenir. Destek paketinde sorgu parametreleri tümden kesilir. Döngüye giren bir hatanın tabloyu doldurmaması için dakikada 30, günde 5000 kayıt sınırı vardır: sınırı aşan kayıtlar tabloya yazılmaz, yerlerine kaç kaydın bastırıldığını bildiren tek bir uyarı satırı düşer. Konteyner logunda ise her satır yine yer alır.

Kartın üstündeki "Destek paketi indir" düğmesi, uygulamanın kendi gördüğü tanı bilgisini tek bir JSON dosyası olarak indirir (myway-support-<tarih-saat>.json). Dosyada sürüm ve yapı bilgisi, veri, e-posta ve depolama sürücüleri, zamanlanmış işlerin durumu, lisans durumu, toplamlar, çevrimiçi kullanıcıların yalnız sayısı, zararsız birkaç ayarın değeri, diğer ayarların ise yalnız dolu olup olmadığı ve son 7 günün uygulama günlüğü (en fazla 1000 kayıt) bulunur. Kişi adları, sorgu değerleri ile parola ve anahtar değerleri dosyaya girmez. Ters vekil ve veritabanı logları ile konteynerlerin durumu bu dosyada yoktur; onlar için aşağıdaki destek paketi betiğini kullanın (bkz. Loglar ve destek).

app.themyway.app/settings/health

Loglar ve destek

Bir hatanın izini sürmek için iki kaynak vardır: uygulamanın içindeki Uygulama günlüğü ve sunucudaki konteyner logları. Hangisine bakacağınız, kaydın ne kadar eski olduğuna ve sorunun nerede yaşandığına bağlıdır.

Kullanıcı beklenmeyen bir sunucu hatasıyla karşılaştığında hata mesajının sonunda bir başvuru kodu görür, örneğin "(Başvuru kodu: 7f3a9c2b1e04)". Kod her isteğe ayrı verilen 12 karakterlik bir kimliktir ve o isteğin log satırlarına yazılır. Kullanıcının kodu yöneticiye iletmesi yeterlidir: superadmin kodu Ayarlar > Sağlık’taki Uygulama günlüğü kartının arama kutusuna yapıştırır ve o isteğin kaydını ayrıntısıyla bulur. Aynı kod konteyner logunda da aranabilir. Bizden destek isterken de bu kodu iletin.

# başvuru koduyla konteyner logunda arama / find a reference code in the container log
docker compose -f docker-compose.onprem.yml --env-file .env.onprem logs app | grep 7f3a9c2b1e04

Uygulama hiç açılmıyorsa ya da sorun ters vekilde, veritabanında veya konteynerlerde ise kurulum dizininde ./scripts/support-bundle.sh betiğini çalıştırın; desteğe göndereceğiniz her şeyi tek dosyada toplar ve uygulama ayakta olmasa da çalışır. Betik varsayılan olarak son 24 saati toplar; --since ile aralık (30m, 72h, 3d gibi), --out ile dosyanın yazılacağı dizin değişir. Sonuç kurulum dizinindeki support/ altında myway-support-<tarih-saat>.tar.gz adlı tek dosyadır ve yalnız betiği çalıştıran kullanıcı okuyabilir. Bu dosyayı destek talebinize ekleyin.

./scripts/support-bundle.sh               # son 24 saat / last 24 hours
./scripts/support-bundle.sh --since 72h   # daha geniş aralık / a wider window
./scripts/support-bundle.sh --out /tmp    # başka bir dizine yaz / write elsewhere

• Tarih, sunucu, kurulu sürüm, Docker ve Compose sürümleri
• Konteynerlerin durumu ve, uygulama ayaktaysa, sağlık ucunun yanıtı
• Disk kullanımı ve Docker’ın disk kullanımı
• .env.onprem ayarlarından hangilerinin dolu olduğu: değer yalnız adres, port, sertifika modu, imaj sürümü, sürücüler, SMTP sunucusu ve portu, log seviyesi, yükleme sınırı gibi zararsız ayarlar için yazılır, diğerleri yalnız "<set>" ya da "<empty>" olarak geçer
• Crontab’daki MyWay bloğu (zamanlanmış işler)
• Tüm servislerin (app, caddy, postgres, migrate ve diğerleri) seçilen aralıktaki konteyner logları
• logs/cron.log ve logs/backup.log dosyalarının son 2000 satırı

Ürünle gelen ters vekil (Caddy) her HTTP isteğini; hangi istemcinin hangi adrese ne zaman istek yaptığını ve dönen durum kodunu JSON satırı olarak kendi konteyner loguna yazar. Oturum çerezi ve Authorization başlığı kayda açık yazılmaz. Davet, parola sıfırlama ve e-posta doğrulama bağlantılarının adresindeki tek kullanımlık anahtar kayıtta [redacted] olarak görünür; logu okuyan biri bu bağlantıları yeniden kullanamaz.

Konteyner logları boyut sınırıyla döndürülür ve aylarca açık kalan bir kurulumda diski doldurmaz: app, caddy ve postgres için konteyner başına en fazla 5 dosya, her biri 10 MB; sınır dolunca en eski dosya silinir. Tek seferlik servislerde (migrate, volume-init) sınır yoktur, logları birkaç satırdır. docker compose ... logs her zamanki gibi çalışır.

Ayrıntı seviyesi .env.onprem dosyasındaki LOG_LEVEL ile değişir: debug, info, warn ya da error; varsayılan info. Destek ekibi istediğinde geçici olarak debug yapın, sorun çözülünce geri alın: debug çok ayrıntılıdır ve logların daha hızlı dönmesine yol açar. Değişiklik env okunduğu için konteynerin yeniden oluşturulmasını ister, restart yetmez. Seviyeyi error yaparsanız uyarılar Uygulama günlüğü’ne de düşmez.

# .env.onprem
LOG_LEVEL=debug

# ardından / then
docker compose -f docker-compose.onprem.yml --env-file .env.onprem up -d

Logları kendi SIEM sisteminize göndermek için kurulum dizinine bir docker-compose.override.yml dosyası koyun ve app, caddy ve postgres servislerinin Docker log sürücüsünü (örneğin syslog, gelf ya da fluentd) orada değiştirin. Uygulama ve Caddy logları satır başına bir JSON nesnesidir, ek ayrıştırıcı gerekmez. Paket bu dosyayı içermez, bu yüzden güncellemede üzerine yazılmaz. Kurulum, yedek ve geri yükleme betikleri ile destek paketi betiği dosya varsa onu kendiliğinden kullanır; güncellemede ayarınız kaybolmaz. Docker, compose dosyası -f ile verildiğinde override dosyasını kendiliğinden okumadığından, elle yazdığınız compose komutlarında iki dosyayı birlikte verin:

docker compose -f docker-compose.onprem.yml -f docker-compose.override.yml --env-file .env.onprem up -d