Vaultwarden, Docker Compose ve HTTPS ile kendi sunucunuzda nasıl kurulur

Vaultwarden, Bitwarden parola yöneticisi için Rust ile yazılmış alternatif bir sunucudur. Bitwarden istemci API'sini uygular, tek ve küçük bir konteynerde çalışır; bilinen Bitwarden tarayıcı eklentileri, masaüstü ve mobil uygulamalarıyla birlikte kullanılabilir. Bu nedenle parola kasasını kendi denetimindeki bir sunucuda tutmak isteyen bireyler, aileler ve küçük ekipler tarafından sıkça tercih edilir. Vaultwarden resmi olmayan bir projedir ve Bitwarden, Inc. ile bağlantısı yoktur.

Bu rehber resmi vaultwarden/server imajını Docker Compose ile çalıştırır, yalnızca 127.0.0.1 üzerinde yayınlar ve web kasasının zorunlu tuttuğu HTTPS için önüne Caddy koyar. Ardından hesabınızı oluşturur, açık kaydı kapatır, yönetici sayfasını Argon2 ile hash'lenmiş bir anahtarla korur ve projenin wiki sayfasına uygun yedekleme ve geri yükleme düzenini kurarsınız. Tekrarlanan hatalı girişlerin fail2ban ile engellenmesi isteğe bağlı bir adım olarak anlatılır.

Adım 1 — Proje klasörünü oluşturun

Bu uygulamaya ait her şeyi yönetici kullanıcınızın sahibi olduğu tek bir klasörde tutun:

sudo mkdir -p /opt/vaultwarden
sudo chown $USER:$USER /opt/vaultwarden
cd /opt/vaultwarden

Kasa verileri, Docker'ın ilk başlatmada oluşturacağı /opt/vaultwarden/vw-data klasöründe durur.

Adım 2 — Hash'lenmiş yönetici anahtarı üretin

Vaultwarden'ın /admin adresinde kullanıcı davet edebileceğiniz, hesapları inceleyebileceğiniz ve ayarları değiştirebileceğiniz bir yönetici sayfası vardır. Bu sayfanın parolası ADMIN_TOKEN değeridir. Wiki, yapılandırmanızı okuyan birinin parolayı öğrenmemesi için bu değerin düz metin yerine Argon2id PHC dizesi olarak saklanmasını önerir.

Önce uzun ve rastgele bir parola üretin ve bunu bu kasanın dışındaki bir parola yöneticisine kaydedin (kasaya erişilemediğinde bu parolaya ihtiyaç duyabilirsiniz):

openssl rand -base64 32

Ardından Vaultwarden'ın yerleşik hash komutunu geçici bir konteynerde çalıştırın. Komut parolayı iki kez sorar ve yalnızca iki giriş eşleşirse hash'i yazdırır:

docker run --rm -it vaultwarden/server:latest /vaultwarden hash

Çıktı ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$ ile başlayan bir satırla biter. Tek tırnakların arasındaki değeri kopyalayın. Varsayılan parametreler Bitwarden'ın kendi ayarlarıyla aynıdır; --preset owasp bunun yerine daha hafif OWASP alt sınırını seçer.

Adım 3 — Ortam ve Compose dosyalarını yazın

Hash'i Compose dosyasının yanındaki bir .env dosyasında saklayın. Wiki'deki gibi değeri tek tırnak içine alın ve her $ işaretini tek bırakın; Compose değeri böylece olduğu gibi okur:

nano .env

VAULTWARDEN_ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$REPLACE_WITH_YOUR_HASH'

chmod 600 .env

Şimdi compose.yaml dosyasını oluşturun. Dosya projenin kendi Compose örneğine dayanır; alan adınız doldurulmuştur ve ilk hesabı oluşturabilmeniz için kayıtlar henüz açıktır:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "true"
      ADMIN_TOKEN: ${VAULTWARDEN_ADMIN_TOKEN}
    volumes:
      - ./vw-data/:/data/
    ports:
      - 127.0.0.1:8000:80

• DOMAIN, kullanıcıların açtığı tam HTTPS adresi olmalıdır; bu değer olmadan bazı özellikler çalışmaz.
• 127.0.0.1:8000:80 konteyneri genel ağın dışında tutar. Ona yalnızca aynı sunucudaki Caddy erişebilir.
• latest etiketi en yeni kararlı sürümü izler; wiki bunu çoğu kullanıcı için önerir. 1.37.4 gibi sürüm etiketleri ve Alpine türevleri (latest-alpine) de vardır.

