Variabel Lingkungan

Halaman ini mencantumkan variabel lingkungan untuk operator yang didukung dan dibaca oleh backend, frontend, serta skrip pemeliharaan Libre WebUI saat ini. Canary internal khusus pengujian sengaja tidak disertakan.

Server Backend

Variabel	Bawaan	Tujuan
`NODE_ENV`	`development`	Mode runtime
`PORT`	`3001` dalam pengembangan, `8080` dalam produksi	Port HTTP backend
`TRUST_PROXY`	tidak ditetapkan (`0` di Helm)	Jumlah hop reverse proxy tepercaya yang persis untuk menentukan alamat klien
`CORS_ORIGIN`	origin pengembangan lokal	Origin peramban yang diizinkan, dipisahkan koma
`SERVE_FRONTEND`	tidak ditetapkan	Menyajikan frontend hasil build dari backend jika `true`
`DOCKER_ENV`	tidak ditetapkan	Mengaktifkan perilaku berorientasi Docker jika `true`
`DATA_DIR`	`backend/data`; `~/.libre-webui` dalam CLI terpaket	Direktori data persisten
`PLATFORM_PREFLIGHT_TMP_DIR`	`backend/temp/preflight`; cache pengguna dalam CLI terpaket	Ruang sementara untuk salinan pemeriksaan awal DB/WAL privat; sediakan ukuran database plus WAL
`PLUGIN_UPLOAD_TEMP_DIR`	`libre-webui-plugin-uploads` di bawah direktori sementara OS	Ruang sementara untuk unggahan plugin yang sedang berlangsung
`PLUGINS_DIR`	`$DATA_DIR/plugins`	Direktori dapat-tulis untuk plugin terinstal/khusus
`BASE_URL`	`http://localhost:3001`	URL dasar untuk nilai bawaan callback OAuth
`LOG_LEVEL`	`info` (`warn` dalam pengujian)	Tingkat log backend
`LOG_FORMAT`	`text`	`json` beralih ke log satu baris terstruktur dengan stempel waktu, ID korelasi, dan penyuntingan
`OTEL_EXPORTER_OTLP_ENDPOINT`	tidak ditetapkan	Ekspor telemetri JSON OTLP/HTTP opsional; tanpa nilai berarti telemetri tidak keluar dari proses
`OTEL_EXPORTER_OTLP_HEADERS`	tidak ditetapkan	Header `key=value` dipisahkan koma yang dikirim ke kolektor OTLP (misalnya autentikasi)
`OTEL_SERVICE_NAME`	`libre-webui`	Atribut sumber daya `service.name` pada telemetri yang diekspor
`WEBUI_HOST`	loopback; `0.0.0.0` di Docker	Alamat dengar HTTP
`OPEN_BROWSER`	`true` saat menyajikan frontend	Tetapkan `false` untuk mencegah peluncuran peramban otomatis
`FULL_DOCUMENT_CONTEXT_MAX_TOKENS`	`32000`	Pelindung token untuk mode konteks dokumen lengkap per chat (1000-2000000)
`GALLERY_RETENTION_DAYS`	tidak ditetapkan (simpan selamanya)	Menghapus media galeri yang lebih tua dari jumlah hari ini melalui sapuan penjadwal
`RECOVERY_DRILL_INTERVAL_HOURS`	tidak ditetapkan (latihan nonaktif)	Menjalankan latihan pemulihan terverifikasi otomatis setiap N jam (profil solo)
`RECOVERY_DRILL_HISTORY`	`60`	Entri riwayat latihan pemulihan yang dipertahankan

Peluncuran dari sumber menambatkan nilai relatif DATA_DIR, PLUGINS_DIR, dan PLATFORM_PREFLIGHT_TMP_DIR pada direktori backend, terlepas dari direktori kerja shell. Karena itu, jika DATA_DIR tidak ditetapkan—atau menggunakan contoh sumber baru DATA_DIR=./data—perintah ruang kerja root dan backend memakai backend/data. Demi kompatibilitas, konfigurasi sumber yang sudah ada dan memuat DATA_DIR=./backend/data tetap memilih backend/backend/data; ubah hanya sebagai bagian dari pencadangan dan migrasi disengaja saat layanan dihentikan. Profil sumber tanpa nilai juga tetap menggunakan backend/backend/data jika itu satu-satunya penyimpanan tahan lama yang ada. Jika kedua lokasi berisi keadaan dan tidak ada jalur dipilih, proses mulai menolak secara aman alih-alih menebak, menyalin, atau menggabungkan.

Peluncur npx, npm global, dan Homebrew interaktif menyimpan data di ~/.libre-webui. DATA_DIR relatif eksplisit yang diberikan kepada peluncur diselesaikan dari direktori kerja pemanggil dan diubah menjadi jalur absolut sebelum backend dimulai. PLUGINS_DIR relatif yang dikonfigurasi eksplisit mengikuti aturan relatif-pemanggil yang sama; jika tidak ditetapkan, plugin dapat-tulis tetap di $DATA_DIR/plugins. Ruang sementara inspeksi secara bawaan memakai cache dapat-tulis milik pengguna di luar direktori data: ~/Library/Caches/libre-webui pada macOS, %LOCALAPPDATA%\libre-webui pada Windows, atau ${XDG_CACHE_HOME:-~/.cache}/libre-webui pada sistem lain. Layanan Homebrew mengunci direktori data home yang sama dan menggunakan var/libre-webui/preflight milik Homebrew sebagai ruang sementara. Tetapkan PLATFORM_PREFLIGHT_TMP_DIR secara eksplisit jika cache tidak dapat menampung database beserta WAL-nya. Deployment Docker dan Helm yang disediakan memakai jalur absolut /app/backend/data dan /app/backend/temp/preflight dengan mount terpisah.

Fondasi Platform

Profil solo bawaan menggunakan SQLite, blob lokal terenkripsi, vektor tertanam terenkripsi, koordinasi lokal, dan worker tahan lama tertanam. Profil team menggunakan PostgreSQL, blob privat kompatibel S3, PGVector, Redis, dan worker eksternal. Konfigurasi team menolak secara aman: semua dependensi bersama harus dipilih sekaligus.

