On-Premise Kurulum

Labelixa'yı kendi sunucunuzda çalıştırma: ortam değişkenleri, Docker dağıtımı, özel font tanımlama ve stateless mimari.

Render servisi bilinçli olarak durumsuzdur (stateless): gelen ZPL diske yazılmaz, loglanmaz. Bu, KVKK/GDPR açısından önemlidir ve yatay ölçeklemeyi kolaylaştırır — işçi ya da sunucu sayısını artırmak yeterlidir.

Ortam değişkenleri

Docker ile çalıştırma

Depo kök dizinindeki Dockerfile tek imaj üretir:

docker build -t labelixa .
docker run -p 8000:8000 \
  -e LABELIXA_DB=/data/labelixa.db \
  -e LABELIXA_FONT=/fonts/OzelFont.ttf \
  -v $PWD/data:/data -v $PWD/fonts:/fonts labelixa

Kalıcılık: yukarıdaki -v hacimleri ŞART. Verilmezse veritabanı konteyner içinde kalır ve her yeniden başlatmada hesaplar ile kullanım geçmişi kaybolur. Uygulama bunu açılışta uyarı olarak yazar ve /health içindeki kalicilik alanından okunur; LABELIXA_KALICILIK_ZORUNLU=1 ile uyarı yerine ret davranışı açılır (yanlış kurulum sessizce çalışmaz).

Compose ile tam yığın (önerilen)

Depo kökündeki docker-compose.yml web + worker + PostgreSQL'i kalıcı hacimlerle ve kalıcılık zorunluluğu açık olarak getirir. Ayrı kuyruk broker'ı ya da object storage GEREKMEZ: kuyruk veritabanında yaşar, asset deposu yerel dosya sistemidir.

cp .env.onprem.example .env   # sirlari doldurun
docker compose up -d --build
docker compose logs -f web

Uzun toplu işler ayrı worker servisinde koşar, böylece API'nin yanıt süresini etkilemez. Worker SIGTERM aldığında koşan adımı tamamlayıp çıkar.

Yönetim aracı (dış servis gerektirmez)

Panel girişi Google ya da e-posta ile açılır; ikisi de yoksa (air-gapped kurulum) ilk API anahtarını komut satırından üretirsiniz:

docker compose exec web python -m yonetim hesap-ac operator@sirket.local --plan enterprise
docker compose exec web python -m yonetim durum
docker compose exec web python -m yonetim hesap-listele

Anahtar yalnızca üretildiği anda gösterilir; listeleme komutu anahtarları maskeler. Kaybederseniz anahtar-yenile ile yenisini üretirsiniz — eski anahtar o anda geçersiz olur.

E-posta gönderimi için bulut sağlayıcısı gerekmez: LABELIXA_MAIL=smtp ile kurum içi SMTP sunucunuzu kullanabilirsiniz (ek paket kurulmaz).

Operatör rehberi

Bu sayfa ürünün on-prem tarafını anlatır. Kurulumu ayakta tutan kişi için ayrı ve daha ayrıntılı bir belge var: depodaki docs/on-prem-kurulum.md — sertleştirme kontrol listesi, yükseltme sırası, yedekleme/geri yükleme provası, izleme alarmları ve sorun giderme tablosu. Sertleştirme maddelerinin her birinin ölçülmüş bir gerekçesi yazılıdır; "neden"i olmayan madde ilk yükseltmede atlanır.

Loglama ve metrikler

LOG_JSON=1 satır başına tek JSON nesnesi yazar; LOG_LEVEL ile düzey imaj değiştirmeden ayarlanır (DEBUG|INFO|WARNING|ERROR). Kişisel veri redaksiyonu biçimden bağımsızdır ve her zaman açıktır: e-posta adresleri ve bilinen sır desenleri maskelenir.

METRICS_TOKEN tanımlarsanız Prometheus uyumlu GET /metrics ucu açılır; tanımlı değilse uç kapalıdır (404). Jeton MAINTENANCE_TOKEN'dan ayrıdır — izleme sisteminin yapılandırması genelde geniş okunur ve aynı jetonla bakım uçlarına erişilebilmesi yetki genişlemesi olurdu.

curl -H "Authorization: Bearer $METRICS_TOKEN" \
     https://etiket.sirket.local/metrics

Metriklerde kişisel veri yoktur: e-posta, IP, hesap kimliği ve ZPL içeriği dışa aktarılmaz; etiket değerleri yalnız sabit kümelerden gelir (plan, işlem türü, çıktı biçimi, iş durumu). En çok işe yarayan seriler: labelixa_kuyruk_is_sayisi (worker ölürse bekliyor sürekli artar), labelixa_sema_bekleyen_goc (yükseltme yarım kaldı) ve labelixa_bilesen_saglikli.

Ters vekil ve TLS

Uygulama TLS'i kendi sonlandırmaz; önüne bir ters vekil koyulur. Depodaki deploy/Caddyfile ile Compose'un tls profili sertifikayı ACME üzerinden kendi alır ve yeniler:

LABELIXA_DOMAIN=etiket.sirket.local \
  docker compose --profile tls up -d