Başlatmadan önce dosyayı hatalara karşı kontrol edin:

docker compose config --quiet

Çıktı yoksa dosya geçerlidir. The "argon2id" variable is not set gibi bir uyarı, Compose'un $ işaretlerini genişletmeye çalıştığı anlamına gelir; .env dosyasındaki tek tırnakları kontrol edin.

Adım 4 — Vaultwarden'ı başlatın

docker compose up -d
docker compose ps
docker compose logs --tail 20
curl -I http://127.0.0.1:8000

docker compose ps konteyneri çalışıyor olarak gösterir (imajda sağlık denetimi olduğu için kısa süre sonra healthy olur) ve curl komutu HTTP/1.1 200 OK döndürür. Yönetici anahtarının tam istediğiniz gibi, tek $ işaretleriyle ve fazladan tırnak olmadan ulaştığını doğrulayın:

docker compose exec vaultwarden printenv ADMIN_TOKEN

Adım 5 — Vaultwarden'ı Caddy ile HTTPS üzerinden sunun

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. header_up satırı ziyaretçinin gerçek IP adresini Vaultwarden'a iletir; Vaultwarden varsayılan olarak X-Real-IP başlığını okur ve loglar, hız sınırlama ile fail2ban bu bilgiye dayanır:

vault.example.com {
    reverse_proxy 127.0.0.1:8000 {
        header_up X-Real-IP {remote_host}
    }
}

Caddy'yi yeniden yükleyin ve güvenlik duvarının yalnızca SSH ile web trafiğine izin verdiğinden emin olun:

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
curl -I https://vault.example.com

Son komut geçerli bir sertifikayla HTTP/2 200 döndürür. Caddy, Vaultwarden'ın canlı eşitleme bildirimleri için kullandığı WebSocket bağlantısını da ek ayar gerektirmeden iletir. Başka bir proxy tercih ediyorsanız Nginx ve Certbot veya Traefik rehberlerine bakın.

Adım 6 — Hesabınızı oluşturun ve kaydı kapatın

Tarayıcınızda https://vault.example.com adresini açın, Create account seçeneğini kullanın ve güçlü bir ana parola belirleyin. Unutulan ana parolayı ne siz ne de yönetici sayfası kurtarabilir; bu yüzden güvenli bir yerde bir kurtarma kopyası saklayın.

Kendi hesabınız (ve varsa aile veya ekip hesapları) oluşturulur oluşturulmaz başkalarının kaydolmasını engelleyin. compose.yaml içindeki satırı değiştirin:

      SIGNUPS_ALLOWED: "false"

Ardından konteyneri yeniden oluşturun:

docker compose up -d

Giriş sayfasındaki Create account bağlantısı kaybolur. Daha sonra kişi eklemek için yönetici sayfasını açın, Users bölümüne gidin ve Invite User seçeneğini kullanın. SMTP yoksa e-posta gönderilmez; davet edilen kişi https://vault.example.com/#/signup adresinden, davet edilen e-posta adresinin aynısıyla kaydolur. INVITATIONS_ALLOWED varsayılan olarak açık olduğundan organizasyon sahipleri de üye davet edebilir.

Davetleri, e-posta doğrulamasını ve parola ipuçlarını e-postayla göndermek için compose.yaml dosyasının environment bölümüne SMTP_HOST: "smtp.example.com", SMTP_PORT: "587", SMTP_SECURITY: "starttls", SMTP_FROM, SMTP_USERNAME ve SMTP_PASSWORD ekleyin (parolayı yönetici anahtarı gibi .env içinde tutun) ve konteyneri docker compose up -d ile yeniden oluşturun.

Adım 7 — Yönetici sayfasını kullanın ve iki adımlı girişi açın

https://vault.example.com/admin adresini açın ve Adım 2'de hash'lediğiniz parolayla (hash'in kendisiyle değil) giriş yapın. Yönetici oturumları varsayılan olarak 20 dakika sürer.

Ardından kendi hesabınızı koruyun: web kasasında Settings, sonra Security, sonra Two-step login bölümünü açın ve bir doğrulayıcı uygulama ayarlayın. Kurtarma kodunu kasanın dışında bir yerde saklayın.

