Installing ElasticSearch on AlmaLinux for XenForo — With Troubleshooting Not

[Aior]

Bu Rehbere Genel Bakış​

XenForo'da büyüyen topluluk arama performansını dramatik olarak yavaşlatır. ElasticSearch tabanlı Enhanced Search eklentisi cümle düzeyinde alakalı, milisaniyelik sonuçlar verir. Bu rehber AlmaLinux 8/9 üzerinde tipik kurulum akışını ve gerçek dünyada karşılaşılan sorun-çözüm adımlarını paylaşır.

Sunucu Hazırlığı​

SSH ile root olarak bağlanın ve sistemin güncel olduğundan emin olun:

sudo dnf update -y

ElasticSearch Java 17+ gerektirir; AlmaLinux 9'da varsayılan olarak gelir, AlmaLinux 8'de elle kurmak gerekebilir:

sudo dnf install java-17-openjdk-headless -y

Repository ve Kurulum​

Elastic.co'nun resmi repo'sunu ekleyin:

rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch

cat > /etc/yum.repos.d/elasticsearch.repo <<'EOF'
[elasticsearch]
name=Elasticsearch repository for 8.x packages
baseurl=https://artifacts.elastic.co/packages/8.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=0
EOF

sudo dnf install --enablerepo=elasticsearch elasticsearch -y

Kurulum çıktısındaki elastic kullanıcı şifresini ve sertifika parmak izini not edin.

Kernel Ayarları​

ElasticSearch vm.max_map_count değerinin yüksek olmasını gerektirir; varsayılan 65536 yetmez:

echo "vm.max_map_count=262144" >> /etc/sysctl.conf
sysctl -p

Bu ayar yapılmadan ElasticSearch başlatılamaz veya rastgele çöker. AIOR olarak müşterilerimizde bu kontrolü kurulum scriptimize dahil ediyoruz.

Servisi Başlatma​

sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch
sudo systemctl status elasticsearch

Durum "active (running)" göstermelidir. İlk başlangıçta JVM ısınması 30-60 saniye sürebilir; sabırlı olun.

Bağlantı Testi​

curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200

Şifreyi girip JSON cluster bilgisi gördüğünüzde kurulum tamamdır.

Yaygın Sorunlar ve Çözümler​

Sorun 1: "max virtual memory areas vm.max_map_count [65530] is too low": kernel parametresini güncelleyin (yukarıdaki adım). Sysctl'i unutmayın.

Sorun 2: ElasticSearch başlamıyor, log'da "JNI error": Java sürümü yanlış. systemctl edit elasticsearch ile Environment=ES_JAVA_HOME=/usr/lib/jvm/java-17-openjdk satırını ekleyin.

Sorun 3: "Port 9200 already in use": başka bir ElasticSearch instance veya farklı uygulama portu tutuyor. ss -tlnp | grep 9200 ile kontrol edin.

Sorun 4: XenForo'dan SSL hatası: sertifika parmak izini doğru kopyaladığınızı doğrulayın; /etc/elasticsearch/certs/http_ca.crt dosyasından SHA-256 parmak izini alabilirsiniz: openssl x509 -fingerprint -sha256 -noout -in http_ca.crt

Sorun 5: Heap yetersizliği uyarısı: /etc/elasticsearch/jvm.options.d/heap.options dosyasında -Xms2g / -Xmx2g olarak ayarlayın; toplam RAM'in yarısından fazla yapmayın.

Güvenlik İyileştirmesi​

elasticsearch.yml dosyasında network.host: 127.0.0.1 olarak ayarlayın. XenForo aynı sunucuda ise localhost yeterlidir; farklı sunucuda ise SSH tunnel kullanın. Asla doğrudan 9200'ü internete açmayın.

Index Yenileme​

XenForo Admin > Tools > Rebuild caches > Rebuild search index ile mevcut tüm konuları yeniden indeksleyin. Büyük forumlarda bu işlem saatler sürebilir; bir CLI alternatifi:

php cmd.php xf-rebuild:search

AIOR Hosting'in XenForo paketlerinde ElasticSearch kurulumu, performans tuning'i ve aylık sürüm güncellemeleri pakete dahildir.

Overview​

On a growing XenForo community, search performance degrades dramatically. The Enhanced Search add-on backed by ElasticSearch delivers millisecond-class, sentence-level results. This guide walks through a typical install on AlmaLinux 8/9 and the real-world troubleshooting steps you'll likely hit.

Server Preparation​

SSH in as root and bring the system up to date:

sudo dnf update -y

ElasticSearch requires Java 17+; AlmaLinux 9 ships it by default, AlmaLinux 8 may need a manual install:

sudo dnf install java-17-openjdk-headless -y

Repository and Installation​

Add Elastic.co's official repo:

rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch

cat > /etc/yum.repos.d/elasticsearch.repo <<'EOF'
[elasticsearch]
name=Elasticsearch repository for 8.x packages
baseurl=https://artifacts.elastic.co/packages/8.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=0
EOF

sudo dnf install --enablerepo=elasticsearch elasticsearch -y

Note the elastic user password and certificate fingerprint printed by the installer.

Kernel Tuning​

ElasticSearch needs a much higher vm.max_map_count than the default 65536:

echo "vm.max_map_count=262144" >> /etc/sysctl.conf
sysctl -p

Without this, ElasticSearch may refuse to start or crash randomly. At AIOR we include this check in our install scripts.

Starting the Service​

sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch
sudo systemctl status elasticsearch

Status should read "active (running)". First boot has a 30-60 second JVM warm-up — be patient.

Connection Test​

curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200

When you enter the password and see JSON cluster info, you're done.

Common Issues and Fixes​

Issue 1: "max virtual memory areas vm.max_map_count [65530] is too low": update the kernel parameter (above). Don't forget sysctl -p.

Issue 2: ElasticSearch won't start, log says "JNI error": wrong Java version. Edit the service with systemctl edit elasticsearch and add Environment=ES_JAVA_HOME=/usr/lib/jvm/java-17-openjdk.

Issue 3: "Port 9200 already in use": another ElasticSearch or app holds the port. Check with ss -tlnp | grep 9200.

Issue 4: XenForo reports SSL error: verify the certificate fingerprint was copied correctly; you can compute it from /etc/elasticsearch/certs/http_ca.crt with openssl x509 -fingerprint -sha256 -noout -in http_ca.crt.

Issue 5: Heap warnings: set -Xms2g / -Xmx2g in /etc/elasticsearch/jvm.options.d/heap.options; never exceed half of total RAM.

Security Hardening​

In elasticsearch.yml set network.host: 127.0.0.1. If XenForo runs on the same server, localhost suffices; for a separate server, tunnel over SSH. Never expose 9200 to the public internet.

Index Rebuild​

Use XenForo Admin > Tools > Rebuild caches > Rebuild search index to reindex existing content. On large forums this can take hours; CLI alternative:

php cmd.php xf-rebuild:search

AIOR Hosting's XenForo packages include ElasticSearch installation, performance tuning and monthly version upgrades.