Kurumunuzda zaten nginx varsa deploy/nginx.conf eşdeğerdir; sertifikayı siz sağlarsınız.

Vekil yapılandırmasının en kritik satırları başlık satırlarıdır. Uygulama istemci kimliğini — hız sınırı ve ücretsiz kota bu kimliğe bağlıdır — CF-Connecting-IP ve X-Forwarded-For başlıklarından çıkarır. İstemci bu başlıkları yazabiliyorsa her istekte yeni bir kimlik uydurur ve hız sınırı fiilen YOKTUR. Ölçüm: sahte başlıkla 12 isteğin 12'si geçti, sabit kimlikte 9'u 429 aldı.

Korumanın iki yarısı vardır ve ikisi de gerekir:

• Vekil, gelen kimlik başlıklarını siler ve kendi gördüğü adresi yazar. Cloudflare bunu kendiliğinden yapar; sıradan bir ters vekil yapmaz. Verdiğimiz iki yapılandırma da yapar.
• Uygulamada LABELIXA_VEKIL=genel ayarlanır; böylece CF-Connecting-IP yok sayılır. On-prem Compose yığını bunu zaten ayarlar. Varsayılan cloudflare'dir, çünkü bulut dağıtımı Cloudflare'in arkasındadır.

tls profilini kullanıyorsanız .env içinde WEB_BIND=127.0.0.1 yapın: uygulama portu dışarıya açık kalırsa vekilin sildiği başlıklar o kapıdan içeri girer ve sertleştirme anlamsızlaşır.

Özel font

Fontu birebir eşleştirme

Zebra'nın yerleşik fontları (font 0 = CG Triumvirate Bold Condensed) tescillidir ve ZPL kodunun içinde yer almaz; ZPL yalnızca fontun numarasını, yüksekliğini ve genişliğini taşır. Varsayılan olarak genişlik bakımından en yakın açık font olan Liberation Sans Bold kullanılır.

Çıktının harf kalınlığına kadar birebir olması gerekiyorsa iki yol vardır:

Hangi font? Tahminle değil ölçerek

GET /v1/fonts/kalibrasyon kurulu tüm fontları, gerçek kargo baskılarından alınmış 6 kısıta karşı puanlar: 4 alan çakışma sınırı ve 2 metin bloğu sarma noktası. En yüksek puanlı fontu seçin.

bash

curl -s https://api.labelixa.com/v1/fonts/kalibrasyon | jq '.en_iyiler[:5]'

Varsayılan sunucuda DejaVuSansCondensed-Bold 6/6 alır. LABELIXA_FONT ile tanımadığımız bir font verirseniz genişlik katsayısı açılışta ölçülerek belirlenir; hazır bir tablo değeri uygulanmaz. Seçilen katsayı ve puan /health çıktısındaki font bölümünde görünür.

bash

# Railway: bir volume'a fontu koyup ortam degiskenini gosterin
railway variables --set LABELIXA_FONT=/data/fonts/OzelFont.ttf

# Docker: fontu imaja veya bind-mount ile verin
docker run -v /opt/fonts:/fonts:ro \
  -e LABELIXA_FONT=/fonts/OzelFont.ttf -p 8000:8000 labelixa

# Dogrulama
curl -s localhost:8000/health | jq .font

• Sunucuya font tanımlamak: lisansladığınız fontu LABELIXA_FONT ile verirsiniz; motor onu tüm metinlerde kullanır. Yol yanlışsa servis sessizce yerleşik fonta düşmez — /health çıktısındaki font.sorun alanı ve durum sayfası uyarır.
• Fontu etikete gömmek: ~DU ile fontu yükleyip ^A@ ile çağırırsınız. Bu durumda çıktı yazıcıya (veya sunucu yapılandırmasına) hiç bağlı olmaz. POST /v1/fonts bir TTF dosyasını hazır ~DU komutuna çevirir; ?chars= ile yalnızca kullandığınız karakterleri alarak dosyayı küçültebilirsiniz.
  Tek adımda yapmak için: önizleme aracındaki Font Göm düğmesi ya da POST /v1/fonts/embed — ZPL'i ve fontu gönderirsiniz, ~DU eklenmiş ve ^A0 alanları ^A@ ile fonta bağlanmış ZPL geri döner. Font otomatik olarak etikette geçen karakterlerle sınırlanır.

~DUR:OZEL.TTF,12345,00010203...
^XA
^A@N,40,40,R:OZEL.TTF
^FO20,20^FDMerhaba^FS
^XZ

Her ZPL'de fontu yeniden yüklemek yerine LABELIXA_FONT ile sunucu düzeyinde bir TrueType font tanımlayabilirsiniz; tüm render'lar bu fontu kullanır. Alternatif olarak POST /v1/fonts ile fontu ZPL'e gömülü hâle getirebilirsiniz; büyük fontlarda ?chars=... ile yalnızca gereken karakterleri gömerek çıktıyı küçültebilirsiniz (alt kümeleme).

Sağlık kontrolü

GET /health bileşen durumunu JSON olarak döndürür; /durum ise insan-okur bir durum sayfasıdır. Yük dengeleyici sağlık yoklaması için /health kullanılabilir.