Variabel	Bawaan	Tujuan
`LIBRE_PLATFORM_MODE`	`solo`	Memilih profil `solo` atau `team` yang koheren
`DATABASE_BACKEND`	`sqlite`	Memilih `sqlite` atau `postgres`
`DATABASE_URL`	tidak ditetapkan	URL koneksi PostgreSQL, wajib dengan `postgres`
`DATABASE_SSL_MODE`	`verify-full`	Kebijakan TLS PostgreSQL: `disable`, `require`, atau `verify-full` yang memverifikasi nama host
`POSTGRES_MIGRATION_MODE`	`apply`	Menjalankan migrasi kompatibel di bawah kunci pemimpin, atau memakai `validate` untuk pemeriksaan skema hanya baca
`POSTGRES_POOL_MAX`	`10`	Koneksi PostgreSQL maksimum per proses aplikasi atau worker (1-100)
`POSTGRES_CONNECT_TIMEOUT_MS`	`5000`	Batas waktu koneksi PostgreSQL (1-60000 ms)
`POSTGRES_IDLE_TIMEOUT_MS`	`30000`	Batas waktu koneksi diam PostgreSQL (1-600000 ms)
`POSTGRES_STATEMENT_TIMEOUT_MS`	`30000`	Batas waktu pernyataan PostgreSQL (1-600000 ms)
`POSTGRES_MIGRATION_LOCK_TIMEOUT_MS`	`60000`	Waktu menunggu kunci pemimpin migrasi (1-600000 ms)
`BLOB_STORE_BACKEND`	`local`	Memilih penyimpanan `local` terenkripsi atau `s3` privat
`VECTOR_STORE_BACKEND`	`embedded` dengan SQLite	Memilih vektor `embedded` terenkripsi atau `pgvector`
`COORDINATION_BACKEND`	`local` dalam solo; `redis` dalam team	Memilih koordinasi lokal-proses atau Redis
`REDIS_URL`	tidak ditetapkan	URL `redis:` atau `rediss:`, wajib dengan koordinasi Redis
`REDIS_KEY_PREFIX`	`libre`	Namespace 1-64 karakter untuk kunci koordinasi Libre
`REDIS_CONNECT_TIMEOUT_MS`	`5000`	Batas waktu koneksi awal Redis, maksimum 60 detik
`JOB_WORKER_MODE`	`embedded` dalam solo; `external` dalam team	Menjalankan handler dalam aplikasi atau worker bersama mandiri
`RESOURCE_LEASE_TTL_MS`	`30000`	TTL sewa koordinasi bagi kepemilikan sumber daya pekerjaan tahan lama (5000-300000; proses mulai gagal di luar rentang)
`JOB_WORKER_CONCURRENCY`	`4`	Pekerjaan tahan lama yang dapat dijalankan bersamaan oleh satu worker (1-32)
`CHAT_STREAM_EVENT_RETENTION_HOURS`	`24`	Jam penyimpanan peristiwa potongan aliran chat sebelum sapuan per jam menghapusnya
`PLATFORM_EVENT_RETENTION_DAYS`	`30`	Hari penyimpanan setiap peristiwa tahan lama sebelum sapuan per jam menghapusnya
`PLATFORM_JOB_RETENTION_DAYS`	`30`	Hari penyimpanan pekerjaan non-siklus-hidup selesai sebelum sapuan per jam menghapusnya
`LIBRE_SKIP_STARTUP_INTEGRITY_SCAN`	tidak ditetapkan	`1` melewati pemindaian ciphertext lama mendalam pada proses mulai berikutnya (jalan keluar; hasil biasanya di-cache per generasi skema)
`STORAGE_ENCRYPTION_KEYS`	tidak ditetapkan	Peta kunci JSON rahasia; saat ini harus memuat `legacy` yang cocok dengan `ENCRYPTION_KEY`
`STORAGE_ENCRYPTION_ACTIVE_KEY_ID`	tidak ditetapkan	ID kunci untuk penulisan blob lokal dan vektor tertanam baru
`BLOB_QUOTA_BYTES_PER_USER`	`10737418240`	Byte blob teks biasa maksimum yang tahan lama per pemilik (bilangan bulat aman positif)
`BLOB_QUOTA_RESERVATION_TTL_MS`	`3600000`	Masa berlaku reservasi kuota streaming yang ditinggalkan (sedikitnya 60000 ms)
`S3_BUCKET`	tidak ditetapkan	Bucket privat kompatibel S3, wajib dengan `s3`
`S3_REGION`	tidak ditetapkan	Region S3, wajib dengan `s3`
`S3_ENDPOINT`	bawaan penyedia	Endpoint HTTP(S) absolut opsional untuk MinIO atau layanan kompatibel lain
`S3_ACCESS_KEY_ID`	rantai kredensial SDK	Kunci akses S3 eksplisit opsional
`S3_SECRET_ACCESS_KEY`	rantai kredensial SDK	Wajib jika kunci akses eksplisit ditetapkan
`S3_SESSION_TOKEN`	tidak ditetapkan	Token opsional yang menyertai kredensial S3 eksplisit
`S3_FORCE_PATH_STYLE`	`false`	Tetapkan `true` untuk layanan yang memerlukan pengalamatan bergaya jalur
`S3_BLOB_PREFIX`	`libre/blobs`	Prefiks kunci bucket buram milik Libre

Jika peta kunci penyimpanan berversi tidak tersedia, adapter penyimpanan menggunakan ENCRYPTION_KEY yang ada sebagai ID kunci legacy; jika nilai itu juga tidak tersedia, adapter membaca ${DATA_DIR}/.encryption_key yang ada tanpa membuat atau mengubahnya. Konfigurasi eksplisit dan berkas persisten harus cocok. Jika peta berversi diperkenalkan saat kunci lama tersedia, pertahankan kunci itu di bawah ID persis legacy sampai semua objek dan vektor telah ditulis ulang atau dibungkus ulang serta diverifikasi. Konflik, izin berkas tidak aman, symlink, dan kunci terkonfigurasi yang hilang ditolak secara aman.

