Kendi sunucunuzda hızlı başlangıç

Multica'yı kendi sunucunuzda barındırmanın iki bölümü vardır:

Aynı makine olabilirler ya da ayrı olabilirler. Kendi sunucunuzda barındırmak yalnızca Multica Cloud kısmının yerini alır.

Bu kılavuz Docker Compose kullanır. Kubernetes dağıtımları için depodaki Kendi sunucunuzda barındırma kılavuzuna bakın.

Başlamadan önce

Multica servisini çalıştıracak makinenin şunlara ihtiyacı vardır:

• docker compose çalışan Docker Engine veya Docker Desktop
• Git, Make, curl ve OpenSSL
• Makinede boşta olan 3000 ve 8080 portları

Önce Docker ve Compose'un kullanılabilir olduğunu doğrulayın:

docker info
docker compose version

Multica, docker compose olarak çağrılan Compose v2 kullanır. Eski docker-compose v1 desteklenmez.

Bilgisayarın ayrıca Claude Code, Codex veya Cursor gibi kurulu ve giriş yapılmış en az bir yapay zekâ kodlama aracına ihtiyacı vardır. Multica CLI, 5. adımda kurulur.

1. Multica'yı başlatın

Servisi çalıştıracak makinede:

git clone --depth 1 https://github.com/multica-ai/multica.git
cd multica
make selfhost

İlk çalıştırmada, make selfhost şunları yapar:

1. .env.example'dan .env oluşturur
2. Rastgele bir JWT_SECRET, PostgreSQL parolası ve MULTICA_VCS_SECRET_KEY (kendi sunucunuzda barındırılan Git entegrasyonları için şifreleme anahtarı) üretir
3. PostgreSQL, Multica arka uç ve Multica ön uç imajlarını çeker
4. Kalıcı volume'ler oluşturur ve üç container'ı başlatır
5. Arka uç sağlık kontrollerine yanıt vermeye başlayana kadar bekler

make selfhost'u tekrar çalıştırmak mevcut .env'i ve volume'leri yeniden kullanır; sırları yeniden üretmez.

git fetch --tags --depth 1
git checkout $(git tag -l 'v*' --sort=-v:refname | head -1)

2. Servislerin hazır olduğunu doğrulayın

Container durumunu kontrol edin:

docker compose -f docker-compose.selfhost.yml ps

postgres, healthy göstermeli, backend ve frontend ise çalışıyor olmalıdır. Ardından arka ucu, veritabanını ve migration'ları kontrol edin:

curl -fsS http://localhost:8080/readyz

Beklenen yanıt:

{"status":"ok","checks":{"db":"ok","migrations":"ok"}}

Arka uç container'ı, hizmet vermeye başlamadan önce her başlangıçta veritabanı migration'larını çalıştırır; çalıştırılacak elle bir migration komutu yoktur.

3. Nasıl erişeceğinizi seçin

Yerel erişim

http://localhost:3000 adresini doğrudan açın. Daha sonra multica setup self-host çalıştırırken de herhangi bir URL geçmenize gerek kalmaz.

Uzaktan erişim

Docker Compose, 3000 ve 8080'i yalnızca 127.0.0.1'e bağlar. Bunu portları herkese açık internete açmak için 0.0.0.0'a değiştirmeyin; bunun yerine HTTPS'li bir ters proxy kullanın.

Aşağıdaki örnek iki alan adı kullanır:

• app.example.com: Multica web uygulaması
• api.example.com: API, sağlık kontrolleri ve daemon bağlantıları

Önce .env'de herkese açık URL'leri ayarlayın:

FRONTEND_ORIGIN=https://app.example.com
MULTICA_APP_URL=https://app.example.com
MULTICA_PUBLIC_URL=https://api.example.com

Bu yapılandırmayla tüm tarayıcı trafiği uygulama alan adında kalır, böylece çerezler asla alan adları arasında geçmez ve COOKIE_DOMAIN gerekmez. Tarayıcı bunun yerine doğrudan api alan adıyla konuşuyorsa, bunu ayarlamanız gerekir — bkz. Ortam değişkenleri.

