Panduan praktis stack Docker Compose repositori: apa yang dilakukan tiap layanan, kunci apa yang kamu butuhkan, cara berjalan tanpa AI cloud, dan apa yang perlu diperkuat sebelum produksi.
Oleh Sans Clip · Diperbarui · 9 mnt baca
Sans Clip adalah AI video clipper open source di balik aplikasi yang di-host di supoclip.com. Repositori yang sama menyertakan stack Docker Compose yang bisa kamu jalankan di laptop, server rumah, atau VPS. Panduan ini mengikuti stack itu persis seperti yang ada di repositori. Kalau sebuah langkah bergantung pada penyedia atau perangkatmu, kami mengatakannya alih-alih menebak.
Lebih suka tidak menjalankan infrastruktur? Aplikasi yang di-host menjalankan pipeline yang sama. Masih memilih alat? Baca kami dulu.
docker compose up memulai kontainer ini, semuanya didefinisikan di docker-compose.yml:
Layanan dalam stack Docker Compose Sans Clip
Layanan
Peran
Port host
frontend
Aplikasi web Next.js, autentikasi, dan proxy API
FRONTEND_PORT (3107 di .env.example; 3001 jika tidak diatur)
backend
API FastAPI; dokumen di /docs
8000
worker
Worker ARQ: unduh, transkripsi, analisis, render
tidak ada
postgres
PostgreSQL 15: pengguna, tugas, clip
tidak ada
redis
Redis 7: antrean pekerjaan dan progres langsung
6379
mcp
Server MCP untuk klien AI (opsional untuk tetap dijalankan)
9100
Setiap port yang dipublikasikan diikat ke 127.0.0.1, jadi instalasi baru hanya bisa dijangkau dari mesin itu sendiri. Clip yang dihasilkan, unggahan, Postgres, dan Redis disimpan di volume Docker bernama, jadi mereka bertahan saat kontainer dimulai ulang. Kalau kamu tidak memakai MCP, hentikan kontainer itu dengan docker compose stop mcp.
Kebutuhan
Docker dengan Compose v2 (docker compose) atau docker-compose yang berdiri sendiri, plus Git.
Sumber transkripsi, diatur dengan TRANSCRIPTION_PROVIDER: assemblyai (default, butuh ASSEMBLY_AI_API_KEY), whisper (lokal, tanpa kunci), atau youtube_captions (hanya tautan YouTube).
LLM untuk pemilihan clip, diatur dengan LLM=provider:model: OpenAI, Google, Anthropic, OpenRouter (masing-masing butuh kunci API-nya), atau model ollama: lokal.
Opsional:PEXELS_API_KEY untuk overlay B-roll.
Build image pertama mengunduh dependensi Python dan Node. Mulai cepat memperkirakan 5–10 menit; itu bervariasi menurut koneksi dan CPU-mu.
Instal dengan Docker Compose
1. Kloning dan buat file environment-mu
terminal
git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env
2. Pilih penyedia di .env
Template secara default memakai LLM=openrouter:anthropic/claude-sonnet-5.5. Pemrosesan gagal kecuali kamu mengatur OPENROUTER_API_KEY atau mengarahkan LLM ke penyedia yang punya kuncinya. Penyiapan cloud minimal terlihat seperti ini:
.env
TRANSCRIPTION_PROVIDER=assemblyai
ASSEMBLY_AI_API_KEY=your_assemblyai_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_key
# Replace every placeholder secret, even for local use
BETTER_AUTH_SECRET=generate_with_openssl_rand_base64_32
BACKEND_AUTH_SECRET=generate_another_one
APP_SETTINGS_ENCRYPTION_KEY=and_another_one
Buat setiap rahasia dengan openssl rand -base64 32. SELF_HOST=true (default) mematikan tagihan dan menghapus batas generasi per akun.
3. Build dan mulai
terminal
docker compose up -d --build
# or: ./start.sh (checks .env and Docker first, then does the same)
Buka http://localhost:3107, buat akun, lalu tempel tautan YouTube, Twitch, atau Kick atau unggah file. Dokumen API ada di http://localhost:8000/docs.
Opsi: transkripsi dan pemilihan clip yang sepenuhnya lokal
Untuk menjaga transkrip dan analisis di perangkatmu sendiri, gabungkan Whisper lokal dengan model Ollama:
.env
TRANSCRIPTION_PROVIDER=whisper
WHISPER_MODEL_SIZE=medium # tiny | base | small | medium | large | large-v3
LLM=ollama:gpt-oss:20b
# Empty = http://host.docker.internal:11434/v1 inside the containers.
# If you set it yourself, keep the /v1 suffix.
OLLAMA_BASE_URL=
Worker membuat panggilan Ollama dari dalam kontainernya, jadi Ollama harus bisa dijangkau dari sana, bukan hanya dari shell-mu. Cara mencapainya bergantung pada tempat Ollama berjalan:
Ollama di host, dengan Docker Desktop (macOS, Windows)
Tidak perlu penyiapan tambahan. Docker Desktop meneruskan host.docker.internal ke host, jadi biarkan OLLAMA_BASE_URL kosong dan tarik model dengan ollama pull gpt-oss:20b.
Ollama di host, dengan Docker Engine (Linux)
Compose memetakan host.docker.internal ke gateway bridge Docker, tapi Ollama secara default hanya mendengarkan di 127.0.0.1, jadi koneksi worker ditolak. Buat Ollama mendengarkan di semua antarmuka:
Itu juga membuka port 11434 di antarmuka jaringanmu. Ollama tidak punya autentikasi, jadi blokir port itu dari luar mesin dengan firewall-mu. Kalau firewall-mu menyaring lalu lintas dari jaringan Docker, izinkan juga kontainer untuk mencapainya.
Ollama di kontainernya sendiri
Tambahkan ke stack dengan file override, lalu arahkan Sans Clip ke nama layanan, bukan ke host:
docker-compose.override.yml (gabungkan ke override yang sudah kamu punya)
OLLAMA_BASE_URL=http://ollama:11434/v1
docker compose up -d ollama
docker compose exec ollama ollama pull gpt-oss:20b
docker compose up -d backend worker # pick up the new .env value
Penyiapan mana pun yang kamu pilih, uji dari dalam worker sebelum mengirim video. Pemeriksaan mencari gpt-oss:20b karena itu model dalam nilai LLM contoh. Kalau kamu memilih model lain, ganti dengan nama persis setelah ollama: di pengaturan LLM-mu. Ollama mencantumkan model yang ditarik tanpa tag sebagai name:latest, jadi pakai bentuk itu dalam pemeriksaan.
model ready berarti worker bisa mencapai Ollama dan model yang kamu cari terpasang. Tidak ada keluaran berarti koneksi gagal atau modelnya hilang, jadi jalankan ulang perintah tanpa grep untuk melihat yang mana. Model Whisper yang lebih kecil menukar akurasi dengan kecepatan, dan kualitas clip bergantung pada LLM. Bandingkan model lokal dengan yang di-host pada rekaman yang kamu kenal sebelum mengalihkan seluruh backlog.
Verifikasi instalasi
terminal
docker compose ps # every service should be "healthy"
curl -f http://localhost:8000/health/db # backend can reach Postgres
docker compose logs -f worker # watch a job move through the pipeline
Buat akun dan kirim video pendek dulu, supaya kesalahan konfigurasi gagal dengan cepat.
Pastikan halaman tugas menampilkan pembaruan progres. Kalau tetap dalam antrean, periksa log worker.
Putar dan unduh clip yang selesai.
Tugas yang macet biasanya karena kunci penyedia yang hilang atau worker yang tidak bisa mencapai Redis. Panduan pemecahan masalah membahas kasus yang umum.
Daftar periksa produksi
File Compose disetel untuk mulai. Sebelum menaruhnya di domain publik:
Build frontend produksi. Compose secara default memakai target development yang hot-reload dan memasang frontend/src ke dalam kontainer. Atur FRONTEND_BUILD_TARGET=runner dan NODE_ENV=production di .env, lalu buang pemasangan sumber dengan override di bawah.
Akhiri HTTPS di reverse proxy (Caddy, nginx, Traefik) di depan port frontend.
Buka backend untuk unggahan. Dengan BACKEND_AUTH_SECRET yang diatur, browser mengunggah file video langsung ke NEXT_PUBLIC_API_URL. Arahkan itu ke URL backend HTTPS publik, dan tambahkan origin frontend-mu ke CORS_ORIGINS.
Atur origin publikmu di mana-mana:NEXT_PUBLIC_APP_URL, BETTER_AUTH_URL, dan CORS_ORIGINS. Nilai NEXT_PUBLIC_* tertanam saat build, jadi build ulang frontend setelah mengubahnya.
Ubah kata sandi basis data.docker-compose.yml menuliskan supoclip_password di empat tempat: POSTGRES_PASSWORD di layanan postgres dan DATABASE_URL di layanan frontend, backend, dan worker. Mengedit POSTGRES_PASSWORD di .env saja tidak mengubah salah satunya. Timpa keempatnya, seperti ditunjukkan di bawah.
Atur REDIS_PASSWORD; kontainer Redis mengaktifkan AUTH saat nilainya tidak kosong.
Tutup pendaftaran dengan DISABLE_SIGN_UP=true kalau instans hanya untuk timmu.
services:
frontend:
volumes: !reset [] # the runner image already contains the build
Untuk kata sandi basis data, taruh nilai baru di POSTGRES_PASSWORD dalam .env. Buat dengan openssl rand -hex 24, karena hex tidak perlu di-escape di dalam URL. Lalu arahkan keempat pengaturan ke nilai itu di file override yang sama:
docker-compose.override.yml (gabungkan ke override yang sudah kamu punya)
Postgres membaca POSTGRES_PASSWORD hanya saat menginisialisasi volume data yang kosong. Pada instalasi yang sudah punya basis data, mengubah variabel itu tidak mengubah kata sandi yang sebenarnya. Putar kata sandinya di dalam Postgres dulu, memakai nilai yang sama seperti di .env. Lalu buat ulang layanan agar mereka memakai URL baru:
init.sql membuat skema hanya saat volume Postgres pertama kali diinisialisasi. Setelah itu, tidak ada yang memperbarui skema secara otomatis. Kalau versi baru menambahkan file di bawah frontend/prisma/migrations atau backend/migrations, terapkan sendiri sebelum kamu memulai ulang aplikasi. Kode baru yang berjalan terhadap skema lama gagal karena kolom dan tabel yang hilang. Cadangkan dulu, dan hentikan layanan aplikasi agar mereka tidak mengambil kode baru terlalu cepat. Frontend pengembangan me-reload sumber yang dipasang.
Baca setiap file yang tercantum, lalu terapkan dalam satu transaksi. Terapkan migrasi Prisma sesuai urutan stempel waktu dan migrasi backend sesuai urutan nomor:
Basis data yang dibuat oleh init.sql tidak punya riwayat migrasi Prisma. Jangan jalankan prisma migrate deploy terhadapnya: Prisma akan memutar ulang setiap migrasi dari yang pertama dan gagal pada tabel yang sudah ada. Kalau kamu ingin Prisma mengelola migrasi mulai sekarang, baseline dulu dengan prisma migrate resolve --applied <migration>, tapi hanya untuk migrasi yang perubahannya sudah ada di skemamu. Prisma secara permanen melewati migrasi apa pun yang kamu tandai sebagai diterapkan, bahkan kalau perubahannya belum ada.
Cadangkan volume clips dan uploads juga kalau kamu perlu menyimpan video yang dirender. Jangan pernah menjalankan docker compose down -v pada instans yang kamu pedulikan: itu menghapus setiap volume, termasuk basis data.
Ingin menyesuaikan keluaran? Taruh font .ttf di backend/fonts/ dan transisi .mp4 di backend/transitions/. Mereka muncul di aplikasi secara otomatis. Untuk otomatisasi, buat kunci API di Pengaturan dan pakai REST API atau server MCP yang disertakan.
Pertanyaan yang sering diajukan
Apakah Sans Clip yang di-host sendiri gratis?
Kodenya gratis di bawah AGPL-3.0 dan mode host sendiri tidak punya batas generasi atau paywall. Kamu tetap membayar perangkat atau server sendiri, serta pemakaian transkripsi cloud atau LLM apa pun yang kamu konfigurasi. Penyiapan Whisper + Ollama menghindari biaya AI per permintaan, tapi butuh komputasi lokal yang cukup.
Bisakah Sans Clip berjalan tanpa layanan AI cloud sama sekali?
blog.self-host-supoclip-docker.faqs.1.answer
Apakah saya butuh GPU?
Tidak. Template .env.example mengatur BACKEND_CPU_ONLY=true, yang memasang PyTorch khusus CPU. Transkripsi Whisper khusus CPU lebih lambat daripada API cloud, jadi video panjang memakan waktu lebih lama di perangkat sederhana.
Apakah ini berjalan di Apple Silicon?
Ya, dengan catatan: image backend dan worker berjalan sebagai linux/amd64 di bawah emulasi. BACKEND_CPU_ONLY=true menghindari unduhan NVIDIA, tapi tidak mengaktifkan akselerasi GPU Apple.
Bagaimana saya menjaga instans tetap privat?
Buat akunmu, lalu atur DISABLE_SIGN_UP=true dan buat ulang kontainer frontend. Compose mengikat setiap port ke 127.0.0.1, jadi tidak ada yang publik sampai kamu menambahkan reverse proxy.
Coba di satu rekaman yang kamu kenal baik.
Pakai aplikasi yang di-host, atau jalankan kode open source yang sama di mesinmu sendiri.