Bitwarden uygulamalarını ve tarayıcı eklentilerini bağlamak için giriş ekranında self-hosted seçeneğini seçin ve sunucu adresi olarak https://vault.example.com girin.

Yönetici sayfasına nadiren ihtiyaç duyuyorsanız onu kapatabilirsiniz: ADMIN_TOKEN satırını (ve varsa config.json içindeki admin_token girdisini) silin ve konteyneri yeniden oluşturun.

Adım 8 — Tekrarlanan hatalı girişleri fail2ban ile engelleyin (isteğe bağlı)

Vaultwarden hatalı girişleri istemcinin IP adresiyle birlikte loglar. fail2ban bu logu okuyup birkaç hatadan sonra adresi engelleyebilir. Önce compose.yaml dosyasının environment bölümüne bir değişken ekleyerek Vaultwarden'ın veri klasörüne log dosyası yazmasını sağlayın:

      LOG_FILE: "/data/vaultwarden.log"

docker compose up -d
sudo apt install fail2ban

Wiki'deki kalıpla /etc/fail2ban/filter.d/vaultwarden.local filtresini oluşturun:

[INCLUDES]
before = common.conf

[Definition]
failregex = ^.*?Username or password is incorrect\. Try again\. IP: <ADDR>\. Username:.*$
ignoreregex =

/etc/fail2ban/jail.d/vaultwarden.local jail dosyasını oluşturun:

[vaultwarden]
enabled = true
port = 80,443
filter = vaultwarden
banaction = %(banaction_allports)s
logpath = /opt/vaultwarden/vw-data/vaultwarden.log
backend = auto
maxretry = 3
bantime = 14400
findtime = 14400

sudo systemctl restart fail2ban
sudo fail2ban-client status vaultwarden

Caddy sunucunun kendisinde çalıştığı için varsayılan engelleme eylemleri ziyaretçiyi istek Caddy'ye ulaşmadan durdurur. Reverse proxy'niz Docker içinde çalışıyorsa wiki chain = FORWARD değişikliğini açıklar; ayrıca yönetici sayfasındaki hatalı girişler için ikinci bir filtre de verir. Vaultwarden bu log dosyasını kendisi döndürmez; dosya büyürse copytruncate kullanan bir logrotate kuralı ekleyin.

Yedekleme ve geri yükleme

Tüm durum /opt/vaultwarden/vw-data klasöründedir. Wiki önemli olanları şöyle sıralar:

• db.sqlite3: kasa verilerinin neredeyse tamamını içeren veritabanı (zorunlu),
• attachments/: dosya ekleri (zorunlu),
• config.json: yönetici sayfasında kaydedilen ayarlar, düz metin olarak (önerilir),
• rsa_key*: oturum belirteçlerini imzalayan anahtarlar (önerilir),
• sends/: geçici olması amaçlanan Send ekleri (isteğe bağlı),
• icon_cache/: önbelleğe alınmış site simgeleri (gerekmez).

Çalışan bir db.sqlite3 dosyasını tek başına kopyalamayın. Vaultwarden'ın (1.32.1 sürümünden beri) SQLite veritabanının tutarlı bir kopyasını özgün dosyanın yanına yazan yerleşik bir komutu vardır; Docker imajında sqlite3 programı bulunmadığı için bu komutu kullanın:

cd /opt/vaultwarden
docker compose exec vaultwarden /vaultwarden backup

Komut Backup to '/data/db_20261009_031500.sqlite3' was successful benzeri bir satır yazar; konteynerin içindeki /data, sizin vw-data klasörünüzdür. Şimdi bu kopyayı diğer dosyalar ve Compose kurulumunuzla birlikte arşivleyin; çalışan veritabanı dosyalarını ve simge önbelleğini dışarıda bırakın, ardından geçici kopyayı silin:

sudo mkdir -p /opt/backups
sudo tar --exclude='db.sqlite3*' --exclude='icon_cache' -czf /opt/backups/vaultwarden-$(date +%F).tar.gz -C /opt/vaultwarden compose.yaml .env vw-data
sudo rm /opt/vaultwarden/vw-data/db_*.sqlite3