Sonra DNS'i kurun ve yerel portları Caddy ile proxy'leyin:

app.example.com {
    # Tarayıcı WebSocket'lerini doğrudan arka uca ver
    @ws path /ws /ws/*
    handle @ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Geri kalan her şey ön uca gider, o da API ve giriş isteklerini iletir
    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

api.example.com {
    reverse_proxy 127.0.0.1:8080 {
        flush_interval -1
    }
}

Her şeyi tek bir origin üzerinden sunmayı tercih ediyorsanız (bir alan adı, ya da tek portlu tek bir host — küçük sunucularda yaygın), daemon açısından kritik yolları doğrudan arka uca yönlendirin ve geri kalanını ön uca bırakın:

multica.example.com {
    # CLI erişilebilirlik probu: `multica setup`, <sunucu-url>/health'e GET
    # atar ve 200 bekler — eski ön uç sürümleri bu yolu iletmez, bu yüzden
    # doğrudan yönlendirin
    handle /health {
        reverse_proxy 127.0.0.1:8080
    }

    # Tarayıcının gerçek zamanlı WebSocket'i — ön uç imajı WS yükseltmelerini proxy'leyemez
    handle /ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Daemon'ın uzun ömürlü WebSocket bağlantısı: daemon'lar {sunucu-url}/api/daemon/ws'i
    # arar (/ws değil). Bu rota olmadan el sıkışma başarısız olur ve daemon
    # sessizce yoklamaya (polling) düşer
    handle /api/daemon/ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Geri kalan her şey ön uca gider, o da API ve giriş isteklerini iletir
    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

Tek bir origin kullanıyorsanız, her iki URL'yi de ona yönlendirin (.env'de FRONTEND_ORIGIN ve MULTICA_APP_URL, ardından multica setup self-host'ta --server-url ve --app-url).

Caddy, TLS sertifikaları alır ve WebSocket'leri iletir. .env'i düzenledikten sonra, yeni yapılandırmanın etkin olması için container'ları up -d ile yeniden oluşturun:

docker compose -f docker-compose.selfhost.yml up -d
curl -fsS https://api.example.com/readyz
curl -fsS https://app.example.com/api/config | grep -o '"daemon_server_url":"[^"]*"'

Son komut, daemon'ların API'ye ulaşmak için kullandığı URL olan daemon_server_url'i yazdırır: ayarlıysa MULTICA_DAEMON_SERVER_URL, sonra MULTICA_PUBLIC_URL, yoksa uygulama URL'si — MULTICA_APP_URL, o da yoksa FRONTEND_ORIGIN. Ne MULTICA_APP_URL ne de FRONTEND_ORIGIN ayarlıysa, alan yanıttan tamamen çıkarılır (bu yüzden grep hiçbir şey yazdırmaz) — MULTICA_DAEMON_SERVER_URL veya MULTICA_PUBLIC_URL ayarlı olsa bile. Bir localhost adresi görünüyorsa .env hâlâ yerel varsayılanları taşıyor demektir: .env.example'dan kopyalanan ${FRONTEND_PORT} referanslarına güvenmek yerine FRONTEND_ORIGIN ve MULTICA_APP_URL'yi doğrudan herkese açık URL'lere ayarlayın, sonra container'ları yeniden oluşturun.

4. Giriş yapın ve bir çalışma alanı oluşturun

Yerelde http://localhost:3000'i, ya da az önce yapılandırdığınız https://app.example.com'u açın ve bir doğrulama kodu istemek için e-postanızı girin.

Varsayılan olarak hiçbir e-posta servisi yapılandırılmamıştır. Bir kod istedikten sonra, onu arka uç loglarından okuyun:

docker compose -f docker-compose.selfhost.yml logs backend \
  | grep "Verification code"

Loglar şuna benzer bir satır içerir:

[DEV] Verification code for you@example.com: 123456

Kodu girin ve ilk çalışma alanınızı oluşturun. Resend veya SMTP yapılandırıldıktan sonra kodlar e-postayla gönderilir ve üyelerin artık container loglarını okumasına gerek kalmaz — bkz. Giriş ve kayıt yapılandırması.

5. Bir bilgisayar bağlayın

Aşağıdaki komutları, Docker'ı çalıştıran sunucu olması gerekmeyen yapay zekâ kodlama araçlarınızı çalıştıran bilgisayarda çalıştırın.

Önce Multica CLI'ı kurun:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex

Multica servisi aynı bu bilgisayarda çalışıyorsa:

multica setup self-host

Multica servisi başka bir makinede çalışıyorsa, daha önce yapılandırdığınız iki URL'yi geçin:

multica setup self-host \
  --server-url https://api.example.com \
  --app-url https://app.example.com

Komut önce <sunucu-url>/health'i kontrol eder, ardından girişi tamamlamak için bir tarayıcı açar. Girişten sonra yerel kimlik bilgilerini saklar ve daemon'ı başlatır. Bu adımda alınan bir Server not reachable hatası, probun /health'ten 200 alamadığı anlamına gelir: proxy her şeyi bu yolu iletmeyen bir web sürümüne yönlendiriyor olabilir, proxy /health'i arka uca hiç yönlendirmiyor olabilir ya da daha alt seviyede bir hata söz konusudur (DNS, TLS, güvenlik duvarı, zaman aşımı, arka uçtan 5xx) — bkz. Sorun Giderme.

Bağlantıyı doğrulayın:

multica daemon status

Çıktı şunları göstermelidir:

• Daemon: running
• Bu makinede kurulu yapay zekâ kodlama araçlarını listeleyen Agents
• 0'dan büyük Workspaces

6. İlk çalıştırmayı tamamlayın

Multica'ya dönün, çevrimiçi bir runtime runtime listesinde göründüğünde bir agent oluşturun ve ona ilk işinizi atayın.

Çalıştırma tamamlandı olarak göründüğünde ve agent'ın yanıtı zaman akışında belirdiğinde, kendi sunucunuzda barındırılan servis, bilgisayar ve yapay zekâ kodlama aracının hepsi bağlıdır demektir. Ayrıntılı adımlar için hızlı başlangıcın 3-5. adımlarına bakın.

Sık kullanılan yönetici komutları

Bunların hepsini multica depo dizininden çalıştırın:

# Durumu kontrol et
docker compose -f docker-compose.selfhost.yml ps

# Arka uç loglarını izle
docker compose -f docker-compose.selfhost.yml logs -f backend

# .env değişikliklerini uygula
docker compose -f docker-compose.selfhost.yml up -d

# Volume'leri koruyarak servisleri durdur
docker compose -f docker-compose.selfhost.yml down

En son yayınlanan imajlara yükseltmek için:

git pull --ff-only
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d
curl -fsS http://localhost:8080/readyz

Bir Docker Compose kurulumunu yükseltmenin iki yolu. Mevcut bir kurulumda aynı sonucu üretirler — Makefile'daki selfhost hedefi aynı docker compose pull + up -d'yi çalıştırır, ayrıca .env eksikse oluşturur ve bir durum özeti yazdırmadan önce /health'i bekler. Tercih ettiğinizi seçin:

cd multica
git pull
make selfhost

cd multica
git pull
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

git pull gerçekte ne yapar

git pull, docker-compose.selfhost.yml'in kendisini günceller — yeni ortam değişkenleri, yeni servisler, değişen sağlık kontrolleri. Yeni bir Multica sürümü almanın yolu bu değildir.

Sonunda çalıştıracağınız sürüm, docker compose pull tarafından çözülür; bu komut GHCR'ye etiketin şu anda neyi işaret ettiğini sorar. Aylardır güncellenmemiş bir checkout bile bugünün latest imajlarını çeker; tersine, git pull tek başına imajları çekip container'ları yeniden oluşturana kadar hiçbir şeyi değiştirmez.

grep MULTICA_IMAGE_TAG .env
# MULTICA_IMAGE_TAG=v0.4.5   ← sabitlenmiş: önce `latest`'e (veya istediğiniz sürüme) düzenleyin

.env'iniz üzerine yazılmaz

make selfhost, .env'i yalnızca dosya eksikse üretir. Mevcut bir kurulumda tekrar çalıştırmak, JWT_SECRET'ınızı, Postgres parolanızı, e-posta ayarlarınızı ve FRONTEND_ORIGIN'inizi tam olarak oldukları gibi bırakır.

Önce Postgres'i yedekleyin

Migration'lar yalnızca ileri yönlüdür, bu yüzden önemsediğiniz bir dağıtımı yükseltmeden önce bir dump alın:

docker compose -f docker-compose.selfhost.yml exec -T postgres \
  pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql

multica varsayılanlarından değiştirdiyseniz .env'deki kendi POSTGRES_USER / POSTGRES_DB'nizi kullanın. Veri, docker compose down'dan sağ çıkan ama down -v'den çıkamayan multica_pgdata adlı named volume'de yaşar.

Migration'lar kendi kendine çalışır

1. Adımda olduğu gibi, arka uç container'ı trafiğe hizmet vermeden önce başlangıçta ./migrate up çalıştırır (docker/entrypoint.sh). Ayrı bir yükseltme komutu yoktur — yeni imajı ayağa kaldırmak, migration adımının kendisidir. Gerçekleştiğini izleyin:

docker compose -f docker-compose.selfhost.yml logs -f backend

Migration'lar arka uç başladığında otomatik çalışır; geçmiş veriyi geriye dolduran migration'lar da (103 gibi) geriye doldurmayı otomatik tamamlar. Nadir durumlarda otomatik geriye doldurma refusing to drop legacy daily rollups hatasıyla başarısız olur — bkz. Sorun Giderme.

/health değil, /readyz ile doğrulayın

/health bir canlılık (liveness) probudur — migration'lar başarısız olsa bile süreç ayaktayken {"status":"ok"} döndürür. /readyz (server/cmd/server/router.go:680; /healthz bir takma addır) veritabanını ve uygulanan migration kümesini kontrol eder, bu yüzden kötü bir yükseltmeyi yakalayan odur:

curl -s localhost:8080/readyz
# {"status":"ok","checks":{"db":"ok","migrations":"ok"}}

HTTP 200 ve her iki kontrolün de ok olması dışındaki her şey, yeni sürümün migration'ı bitirmediği anlamına gelir — trafik göndermeden önce arka uç loglarını kontrol edin.

Kubernetes

Helm'in kendi yükseltme yolu vardır: values dosyanızda images.backend.tag / images.frontend.tag'i istediğiniz sürüme ayarlayın, sonra helm upgrade yapın. Etiketi değiştirmek pod spesifikasyonunu değiştirir, bu yüzden Kubernetes yeni imajı çeker ve Deployment'ları döndürür — güvenilir yol budur.

kubectl -n multica rollout restart tek başına bir yükseltme değildir. Chart, pullPolicy: IfNotPresent ile gelir (deploy/helm/multica/values.yaml), bu yüzden o etiketi zaten önbelleğe almış bir node eski imajı yeniden kullanır ve yeniden başlatma sessizce hiçbir şeyi değiştirmez — sabitlenmiş bir MULTICA_IMAGE_TAG ile aynı sınıf tuzak. Bu şekilde değişken bir etiketi takip etmek istiyorsanız, önce images.backend.pullPolicy / images.frontend.pullPolicy'yi Always'e ayarlayın. Bkz. Kendi sunucunuzda barındırma kılavuzu.

Yaygın sorunlar

Daha fazla senaryo için bkz. Sorun Giderme.

Sonraki adımlar

• Giriş ve kayıt yapılandırması — e-postayı, Google girişini ve kayıt kapsamını yapılandırın.
• Ortam değişkenleri — tam sunucu yapılandırma referansı.
• Kendi sunucunuzda barındırma kılavuzu — Kubernetes, yükseltmeler ve elle dağıtım.
• Masaüstü uygulaması — Masaüstü'nü kendi sunucunuzda barındırılan bir servise bağlayın.