Redis adalah koordinasi, bukan persistensi kanonis. Memilihnya saja tidak membuat SQLite, berkas lokal, atau keadaan lain milik proses aman di seluruh replika. Dalam mode team, batas laju HTTP, koneksi chat/WebSocket, pekerjaan penyedia STT/TTS/audio, impor arsip, dan sesi terminal Work menggunakan penerimaan bersama berbasis Redis. Kapasitas berlaku di seluruh replika, bukan sekali per proses. Kegagalan penerimaan dan izin yang dapat diperbarui mengembalikan 503 atau membatalkan operasi yang sedang berjalan; Libre tidak pernah kembali ke penghitung lokal independen. Lihat Fondasi Platform.

Profil Compose team dan chart Helm terpaket meneruskan setiap pemilih platform serta nilai penyetelan team di atas kepada aplikasi dan worker eksternal. Dalam chart Helm, pemilih nonrahasia berada di bawah env; tetapkan secrets.redisUrl, secrets.databaseUrl, dan secrets.storageEncryptionKeys untuk koneksi atau materi kunci. Batas pool PostgreSQL berlaku per proses: sediakan database untuk sedikitnya (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX koneksi, ditambah ruang operator dan migrasi. Pertahankan DATABASE_SSL_MODE=verify-full untuk PostgreSQL terkelola atau jarak jauh. Hanya profil Compose team terpaket yang memilih disable karena listener databasenya diisolasi pada jaringan proyek privat. Helm team juga memerlukan satu secrets.jwtSecret stabil dan memasang kunci Secret yang sama ke setiap pod aplikasi serta worker; jika rahasia JWT tidak ada, materi penandatanganan lokal-proses akan dibuat. S3 menerima kunci buram dan ciphertext; URL bucket serta penyedia tidak disimpan dalam metadata aplikasi.

Arsip solo dan team terintegrasi mempertahankan pengaturan pool dan batas waktu PostgreSQL, batas waktu koneksi Redis, kedua pengaturan kuota blob, pemilih platform, serta pengaturan pengalamatan S3 dalam konfigurasi terlindungi yang ditandatangani dan dienkripsi. Karena itu, pemulihan bersih dapat menerbitkan nilai operasional yang diperlukan untuk membuat ulang deployment yang cocok tanpa menempatkannya dalam metadata arsip teks biasa.

Pasangan aplikasi/worker eksternal Compose dan Helm team terpaket menerima OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT, dan OLLAMA_MAX_CONTEXT hasil resolusi yang sama. Panggilan penyedia untuk embedding dokumen, chat tahan lama, dan proses Work dijalankan dalam worker, sehingga nilai tersebut tidak boleh berbeda antarp proses. Kedua titik masuk server mengurai tiga nilai numerik sebagai bilangan bulat positif basis-10 lengkap sebelum membuat keadaan lokal atau terhubung ke keadaan bersama. Nilai parsial seperti 300000ms, notasi eksponen/heksadesimal, nilai di luar rentang, dan batas waktu operasi panjang di bawah batas waktu standar membuat proses mulai gagal.

Helm membatasi TRUST_PROXY ke jumlah hop bilangan bulat persis dari 0 hingga 16 dan hanya meneruskannya ke pod aplikasi HTTP. Pertahankan nilai bawaan 0 untuk lalu lintas langsung. Tetapkan jumlah tetap yang persis untuk rantai ingress/load balancer; jangan pernah gunakan bentuk true runtime yang tidak terbatas. Jumlah yang salah akan mengelompokkan klien di bawah alamat proksi untuk batas laju bersama atau memercayai alamat yang dapat diberikan klien.

Kompatibilitas skema PostgreSQL menggunakan versi persis. Aplikasi dan worker Helm menggunakan Recreate; kuras dan hentikan setiap pod lama sebelum peningkatan team, lalu biarkan satu proses baru bermigrasi di bawah kunci pemimpin advisory. Jangan jalankan versi biner campuran atau mengklaim peluncuran skema tanpa waktu henti. Rollback berarti memulihkan arsip team terverifikasi sebelum peningkatan ke tujuan PostgreSQL/S3 yang bersih sebelum memulai biner lama yang cocok.

Aplikasi team aktif memerlukan worker.replicaCount >= 1; Helm menolak aplikasi aktif tanpa worker tahan lama, bukan menunggu kesiapan gagal. Tetapkan jumlah aplikasi dan worker ke nol untuk penangguhan penuh. Aplikasi nol dengan jumlah worker positif merupakan mode pengurasan atau pemulihan khusus-worker yang disengaja dan terus mengonsumsi pekerjaan antrean tanpa melayani lalu lintas web.

Pembantu Cadangan Privat

Variabel ini mengonfigurasi deploy/private/libre-webui-backup dan dibaca oleh skrip pemeliharaan, bukan proses aplikasi:

Variabel	Bawaan	Tujuan
`LIBRE_WEBUI_STACK_DIR`	`/opt/libre-webui`	Direktori yang memuat berkas Compose privat
`LIBRE_WEBUI_BACKUP_DIR`	`/var/backups/libre-webui`	Direktori terlindungi untuk set cadangan dan berkas kunci
`LIBRE_WEBUI_BACKUP_RETENTION_DAYS`	`14`	Usia saat set cadangan selesai dihapus
`LIBRE_WEBUI_CONTAINER_NAME`	`libre-webui`	Kontainer aplikasi ter-deploy yang akan diperiksa
`LIBRE_WEBUI_BACKUP_KEY_DIR`	`/etc/libre-webui/backup-keys`	Direktori kunci enkripsi dan penandatanganan arsip privat
`LIBRE_WEBUI_RESTORE_IMAGE`	wajib untuk pemulihan	ID atau digest image Libre yang tidak dapat diubah dan telah ditinjau
`LIBRE_WEBUI_RESTORE_CONFIG_DIR`	jalur per volume di bawah `/etc/libre-webui/restored`	Direktori baru untuk konfigurasi hasil pemulihan

Unit systemd memuat override cadangan dari berkas opsional milik root /etc/libre-webui/backup.env. Tetapkan modenya ke 0600. Direktori stack, retensi, nama kontainer, dan direktori kunci cadangan dapat ditetapkan langsung di sana. Sandbox sistem berkas unit hanya mengizinkan penulisan di bawah direktori cadangan bawaan. LIBRE_WEBUI_BACKUP_DIR khusus juga memerlukan direktori persis yang telah dibuat sebelumnya dalam drop-in layanan ReadWritePaths=; lihat Deployment Jarak Jauh Privat.

Autentikasi dan Keamanan

Variabel	Bawaan	Tujuan
`ENABLE_SIGNUP`	`false`	Mengizinkan pendaftaran setelah administrator lokal pertama
`JWT_SECRET`	dibuat/fallback dalam pengembangan	Rahasia penandatanganan JWT; tetapkan eksplisit dalam produksi
`JWT_EXPIRES_IN`	`7d`	Masa berlaku token sesi
`ENCRYPTION_KEY`	dibuat otomatis	Kunci heksadesimal 64 karakter untuk nilai terenkripsi
`DEBUG_ENCRYPTION`	tidak ditetapkan	Mencatat keluaran debug enkripsi jika ditetapkan
`TURNSTILE_SITE_KEY`	tidak ditetapkan	Kunci situs Cloudflare Turnstile untuk login dan pendaftaran
`TURNSTILE_SECRET_KEY`	tidak ditetapkan	Kunci rahasia Cloudflare Turnstile untuk verifikasi backend
`TURNSTILE_EXPECTED_HOSTNAME`	nama host dari `BASE_URL`	Nama host wajib dalam respons verifikasi Cloudflare
`MFA_REQUIRED_MODE`	tidak ditetapkan (sakelar admin, `optional`)	Mengunci kebijakan dua faktor ke `optional` atau `required`
`WEBAUTHN_RP_ID`	nama host permintaan	ID relying party tetap untuk passkey di balik banyak nama host
`VAPID_PUBLIC_KEY`	dibuat dan disimpan terenkripsi	Mengunci kunci publik VAPID Web Push (titik P-256 base64url)
`VAPID_PRIVATE_KEY`	dibuat dan disimpan terenkripsi	Mengunci kunci privat VAPID Web Push (skalar base64url)
`VAPID_SUBJECT`	`mailto:admin@localhost`	Klaim kontak dalam otorisasi Web Push bertanda tangan

Turnstile hanya diaktifkan ketika kedua kunci Turnstile tersedia.

ENABLE_SIGNUP=false tetap mengizinkan administrator lokal pertama pada database kosong, lalu memblokir akun lokal dan OAuth tambahan. Lindungi rute awal yang dapat dijangkau dari jauh dengan batas identitas luar sebelum proses mulai pertama.

Setiap JWT yang diterbitkan diikat pada sesi sisi server (klaim sid), sehingga keluar atau mencabut sesi dari Pengaturan → Sesi langsung membatalkan token pada setiap replika dan menutup koneksi WebSocket aktif. Retensi audit keamanan dapat dikonfigurasi:

Variabel	Bawaan	Tujuan
`AUDIT_RETENTION_DAYS`	`180`	Hari penyimpanan baris dalam log peristiwa audit keamanan

Single Sign-On OIDC Generik

Setiap penyedia OpenID Connect dengan dokumen penemuan dapat digunakan untuk login. Alur menggunakan PKCE (S256), keadaan CSRF, dan nonce yang diverifikasi di dalam token ID dengan tanda tangan terperiksa. Identitas ditautkan pada klaim sub yang stabil.

Variabel	Bawaan	Tujuan
`OIDC_ISSUER_URL`	tidak ditetapkan	URL dasar penerbit; penemuan diambil dari `<issuer>/.well-known/openid-configuration`
`OIDC_CLIENT_ID`	tidak ditetapkan	ID klien OAuth yang terdaftar pada penyedia
`OIDC_CLIENT_SECRET`	tidak ditetapkan	Rahasia klien OAuth
`OIDC_DISPLAY_NAME`	`Single Sign-On`	Label yang tampil pada tombol login
`OIDC_SCOPES`	`openid profile email`	Cakupan yang diminta
`OIDC_CALLBACK_URL`	`BASE_URL` + rute callback OIDC	URI pengalihan yang terdaftar pada penyedia
`OIDC_ALLOWED_EMAIL_DOMAINS`	tidak ditetapkan	Daftar dipisahkan koma; jika ditetapkan, email terverifikasi di salah satu domain wajib
`OIDC_GROUP_CLAIM`	`groups`	Klaim token ID yang memuat nama grup
`OIDC_ADMIN_GROUPS`	tidak ditetapkan	Daftar dipisahkan koma; jika ditetapkan, peran admin mengikuti keanggotaan klaim tiap login
`OIDC_SYNC_GROUPS`	`false`	`true` menyelaraskan keanggotaan grup Libre dengan klaim grup pada setiap login

OIDC hanya diaktifkan jika URL penerbit, ID klien, dan rahasia klien semuanya tersedia. Email yang sudah digunakan akun lokal tidak tertaut ditolak, bukan digabungkan diam-diam, dan pembuatan akun tetap mematuhi ENABLE_SIGNUP.

Penerimaan WebSocket Chat dapat disetel tanpa melemahkan autentikasi:

Variabel	Bawaan	Tujuan
`CHAT_WS_MAX_PAYLOAD_BYTES`	10 MiB	Ukuran pesan WebSocket maksimum yang diterima
`CHAT_WS_MAX_MESSAGES_PER_MINUTE`	`120`	Batas pesan WebSocket per koneksi
`CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER`	`4`	Pembuatan penyedia yang diizinkan per akun
`CHAT_WS_MAX_CONNECTIONS_PER_USER`	`5`	Soket terautentikasi bersamaan per akun
`WEBSOCKET_TICKET_TTL_MS`	`30000`	Masa berlaku tiket Chat/Work sekali pakai; maksimum 60 detik

Peramban menukar header Authorization normalnya dengan tiket buram dan hanya menempatkan nilai berumur singkat tersebut dalam URL peningkatan WebSocket. Tiket hanya dapat digunakan sekali, terikat protokol dan sesi, serta hanya disimpan sebagai hash. Dengan demikian, token sesi tahan lama tidak masuk ke log target-permintaan reverse proxy. Jika CORS_ORIGIN atau BASE_URL dikonfigurasi, peningkatan peramban dengan header Origin harus cocok dengan salah satu origin yang dikonfigurasi. Tetapkan sedikitnya satu pada deployment yang dapat dijangkau dari jauh; jika keduanya tidak dikonfigurasi, filter Origin bersifat permisif demi kompatibilitas pengembangan lokal. Peningkatan tanpa origin sengaja tetap didukung untuk Electron dan klien nonperamban, tempat kontrol Origin peramban tidak tersedia; klien tetap memerlukan tiket sekali pakai yang valid dan menerima pemeriksaan akun saat ini, akses Work, serta tugas yang sama. Perlakukan tiket sebagai batas autentikasi dan batasi akses nonperamban dengan kontrol TLS, firewall, dan reverse proxy normal deployment.

OAuth

Variabel	Tujuan
`GITHUB_CLIENT_ID`	ID klien GitHub OAuth
`GITHUB_CLIENT_SECRET`	Rahasia klien GitHub OAuth
`GITHUB_CALLBACK_URL`	Override URL callback GitHub
`HUGGINGFACE_CLIENT_ID`	ID klien Hugging Face OAuth
`HUGGINGFACE_CLIENT_SECRET`	Rahasia klien Hugging Face OAuth
`HUGGINGFACE_CALLBACK_URL`	Override URL callback Hugging Face

Jika URL callback tidak ditetapkan, Libre WebUI membuat nilai bawaan dari BASE_URL.

Ollama

Variabel	Bawaan	Tujuan
`OLLAMA_BASE_URL`	`http://localhost:11434`	URL dasar API Ollama
`OLLAMA_TIMEOUT`	`300000`	Batas waktu permintaan Ollama standar (1.000-3.600.000 ms)
`OLLAMA_LONG_OPERATION_TIMEOUT`	`900000`	Batas waktu operasi panjang (1.000-3.600.000 ms dan tidak lebih pendek dari `OLLAMA_TIMEOUT`)
`OLLAMA_MAX_CONTEXT`	`32768`	Konteks model maksimum yang diadopsi otomatis (128-2.097.152 token)

Pencarian Web

Variabel	Bawaan	Tujuan
`SEARXNG_URL`	tidak ditetapkan	Endpoint SearXNG bawaan untuk pengaturan pencarian web; admin tetap mengaktifkannya di Pengaturan > Pencarian

Libre Claw

Variabel	Bawaan	Tujuan
`LIBRE_CLAW_BASE_URL`	`http://127.0.0.1:8766`	URL daemon Libre Claw opsional
`LIBRE_CLAW_TIMEOUT_MS`	`30000`	Batas waktu permintaan HTTP Libre Claw

Runtime Work

Variabel berikut mengonfigurasi eksekusi Work pada mesin atau klaster Kubernetes yang menjalankan backend Libre WebUI. Docker adalah runtime bawaan; chart Helm memilih Kubernetes ketika work.enabled=true.

Variabel	Bawaan	Tujuan
`WORK_RUNTIME_IMAGE`	`node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3`	Image terkunci yang digunakan untuk sandbox Work
`WORK_DOCKER_COMMAND`	`docker`	Program CLI backend Docker yang tersedia bagi proses
`WORK_COMMAND_TIMEOUT_MS`	`120000`	Batas waktu bawaan; alat dapat meminta hingga `600000` ms
`WORK_MAX_OUTPUT_CHARS`	`50000`	Batas stdout/stderr yang ditangkap, diterapkan pada setiap aliran
`WORK_MAX_AGENT_ROUNDS`	`48`	Anggaran putaran model/alat yang tidak bergantung penyedia untuk satu proses
`WORK_STATUS_BLURB_MODEL`	`1`	Tetapkan `0` untuk melewati satu permintaan model yang menulis baris status agen di bilah samping setelah proses
`WORK_MEMORY_LIMIT`	`2g`	Batas memori yang diberikan kepada setiap kontainer Work
`WORK_CPU_LIMIT`	`2`	Batas CPU yang diberikan kepada setiap kontainer Work
`WORK_PIDS_LIMIT`	`256`	Batas proses yang diberikan kepada setiap kontainer Work
`WORK_PREVIEW_PORT`	`4173`	Port yang harus digunakan server pratinjau di dalam kontainer tugas
`WORK_PREVIEW_BIND`	`127.0.0.1`	Antarmuka host tempat port pratinjau tugas diterbitkan; deployment Compose pada Docker Engine native harus memakai antarmuka bridge non-publik yang dapat dijangkau
`WORK_DOCKER_PUBLISHED_HOST`	bawaan aplikasi: sama dengan `WORK_PREVIEW_BIND`; bawaan Compose: `host.docker.internal`	Host/IP yang dilihat backend untuk port pratinjau, layar, dan audio terbitan Docker
`WORK_COMPUTER_SCREEN_PORT`	`6080`	Port kontainer jembatan layar Work Computer (websockify) dalam sandbox ber-GUI
`WORK_COMPUTER_AUDIO_PORT`	`6081`	Port kontainer jembatan audio Work Computer (websockify → monitor PulseAudio) dalam sandbox ber-GUI
`WORK_MAX_ACTIVE_RUNTIMES_GLOBAL`	`3`	Tugas berbasis runtime bersamaan untuk seluruh instans
`WORK_MAX_ACTIVE_RUNTIMES_PER_USER`	`2`	Tugas berbasis runtime bersamaan untuk satu pengguna
`WORK_MAX_TASKS_GLOBAL`	`500`	Tugas Work persisten maksimum untuk seluruh instans
`WORK_MAX_TASKS_PER_USER`	`100`	Tugas Work persisten maksimum untuk satu administrator
`WORK_NETWORK_NAME`	`libre-webui-work`	Jaringan bridge sandbox terkelola untuk tugas berjejaring
`WORK_RUN_LEASE_WAIT_MS`	`60000`	Lama proses menunggu sewa runtime bersama tugas sebelum melaporkan konflik replika (mode team)
`WORK_RUNTIME_DNS`	tidak ditetapkan	IP resolver dipisahkan koma yang dipaksakan pada tugas berjejaring
`WORK_DOCKER_SOCKET`	`DOCKER_HOST` jika `unix://` atau `tcp://`, selain itu `/var/run/docker.sock`	Endpoint Docker Engine untuk terminal dan diagnostik
`WORK_TERMINAL_MAX_SESSIONS_PER_TASK`	`2`	Terminal peramban bersamaan yang terhubung ke satu tugas
`WORK_TERMINAL_IDLE_TIMEOUT_MS`	`900000`	Batas waktu diam sebelum sesi terminal ditutup
`WORK_RUNTIME_IDLE_TIMEOUT_MS`	`0` (dinonaktifkan)	Menghentikan sandbox setelah durasi tanpa aktivitas ini (termasuk pratinjau)
`WORK_HOST_WORKSPACES_ENABLED`	`false`	Mengizinkan tugas memakai folder host alih-alih volume
`WORK_HOST_WORKSPACE_ROOTS`	direktori home pengguna server	Root dipisahkan `:` yang harus menaungi ruang kerja host
`WORK_RUNTIME_BACKEND`	`docker`	Backend sandbox: `docker` atau `kubernetes`
`WORK_K8S_NAMESPACE`	`libre-webui-work`	Namespace yang memuat Pod dan PVC sandbox Kubernetes
`WORK_K8S_STORAGE_CLASS`	bawaan klaster	StorageClass untuk PVC ruang kerja
`WORK_K8S_WORKSPACE_SIZE`	`5Gi`	Ukuran PVC ruang kerja per tugas (kuota disk nyata)
`WORK_K8S_POD_READY_TIMEOUT_MS`	`900000`	Waktu menunggu Pod sandbox mencapai Running (mencakup pengunduhan)
`WORK_K8S_POD_GONE_TIMEOUT_MS`	`60000`	Waktu menunggu Pod sandbox yang dihapus menghilang
`AGENT_CLI_MODELS_ENABLED`	tidak ditetapkan (sakelar admin, nonaktif)	Mengunci fitur Agen aktif/nonaktif; tanpa nilai mengikuti sakelar admin di Pengelolaan Pengguna (bawaan nonaktif)
`TOOLS_ACCESS_MODE`	tidak ditetapkan (sakelar admin, khusus admin)	Mengunci alat chat ke `admins` atau `all-users` dan mengunci sakelar admin di Pengelolaan Pengguna
`STT_ACCESS_MODE`	tidak ditetapkan (sakelar admin, semua pengguna)	Mengunci ucapan-ke-teks ke `admins` atau `all-users` dan mengunci sakelar admin di Pengelolaan Pengguna
`TTS_ACCESS_MODE`	tidak ditetapkan (sakelar admin, semua pengguna)	Mengunci teks-ke-ucapan ke `admins` atau `all-users` dan mengunci sakelar admin di Pengelolaan Pengguna
`VOICE_MODE_ACCESS_MODE`	tidak ditetapkan (sakelar admin, semua pengguna)	Mengunci mode suara bebas genggam ke `admins` atau `all-users` dan mengunci sakelar admin di Pengelolaan Pengguna
`VOICE_CLONING_ACCESS_MODE`	tidak ditetapkan (sakelar admin, semua pengguna)	Mengunci kloning suara ke `admins` atau `all-users` dan mengunci sakelar admin di Pengelolaan Pengguna
`TOOLS_PRIVATE_NETWORK_ALLOWLIST`	tidak ditetapkan	Nama host persis yang boleh diresolusi server alat dan target webhook ke alamat privat (dipisahkan koma); dikunci
`AGENT_CLI_TIMEOUT_MS`	`600000`	Waktu CLI agen boleh berjalan sebelum dihentikan
`CODEX_OAUTH_MODELS_ENABLED`	`true`	Menawarkan penyedia Codex (ChatGPT) kepada admin
`CODEX_HOME`	`~/.codex`	Lokasi pembacaan login CLI Codex (`auth.json`)

Biner CLI agen dan kredensial Codex OAuth bersifat lokal-node. Keduanya hanya didukung dalam proses solo, tempat penemuan dan eksekusi melihat sistem berkas serta lingkungan yang sama. Mode team mengeksekusi pekerjaan chat tahan lama dalam worker eksternal, sehingga mengharuskan AGENT_CLI_MODELS_ENABLED=false dan CODEX_OAUTH_MODELS_ENABLED=false; proses mulai menolak nilai lain, bukan mengiklankan penyedia yang mungkin hanya tersedia pada satu replika aplikasi. Gunakan Ollama atau plugin penyedia yang kredensial dan peruteannya disimpan dalam PostgreSQL bersama atau diteruskan secara identik ke setiap aplikasi dan worker.

Pada backend Docker, ruang kerja host melakukan bind-mount direktori nyata di /workspace, sehingga tugas dapat membaca dan menulis berkas tersebut secara langsung alih-alih bekerja dalam volume Docker tersendiri. Kubernetes menolak ruang kerja folder host. Ini sengaja mengurangi perlindungan sandbox Docker: biarkan WORK_HOST_WORKSPACES_ENABLED nonaktif kecuali memang diinginkan, dan jaga WORK_HOST_WORKSPACE_ROOTS sesempit mungkin. Jalur yang diminta diselesaikan melalui symlink sebelum diperiksa terhadap root, dan folder seperti .ssh, .gnupg, .aws, serta .config ditolak sepenuhnya.

Model CLI agen mengekspos agen pemrograman yang sudah terinstal pada server (claude, codex) sebagai model chat yang dapat dipilih, sehingga agen berlangganan dapat menjawab tanpa kunci API. Hanya administrator yang melihatnya, CLI berjalan sebagai pengguna server Libre WebUI, dan mewarisi kredensial agen milik pengguna tersebut—perlakukan sebagai setara dengan memberikan akses shell kepada agen itu.

Di Docker, tugas Work berjejaring terhubung ke bridge WORK_NETWORK_NAME terkelola, yang dibuat dengan komunikasi antarkontainer dinonaktifkan agar satu sandbox tidak dapat menjangkau sandbox lain atau kontainer milik deployment. WORK_RUNTIME_DNS adalah kait kebijakan egress Docker yang didukung: arahkan ke resolver pemfilter untuk menerapkan daftar izin/tolak berbasis nama. Entri yang bukan alamat IPv4/IPv6 ditolak dan dicatat. Pemfilteran DNS tidak membatasi egress IP langsung; tambahkan aturan firewall host jika deployment memerlukannya. Backend Kubernetes menggunakan NetworkPolicy tolak-bawaan milik chart dan nilai work.networkPolicy.blockedEgressCidrs.

Di Docker, terminal interaktif dan diagnostik sistem berkomunikasi langsung dengan API Docker Engine. Keduanya mengikuti WORK_DOCKER_SOCKET jika ditetapkan, lalu DOCKER_HOST—baik soket unix:// maupun endpoint tcp:// HTTP biasa seperti proksi soket (lihat docker-compose.socket-proxy.yml)—atau /var/run/docker.sock. DOCKER_HOST yang tidak dapat digunakan klien ini (ssh://, atau tcp:// dengan DOCKER_TLS_VERIFY ditetapkan) membuat terminal dan diagnostik Docker dilaporkan tidak tersedia; bagian Work lainnya tetap berjalan melalui CLI Docker, yang memahami endpoint tersebut sendiri. Pada Kubernetes, terminal menggunakan subsumber daya exec Pod dan tidak memakai endpoint Docker.

Work membaca nilai ini saat backend dimulai. Port pratinjau bersifat internal bagi kontainer tugas; Libre WebUI menerbitkannya ke port loopback yang ditetapkan dinamis, bukan mengekspos nilai ini secara langsung pada setiap antarmuka host.

Kunci image runtime pada versi atau digest yang telah ditinjau. Menaikkan konkurensi atau batas sumber daya meningkatkan kapasitas runtime yang dapat digunakan satu atau beberapa proses otonom. WORK_MAX_AGENT_ROUNDS berlaku sama pada proses berbasis Ollama dan plugin; tidak ada batas bawah khusus plugin. Anggaran keamanan panggilan alat adalah max(128, WORK_MAX_AGENT_ROUNDS × 8). Ketika proses menghabiskan anggaran putarannya, Work meminta penyerahan akhir tanpa alat dari model dan berakhir dalam keadaan terminal needs_input, bukan mengembalikan kesalahan batas putaran mentah atau mengklaim selesai. Proses lanjutan meneruskan dalam ruang kerja tahan lama yang sama. Keluaran alat persisten memiliki batas terpisah sekitar 20.000 karakter sumber ditambah penanda pemotongan.

Variabel berikut menyetel runtime Work yang sudah dapat dijangkau. Deployment Compose satu instans dari repositori mengaktifkannya secara bawaan: image menyertakan CLI Docker dan berkas Compose tersebut memasang soket Docker host. Dua variabel tingkat Compose mengontrol sambungan ini:

Variabel	Bawaan	Tujuan
`DOCKER_GID`	`0`	ID grup soket Docker host, ditambahkan ke pengguna kontainer
`DOCKER_SOCKET`	`/var/run/docker.sock`	Jalur host soket Docker yang akan dipasang

DOCKER_GID harus berupa grup soket sebagaimana terlihat dari dalam kontainer; host macOS melaporkan nilai berbeda. Dasar Compose team tidak memasang soket dan membuat Work berbasis Docker tidak tersedia sampai docker-compose.team.work.yml ditambahkan. Overlay produksi tersebut memberi aplikasi dan worker endpoint proksi terfilter internal yang sama, tidak pernah mount atau grup soket. Proksi hanya mengizinkan bagian API Docker yang digunakan runtime, tetapi pembuatan kontainer tetap merupakan kredensial kontrol host Docker; gunakan daemon Work khusus atau tanpa root untuk batas yang lebih kuat. Chart Helm tidak pernah memasang soket runtime node. Aktifkan backend Work Pod/PVC native dengan work.enabled=true.

Profil solo harus tetap memiliki nol atau satu replika aplikasi karena menggunakan SQLite, berkas lokal, dan koordinasi lokal-proses. Chart Helm menerima nol untuk penangguhan disengaja dan menolak jumlah replika solo yang lebih besar atau penskalaan otomatis solo. Profil team lengkap dapat memakai beberapa replika aplikasi dan worker eksternal karena PostgreSQL, S3, PGVector, serta Redis memiliki keadaan bersama. Pod sandbox Work diskalakan secara independen dalam kedua profil; dalam mode team, worker eksternal menerima image runtime Kubernetes, StorageClass, dan batas work.env yang sama dengan pod aplikasi.

Berkas Compose repositori juga menerima WEBUI_BIND_ADDRESS (bawaan 127.0.0.1) dan WEBUI_PORT (bawaan 8080). Pertahankan loopback bawaan kecuali LAN tepercaya atau reverse proxy host harus menjangkau port tersebut.

Penemuan Model Penyedia

Katalog model penyedia ditemukan ulang secara otomatis jika hilang atau usang, sehingga pemuatan ulang mencerminkan model yang saat ini dilayani penyedia. Variabel berikut menyetel siklus tersebut:

Variabel	Bawaan	Tujuan
`PLUGIN_MODEL_DISCOVERY_TTL_MS`	`21600000` (6 jam)	Usia saat katalog tersimpan disegarkan pada pembacaan daftar plugin berikutnya
`PLUGIN_MODEL_DISCOVERY_RETRY_MS`	`600000` (10 menit)	Jeda minimum antarupaya agar penyedia gagal tidak sering diperiksa
`PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS`	`3000`	Lama respons daftar plugin menunggu penyegaran sebelum menjawab

Penyegaran yang melampaui tenggat tetap selesai dan disajikan pada permintaan berikutnya. Segarkan model yang eksplisit selalu menghubungi penyedia dan mengabaikan interval.

Kunci Plugin Penyedia

Plugin penyedia dapat menggunakan kunci lingkungan sebagai nilai bawaan seluruh deployment:

Variabel	Penyedia
`OPENAI_API_KEY`	OpenAI dan OpenAI TTS
`ANTHROPIC_API_KEY`	Anthropic
`GROQ_API_KEY`	Groq
`GEMINI_API_KEY`	Google Gemini
`MISTRAL_API_KEY`	Mistral
`OPENROUTER_API_KEY`	OpenRouter
`KIMI_API_KEY`	Kimi Code dari Moonshot AI
`GITHUB_API_KEY`	GitHub Models
`HUGGINGFACE_API_KEY`	API Hugging Face jika dikonfigurasi
`ELEVENLABS_API_KEY`	ElevenLabs TTS
`COMFYUI_API_KEY`	Deployment ComfyUI yang memerlukan kunci API

Pengguna juga dapat menyimpan kredensial penyedia dalam UI jika kunci per pengguna lebih diutamakan. Kunci lingkungan hanya digunakan dengan proyeksi perutean dan autentikasi dari definisi terpaket yang tidak dibayangi. Definisi impor, definisi dapat-tulis yang memakai ulang ID terpaket, dan rute khusus tersimpan administrator memerlukan kredensial yang disimpan akun tersebut. Libre WebUI tidak akan memasang kunci lingkungan pada rute tersebut atau mengeksposnya melalui pemeriksaan penemuan dan ketersediaan. Kepercayaan berasal dari hash terkompilasi setiap manifes yang dikirim, sehingga tata letak kontainer tempat direktori plugin lama dan terpaket berbagi jalur tetap didukung tanpa menganggap manifes yang diubah sebagai terpaket.

Kunci tersimpan pengguna diikat pada definisi penyedia efektif, sumber, kontrak autentikasi, dan nilai perutean. Pengguna harus menyimpan kembali kunci setelah administrator mengubah tujuan tersebut. Kunci tanpa ikatan sebelum peningkatan hanya diterima dan diikat pada penggunaan pertama untuk definisi kiriman yang persis menggunakan rute terpaketnya.

Untuk peluncuran dari sumber, nilai relatif PLUGINS_DIR diselesaikan dari direktori backend. Peluncur terpaket mengubah nilai relatif yang dikonfigurasi eksplisit menjadi jalur absolut-pemanggil sebelum memulai backend. Demi kompatibilitas, Libre juga membaca direktori deterministik backend/plugins dan lokasi historis yang dipilih konfigurasi sebelumnya. Pindahkan definisi tersebut ke $DATA_DIR/plugins; pemulihan melaporkan jalur lama sebagai keadaan eksternal dan memblokir snapshot khusus-volume selama definisi khusus tetap di sana. Direktori plugin dan definisi JSON harus berupa entri fisik biasa—Libre tidak mengikuti symlink plugin.

Frontend

Variabel	Bawaan	Tujuan
`VITE_API_BASE_URL`	proksi pengembangan origin-sama atau API produksi	URL dasar API frontend
`VITE_WS_BASE_URL`	disimpulkan dari URL API	Dasar `ws:`/`wss:` absolut untuk soket Chat dan Work
`VITE_APP_VERSION`	versi paket yang disuntikkan konfigurasi Vite	Versi aplikasi yang ditampilkan
`VITE_DEMO_MODE`	`false`	Mengaktifkan tiruan mode demo jika `true`
`VITE_API_TIMEOUT`	`300000`	Batas waktu API frontend dalam milidetik
`VITE_BACKEND_URL`	`http://localhost:3001`	Digunakan sebagian komponen pembantu autentikasi
`VITE_DEBUG_VERBOSE`	tidak ditetapkan	Mengaktifkan log debug frontend terperinci dalam pengembangan
`VITE_LOG_LEVEL`	tidak ditetapkan	Mengganti tingkat log frontend
`ELECTRON_BUILD`	tidak ditetapkan	Mengaktifkan perilaku Vite khusus Electron jika `true`

VITE_WS_BASE_URL mengganti setiap fallback WebSocket bagi Chat dan terminal Work. Nilai ini boleh memuat prefiks jalur reverse proxy, tetapi harus berupa URL ws: atau wss: absolut tanpa kredensial, kueri, atau fragmen. Jika tidak ditetapkan, klien Electron file: menggunakan ws://localhost:3001; klien peramban menurunkan dasarnya dari VITE_API_BASE_URL, lalu origin peramban. Vite mem-proksi origin pengembangan ke backend pada port 3001.

Skrip Pemeliharaan

Variabel	Tujuan
`CHANGELOG_AI`	Tetapkan `0` untuk menonaktifkan draf changelog berbantuan AI
`CHANGELOG_AI_MODEL`	Model Ollama untuk pembuatan rilis/changelog
`CHANGELOG_AI_TIMEOUT_MS`	Batas waktu pembuatan changelog AI dalam milidetik

Contoh:

CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor

Contoh Produksi

NODE_ENV=production
PORT=3001
SERVE_FRONTEND=true
DATA_DIR=/data/libre-webui
CORS_ORIGIN=https://librewebui.example
BASE_URL=https://librewebui.example

JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
ENABLE_SIGNUP=false

OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_TIMEOUT=300000
OLLAMA_LONG_OPERATION_TIMEOUT=900000
OLLAMA_MAX_CONTEXT=32768

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=librewebui.example

Server Backend​

Fondasi Platform​

Pembantu Cadangan Privat​

Autentikasi dan Keamanan​

Single Sign-On OIDC Generik​

OAuth​

Ollama​

Pencarian Web​

Libre Claw​

Runtime Work​

Penemuan Model Penyedia​

Kunci Plugin Penyedia​

Frontend​

Skrip Pemeliharaan​

Contoh Produksi​

Dokumentasi Terkait​