CasaOS sunucuya nasıl kurulur ve paneli nasıl gizli tutulur

CasaOS, Docker üzerine kurulu açık kaynaklı bir kişisel bulut panelidir. Dosya yöneticisi, sistem bileşenleri ve Jellyfin, Nextcloud veya Home Assistant gibi self-hosted uygulamaları tek tıkla kuran bir uygulama mağazası içeren bir web arayüzü sunar. IceWhale tarafından geliştirilmiştir ve özel bir ağdaki tek kartlı bilgisayarlar ile mini PC'ler gibi küçük ev cihazları için tasarlanmıştır.

Kiralık bir sunucu ise ev ağı değildir. CasaOS paneli düz HTTP konuşur, yönetici hesabını paneli ilk açan kişi oluşturur ve uygulama mağazasındaki uygulamalar portlarını sunucunun tüm adreslerinde yayınlar. Bu rehber CasaOS'u Debian 12'ye, çalıştırmadan önce indirip okuyacağınız resmi kurulum betiğiyle kurar. Ardından Docker'ın uygulama portlarını yalnızca localhost'ta yayınlamasını sağlar, paneli SSH tüneli, WireGuard veya HTTPS'li Caddy ile gizli tutar ve CasaOS'u nasıl yedekleyeceğinizi, güncelleyeceğinizi ve kaldıracağınızı gösterir.

Adım 1 — Kurulumdan önce güvenlik duvarını kapatın

CasaOS yönetici hesabını panelin ilk ziyaretinde oluşturur. Siz açmadan önce panel internetten erişilebilir durumdaysa, onu ilk bulan kişi hesabı sahiplenebilir. CasaOS gateway sıradan bir sunucu servisi olarak çalıştığından ufw onun portunu filtreler. Yalnızca SSH'ye izin verin ve güvenlik duvarını açın:

sudo apt update
sudo apt install ufw
sudo ufw default deny incoming
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

Durum çıktısında izin verilen olarak yalnızca OpenSSH (ve IPv6 karşılığı) görünmelidir.

Adım 2 — Docker'ın uygulama portlarını yalnızca localhost'ta yayınlamasını sağlayın

Uygulama mağazasındaki uygulamalar, portlarını ana makine adresi belirtmeden yayınlayan Docker Compose projeleridir. Örneğin CasaOS Jellyfin uygulaması 8097 portunu tüm adreslerde yayınlar. Docker yayınlanan portları ufw kurallarını değerlendirmeden önce yönlendirdiği için bu portlar ufw açıkken bile internete açık olur.

Docker, yayınlanan portları bağladığı varsayılan adresi değiştirebilir. ip anahtarı varsayılan bridge ağını, default-network-opts ise Compose'un her uygulama için oluşturduğu ağları kapsar. İkisini de Docker rehberindeki log döndürme ayarlarıyla birlikte /etc/docker/daemon.json dosyasına yazın:

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "local",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "ip": "127.0.0.1",
  "default-network-opts": {
    "bridge": {
      "com.docker.network.bridge.host_binding_ipv4": "127.0.0.1"
    }
  }
}
EOF
sudo systemctl restart docker

Ayarı yeni bir ağdaki geçici bir konteynerle test edin:

docker network create probe-net
docker run -d --rm --name probe --network probe-net -p 9999:80 nginx:stable
sudo ss -tlnp | grep 9999
docker rm -f probe && docker network rm probe-net

ss satırı 0.0.0.0:9999 değil, 127.0.0.1:9999 göstermelidir. Ayar bundan sonra oluşturulan ağlara uygulanır; bu yüzden herhangi bir uygulama kurmadan önce yapılır.

Adım 3 — Resmi kurulum betiğini indirin, inceleyin ve çalıştırın

Resmi tek satırlık kurulum curl -fsSL https://get.casaos.io | sudo bash komutudur. Okuyabilmek için betiği önce indirin:

cd ~
curl -fsSL https://get.casaos.io -o casaos-install.sh
less casaos-install.sh
sudo bash casaos-install.sh

Bu rehber yazılırken betik (kurulum betiği v0.4.16) şunları yapar:

• CPU mimarisini ve dağıtımı kontrol eder, 400 MB'ın altındaki RAM'de durur ve 5 GB'tan az boş disk alanı varsa devam etmeden önce sorar;
• yardımcı paketleri kurar: wget, curl, smartmontools, parted, ntfs-3g, net-tools, udevil, samba, cifs-utils, mergerfs ve unzip;
• mevcut Docker'ınızı (sürüm 20 veya daha yeni) kullanır, Docker yoksa Docker'ın kolaylık betiğiyle kurar, ardından Docker'ın en düşük API sürümü için bir systemd override ekler;
• rclone'u kurar, ardından CasaOS bileşenlerini (gateway, message bus, user service, local storage, app management, arayüz, CLI ve uygulama mağazası) GitHub sürümlerinden indirip sisteme kopyalar;
• casaos-uninstall komutunu kurar, CasaOS servislerini başlatır ve panel adresini yazdırır.