Arşiv gizli bilgiler içerir (yönetici anahtarı hash'i, config.json, RSA anahtarları ve şifreli kasanız). İzinlerini kısıtlayın, yedeği cron veya bir systemd timer ile her gün alın ve sunucunun dışına kopyalayın; örneğin başka bir makinedeki kendi S3 depolamanıza.

Geri yüklemek için Vaultwarden'ı durdurun, arşivi açın ve tarihli veritabanı kopyasını yeniden db.sqlite3 yapın. Wiki, mevcut bir db.sqlite3-wal dosyasının önce silinmesini söyler; aksi hâlde geri yüklenen veritabanı bozulabilir:

cd /opt/vaultwarden
docker compose down
sudo tar -xzf /opt/backups/vaultwarden-2026-10-09.tar.gz -C /opt/vaultwarden
sudo rm -f vw-data/db.sqlite3 vw-data/db.sqlite3-wal vw-data/db.sqlite3-shm
sudo mv vw-data/db_*.sqlite3 vw-data/db.sqlite3
docker compose up -d

Aynı adımlar, Docker ve Caddy'yi kurduktan sonra yeni bir sunucuya geri yükleme için de geçerlidir. Geri yüklemeyi ara sıra deneyin ve geri yüklenen kasanın çalıştığını doğrulayana kadar özgün verileri saklayın.

Vaultwarden güncelleme

Bitwarden uygulamaları kendiliğinden güncellendiği için wiki, sunucunun en son sürümde tutulmasını vurgular. Bazı sürümler eski seçenekleri kaldırdığı veya proxy davranışını değiştirdiği için önce sürüm notlarını okuyun, yedek alın, ardından imajı çekip konteyneri yeniden oluşturun:

cd /opt/vaultwarden
docker compose pull
docker compose up -d
docker compose logs --tail 20
docker image prune

Web kasası sunucu imajının içinde gelir; bu nedenle her zaman sunucu sürümüyle eşleşir.

Sorun giderme

Web kasası HTTP üzerinden hata veriyor veya boş kalıyor

Web kasası, Web Crypto API için güvenli bağlama ihtiyaç duyar. Kasayı http:// veya sunucunun IP adresiyle değil, https://vault.example.com üzerinden açın ve compose.yaml içindeki DOMAIN değerinin aynı HTTPS adresi olduğundan emin olun.

You are using a plain text ADMIN_TOKEN which is insecure

Ya .env hâlâ düz bir parola içeriyor ya da yönetici sayfasında kaydedilen bir değer onu geçersiz kılıyor. Wiki'nin önerdiği gibi iki yeri de kontrol edin: docker compose exec vaultwarden printenv ADMIN_TOKEN ve sudo grep admin_token vw-data/config.json. Çıktı, tek $ işaretli ve fazladan tırnak içermeyen $argon2id$ dizesi olmalıdır.

WARNING: The argon2id variable is not set

Compose, hash içindeki $ işaretlerini genişletmeye çalıştı. Değeri Adım 3'teki gibi .env içinde tek tırnakla yazın veya hash'i doğrudan compose.yaml içine yazıyorsanız her $ işaretini ikiye katlayın.

Yönetici sayfası devre dışı olduğunu söylüyor

Konteynerin içinde ADMIN_TOKEN boş. .env dosyasındaki değişkenin servise ulaşıp ulaşmadığını görmek için docker compose config çalıştırın, ardından konteyneri docker compose up -d ile yeniden oluşturun.

Loglar ve fail2ban ziyaretçinin IP'si yerine 127.0.0.1 gösteriyor

Caddy site bloğunda header_up X-Real-IP {remote_host} satırı eksik veya Caddy yeniden yüklenmemiş. Önüne Cloudflare proxy'si koyduysanız wiki bunun yerine hangi başlığın kullanılacağını açıklar.

Sonraki adımlar

• Yedeklerinizin sunucu dışı kopyalarını ikinci bir sunucuda çalışan kendi S3 depolamanızda tutun.
• Yönetici sayfasını WireGuard VPN sunucusu ile yalnızca VPN üzerinden erişilebilir yapın.
• Compose dosya biçimini Docker Compose temelleri rehberinde öğrenin.
• Özel parola kasası için sunucuları Vaultwarden hosting sayfasında karşılaştırın.
• SMTP, anlık bildirimler ve diğer seçenekler için Vaultwarden wiki sayfalarını okuyun.