Betik bitince sürümü ve servisleri kontrol edin:

casaos -v
systemctl status casaos-gateway casaos --no-pager
sudo ss -tlnp | grep -E "casaos|smbd"

Gateway, boşsa 80 numaralı portta dinler. 80 doluysa önce 81-89, sonra 8080-8089 aralığındaki ilk boş portu seçer ve seçimini /etc/casaos/gateway.ini dosyasına kaydeder.

Adım 4 — Yönetici hesabını SSH tüneli üzerinden oluşturun

Paneli genel adres yerine şifreli bir SSH tüneli üzerinden açın. Bu komutu kullanıcı adını ve IP'yi değiştirerek kendi bilgisayarınızda çalıştırın:

ssh -L 8080:127.0.0.1:80 admin@203.0.113.10

Oturumu açık tutun ve tarayıcıda http://localhost:8080 adresine gidin. CasaOS sizden bir hesap oluşturmanızı ister: bir kullanıcı adı ve tercihen bir parola yöneticisinden alınmış uzun, benzersiz bir parola seçin. Ardından bileşenleri, dosya yöneticisi ve App Store ile panel açılır.

Adım 5 — Panele nasıl erişeceğinizi seçin

CasaOS'u sunucu dışından kullanmak için üç yoldan birini seçin:

Seçenek A — Yalnızca SSH tüneli

Adım 4'teki komutu kullanmaya devam edin. Başka hiçbir şey açılmaz ve ufw 80 numaralı portu kapalı tutar.

Seçenek B — WireGuard

WireGuard'ı WireGuard VPN sunucusu nasıl kurulur rehberiyle kurun, ardından panel portuna yalnızca VPN arayüzünde izin verin:

sudo ufw allow in on wg0 to any port 80 proto tcp

Bağlı VPN istemcileri tarayıcıda sunucunun WireGuard adresini açar; örneğin http://10.8.0.1. Genel arayüz kapalı kalır.

Seçenek C — HTTPS'li Caddy ve IP izin listesi

Caddy 80 ve 443 numaralı portlara ihtiyaç duyar; bu yüzden önce CasaOS gateway'ini başka bir porta, örneğin 8088'e taşıyın:

sudo sed -i 's/^port=.*/port=8088/' /etc/casaos/gateway.ini
sudo systemctl restart casaos-gateway
sudo ss -tlnp | grep 8088

Caddy'yi Caddy reverse proxy olarak nasıl kurulur rehberiyle kurun ve ufw'de 80/tcp ile 443/tcp portlarına izin verin. 8088 numaralı porta izin vermeyin; Caddy ona localhost üzerinden ulaşır. /etc/caddy/Caddyfile dosyasına yalnızca kendi IP adresinize (burada 198.51.100.7) yanıt veren bir site bloğu ekleyin:

casa.example.com {
    @denied not remote_ip 198.51.100.7
    abort @denied
    reverse_proxy 127.0.0.1:8088
}

Caddy'yi yeniden yükleyin ve kendi bilgisayarınızdan test edin:

sudo systemctl reload caddy
curl -I https://casa.example.com

İzin verdiğiniz IP'den HTTP 200 yanıtı almalısınız; diğer adreslerden bağlantı kapatılır. Adım 4'teki SSH tünelini 8088 numaralı porta göre güncellemeyi unutmayın. IP adresiniz sık değişiyorsa izin listesi yerine WireGuard kullanın.

Adım 6 — Uygulamaları kurun ve onlara güvenle erişin

Panelde App Store'u açın ve bir uygulama kurun. Adım 2 sayesinde portları artık yalnızca localhost'ta dinler; şöyle kontrol edin:

sudo ss -tlnp | grep docker-proxy

Her satır 127.0.0.1 ile başlamalıdır. Uygulama verileri /DATA/AppData/ altında uygulama adıyla, uygulama tanımları ise /var/lib/casaos/apps altında durur.

Paneldeki uygulama simgeleri http://sunucu-ip-adresiniz:port adresine bağlanır ve bu adres artık dışarıdan yanıt vermez. Bir uygulamaya şu yollardan biriyle erişin: portunu SSH tünelinize ekleyin (örneğin -L 8097:127.0.0.1:8097) ya da ona kendi Caddy site bloğunu verin; Jellyfin uygulaması için örnek:

media.example.com {
    reverse_proxy 127.0.0.1:8097
}

Yedekleme ve geri yükleme

CasaOS durumunu üç yerde tutar:

• /DATA: uygulama verileri (/DATA/AppData), medya ve panelde yönettiğiniz dosyalar,
• /var/lib/casaos: uygulama tanımları, uygulama mağazası önbelleği ve CasaOS veritabanları,
• /etc/casaos: gateway.ini gibi yapılandırma dosyaları.

Uygulamaların içindeki veritabanları tutarlı olsun diye çalışan konteynerleri durdurun, üç klasörü arşivleyin, ardından aynı konteynerleri yeniden başlatın:

sudo mkdir -p /opt/backups
RUNNING=$(docker ps -q)
docker stop $RUNNING
sudo tar czf /opt/backups/casaos-$(date +%F).tar.gz /DATA /var/lib/casaos /etc/casaos
docker start $RUNNING

Arşivi sunucunun dışına kopyalayın; örneğin rsync ile başka bir makineye:

rsync -avP admin@203.0.113.10:/opt/backups/ ~/casaos-backups/

Geri yüklemek için hedef sunucuya Docker'ı, Adım 2'deki daemon.json dosyasını ve aynı CasaOS sürümünü kurun. Ardından CasaOS'u durdurun, arşivi açın ve servisleri yeniden başlatın:

sudo systemctl stop casaos casaos-app-management casaos-local-storage casaos-user-service casaos-message-bus casaos-gateway
sudo tar xzf /opt/backups/casaos-2026-10-09.tar.gz -C /
sudo systemctl start casaos-gateway casaos-message-bus casaos-user-service casaos-local-storage casaos-app-management casaos

Yeni bir sunucuda bir uygulama başlamazsa onu App Store'dan aynı ayarlarla yeniden kurun; /DATA/AppData altında bulduğu verileri kullanır.

CasaOS güncelleme

Önce yedek alın. Paneldeki Settings bölümünden ya da komut satırından güncelleyebilirsiniz. Proje, komut satırı güncellemesini CasaOS panelinin içindeki terminalden değil, SSH veya yerel konsol üzerinden çalıştırmanızı ister. Güncelleme betiğini kurulum betiği gibi indirip inceleyin:

curl -fsSL https://get.casaos.io/update -o casaos-update.sh
less casaos-update.sh
sudo bash casaos-update.sh
casaos -v

CasaOS kurulu uygulamaları kendiliğinden güncellemez. Her uygulamayı sürüm notlarını okuduktan sonra panelden güncelleyin. Docker'ın kendisi, Docker rehberinde anlatıldığı gibi apt üzerinden güncellenir.

CasaOS'u kaldırma

Kurulum betiği bir kaldırma komutu ekledi. Komut tüm konteynerlerin, imajların ve /DATA/AppData içindeki uygulama verilerinin silinip silinmeyeceğini sorar; saklamak için n yanıtını verin. /etc/casaos klasörünü ve CasaOS servislerini kaldırır, Docker'ı ise kurulu bırakır.

sudo casaos-uninstall

Sorun giderme

Panel 80 numaralı portta değil

Gateway 80 numaralı portu dolu buldu ve başka bir port seçti. Portu görmek için grep port /etc/casaos/gateway.ini ve sudo ss -tlnp | grep casaos komutlarını çalıştırın; ardından tünelinizi veya Caddy bloğunuzu buna göre ayarlayın ya da portu Seçenek C'deki gibi kendiniz belirleyin.

ufw açık olduğu hâlde bir uygulamaya internetten erişilebiliyor

Uygulama daemon.json değişikliğinden önce kuruldu ya da ağı zaten vardı. sudo ss -tlnp | grep docker-proxy ile kontrol edin. Uygulamayı panelden kaldırın (verilerini saklayın), Adım 2'nin uygulandığından emin olun ve uygulamayı yeniden kurun.

Recommended minimum Docker version

Docker 20'den eski olduğu için kurulum betiği durdu. Eski paketleri kaldırın, Docker'ı Docker rehberinde anlatıldığı gibi Docker'ın deposundan kurun ve kurulum betiğini yeniden çalıştırın.

Kurulumdan sonra Docker başlamıyor

systemctl status docker ve journalctl -u docker -n 50 çıktılarına bakın. /etc/docker/daemon.json içindeki bir yazım hatası servisi durdurur; dosyayı python3 -m json.tool /etc/docker/daemon.json ile doğrulayın, düzeltin ve sudo systemctl restart docker çalıştırın.

Bir uygulama simgesi hiç yüklenmeyen bir sayfa açıyor

Uygulama, amaçlandığı gibi 127.0.0.1 üzerinde dinliyor. Onu SSH tüneliniz, WireGuard ile Caddy ya da Adım 6'daki gibi kendi Caddy site bloğu üzerinden açın.

Sonraki adımlar

• Panele tüm cihazlarınızdan WireGuard VPN sunucusu ile erişin.
• HTTPS ve site blokları hakkında daha fazlasını Caddy reverse proxy olarak nasıl kurulur rehberinde öğrenin.
• Konteynerleri Portainer ile daha ayrıntılı yönetin.
• Self-hosted bir panel için sunucuları CasaOS hosting sayfasında karşılaştırın.
• Projeyi GitHub üzerinden takip edin.