Jinsi ya ku-host Supabase kwenye VPS kwa Docker

Unachojenga

Self-hosting ya Supabase inamaanisha kuendesha stack rasmi ya Docker Compose kwenye seva yako mwenyewe: Postgres, REST API inayoiwekea mbele, huduma ya uthibitishaji (auth), hifadhi ya faili, realtime websockets, na dashibodi ya Studio. Unaclonerepository moja, unahariri faili moja ya .env, na kuanzisha takriban container kumi na nne ambazo kwa pamoja hufanya kazi kama mradi wa Supabase unaouhibiti wewe.

Ufungaji ni mfupi. Sehemu inayoweza kwenda vibaya ni faili ya .env. Inakuja na demo secrets zilizochapishwa kwenye repository, na stack ikianzishwa kwa kutumia default hizo inakuwa wazi kwa yeyote atakayeipata. Mwongozo huu unaelezea secrets unazopaswa kubadilisha, kazi ya kila huduma, kiasi cha kumbukumbu (memory) ambacho stack inahitaji kweli, na jinsi ya kuifanyia update bila kufuta database yako.

Ikiwa Compose yenyewe ni ngeni kwako, soma Misingi ya Docker Compose kwenye VPS kwanza. Kila kitu hapa chini kinachukulia kuwa docker compose version tayari inatoa toleo (version).

Yaliyomo kwenye stack hii

Supabase si programu moja. Faili la Compose huanzisha seti ya huduma tofauti kwenye mtandao mmoja, na kuelewa kila huduma ni nini hubadilisha orodha ya majina ya container kuwa kitu unachoweza kukifanyia debugging.

• db ni PostgreSQL iliyo na extensions za Supabase zilizopakiwa. Kila huduma nyingine huwasiliana nayo. Ikiwa container hii haifanyi kazi vizuri, kila kitu kingine kitafeli pia.
• kong ni API gateway. Inasikiliza kwenye port 8000 na kuelekeza /rest/v1/, /auth/v1/ na /storage/v1/ kwenye backend sahihi. Hii ndiyo container pekee unayopaswa kuifungua kwa umma.
• rest ni PostgREST. Inasoma schema yako ya Postgres na kuitoa kama REST API, hivyo table mpya inakuwa endpoint mpya bila kuhitaji code yoyote.
• auth ni GoTrue. Inatoa JSON web tokens (JWT) zinazotambulisha watumiaji wako.
• storage na imgproxy hushughulikia upakiaji wa faili na kubadilisha ukubwa wa picha.
• realtime hutiririsha mabadiliko ya database kupitia websockets.
• studio na meta ni dashboard na admin API iliyo nyuma yake.
• analytics (Logflare) na vector hukusanya logi, na supavisor ni Postgres connection pooler.

Orodha hiyo ndiyo sababu ya namba za rasilimali zilizotajwa hapa chini kuwa vile zilivyo. Huendeshi database pekee. Unaendesha database pamoja na huduma nyingine kumi na mbili za usaidizi.

Ukubwa: panga kuwa na 8 GB ya RAM

Stack hii hutumia takriban 2.5 hadi 3 GB ya kumbukumbu ya resident ikiwa imesakinishwa upya, kufikia Julai 2026, kabla ya kuongeza data yako au trafiki. Huduma ya analytics na mchakato wa Studio Node.js ndio watumiaji wakubwa zaidi. Seva ya 2 GB itaanza containers kisha itapoteza moja kupitia kernel out of memory killer, kwa kawaida analytics au db, na dalili yake ni container kukwama ikijianzisha upya na exit code 137.

Tenga 8 GB ya RAM na 4 vCPU kwa chochote unachokitegemea. 4 GB inafaa kwa instance ya maendeleo ya mtu mmoja ikiwa utakubali kuwa query nzito na session ya Studio kwa wakati mmoja vitakuwa polepole. Disk pia ni muhimu, kwa sababu Postgres, storage volume na data ya log zote hukaa chini ya saraka ya mradi. Anza na 40 GB na uifuatilie. Kuhesabu huduma kabla ya kuchagua mpango ni tabia nzuri ya kuzingatia kwa chochote unachojiendeshea mwenyewe, kwa kuwa PhotoPrism na Immich zina viwango vya chini vya RAM vilivyo juu zaidi ya vile kurasa zao za kuanza haraka zinavyodokeza.

Usakinishaji: clone repository rasmi

Njia inayopendekezwa ni kunakili saraka ya docker kutoka kwenye repository kuu kwenda kwenye saraka ya mradi wako. Utengano huu ni muhimu, kwa sababu unamaanisha kuwa git pull ya baadaye haiwezi kufuta na kuandika juu ya .env yako.

git clone --depth 1 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/* supabase-project
cp supabase/docker/.env.example supabase-project/.env
cd supabase-project
docker compose pull

docker compose pull hupakua gigabytes kadhaa za images. Inapaswa kumalizika huku kila huduma ikiwa imewekwa alama ya Pulled. Hitilafu ya manifest unknown hapa inamaanisha kuwa tag ya image iliyokuwa imefungwa imeondolewa kwenye chanzo, na suluhisho ni kupakua nakala mpya ya repository badala ya kuhariri tags kwa mkono.

Siri unazopaswa kuzibadilisha kabla ya kuanza kwa mara ya kwanza

Fanya hivi kabla ya kuanza stack, siyo baada ya hapo. Baadhi ya thamani hizi huandikwa kwenye data wakati wa boot ya kwanza, kwa hivyo kuzibadilisha baadaye kunamaanisha kuweka upya database.

Repository hii inakuja na jenereta inayozalisha kila thamani kwa usahihi, ikiwemo funguo mbili za API ambazo lazima zisainiwe kwa siri yako mpya ya JWT.

sh utils/generate-keys.sh --update-env

Script hiyo huandika thamani mpya kwa ajili ya JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY, SECRET_KEY_BASE, REALTIME_DB_ENC_KEY, VAULT_ENC_KEY, PG_META_CRYPTO_KEY na token za Logflare ndani ya .env. Inahitaji openssl, ambayo inapatikana kwenye image yoyote ya kawaida ya Ubuntu.

Thamani mbili ambazo haiziweki, na lazima uzihariri kwa mkono ndani ya .env, ni:

• POSTGRES_PASSWORD. Tumia herufi na namba pekee. Alama za uandishi hapa huvunja connection strings ambazo huduma kadhaa hujenga kwa kuunganisha maneno, na hitilafu hiyo huonekana kama tatizo la uthibitishaji (authentication error) badala ya tatizo la uchanganuzi (parsing error), jambo linalowafanya watu kutafuta suluhisho mahali pasipofaa.
• DASHBOARD_USERNAME na DASHBOARD_PASSWORD. Hizi ni sifa za uthibitishaji (credentials) za msingi kwa ajili ya Studio. Nenosiri chaguo-msingi lililopo ni this_password_is_insecure_and_should_be_updated.

Elewa kwa nini ANON_KEY na SERVICE_ROLE_KEY haziwezi kubuniwa. Zote ni JWT zilizosainiwa kwa JWT_SECRET. Gateway huthibitisha sahihi hiyo kwenye kila ombi, kwa hivyo ufunguo usiolingana na siri yako hukataliwa kwa {"message":"Invalid authentication credentials"}. Hili ndilo tatizo la kawaida zaidi katika self-hosting: mwendeshaji alibadilisha JWT_SECRET lakini akaacha funguo za demo. Zalisha zote tatu kwa pamoja, kila wakati.

Ichukulie SERVICE_ROLE_KEY kama nenosiri la root. Inapita usalama wa kiwango cha safu (row level security) kabisa. Inapaswa kuwa kwenye msimbo wa upande wa seva (server side code) na si mahali pengine popote.

Weka SITE_URL na API_EXTERNAL_URL kwenye anwani ambayo watumiaji wako wataifikia kihalisi, kwa mfano https://supabase.example.com. Auth hujenga viungo vyake vya uthibitishaji wa barua pepe na callback za OAuth kutokana na thamani hizo, kwa hivyo kuziacha zikiwa http://localhost:8000 kutawapeleka watumiaji wako wote kwenye mashine zao wenyewe.

Kisha kagua ulichonacho:

sh run.sh secrets

Anzisha huduma na uhakikishe iko katika hali nzuri

sh run.sh start
docker compose ps

run.sh start inafunga docker compose up -d --wait, kwa hivyo hairejeshi udhibiti hadi ukaguzi wa afya (health checks) utakapokamilika. Kila huduma inapaswa kuonyesha running (healthy) au running. Boot ya kwanza huchukua dakika mbili hadi nne kwa sababu Postgres huendesha hati zake za awali (initialisation scripts) kabla ya kitu kingine chochote kuweza kuunganishwa.

Ikiwa container inajianzisha upya, soma logi zake kwa kutumia jina la huduma:

docker compose logs db
docker compose logs auth

Studio itakuwa kwenye port 8000, na itakuomba jina la mtumiaji (username) na nenosiri (password) la dashboard ulivyoweka.

Usifungue port 8000 kwenye mtandao wa umma

Kong kwenye port 8000 hutumia HTTP ya kawaida. Kila API key na kila password ya mtumiaji hupita kwenye mtandao bila kusimbwa, na vitambulisho vya Studio hutumia basic authentication, ambayo ni base64 encoding badala ya encryption.

Weka reverse proxy mbele yake, malizia TLS (transport layer security) hapo, na ufunge Kong kwenye loopback address ili huduma nyingine zisiweze kuifikia. Katika docker-compose.yml, ramani ya port ya kong inakuwa 127.0.0.1:8000:8000, na proxy hupeleka maombi huko. Traefik mbele ya programu kadhaa za Compose inaelezea upande wa cheti.

Funga sehemu nyingine kwenye firewall pia, kwa sababu Docker huchapisha ports kwa kuandika sheria zake za iptables ambazo usanidi wa kawaida wa ufw hauzioni. Mtego huo unafafanuliwa katika kwa nini Docker containers hupuuza sheria zako za ufw.

Hifadhi nakala ya database, siyo saraka

Data ya Postgres hukaa kwenye bind mount katika ./volumes/db/data. Kunakili saraka hiyo wakati container inaendelea kufanya kazi kutakupa nakala isiyo kamili (torn copy), kwa sababu Postgres huhifadhi data kwenye buffer na faili zilizopo kwenye diski huwa katika hali sahihi tu wakati wa checkpoint. Kurejesha nakala hiyo kwa kawaida kutafanikiwa, lakini wakati mwingine kutapoteza miamala ya mwisho kimyakimya, hali ambayo ni mbaya zaidi kwa nakala ya usalama.

Tumia dump badala yake. pg_dumpall hufanya kazi ndani ya container na kuzalisha snapshot iliyo sahihi:

docker exec -t supabase-db pg_dumpall -U postgres > supabase-$(date +%F).sql

Hakikisha faili si tupu kabla ya kuitegemea. Kisha hamisha dump hizo nje ya seva kwa ratiba maalum, jambo ambalo ndilo kusudi la nakala za usalama zilizosimbwa nje ya tovuti kwa kutumia restic. Hifadhi nakala ya .env yako wakati huo huo. Kupoteza JWT_SECRET kunamaanisha kila token iliyotolewa itakuwa batili na kila siri iliyohifadhiwa kwa njia ya usimbaji haitasomeka.

Faili zilizopakiwa hukaa katika ./volumes/storage, na hizo ni faili za kawaida, kwa hivyo kunakili kwa njia ya kawaida ni sawa.

Kusasisha bila kupoteza data

Supabase huweka image versions katika docker-compose.yml, kwa hiyo hakuna kinachobadilika hadi wewe ubadilishe. Pinning inafaa kuigwa katika stack yoyote unayounda mwenyewe. Ndiyo maana relay ya RustDesk inayojihudumia huweka server images zake mbili kwenye versions maalum badala ya kufuata moving tag. Upgrade inapaswa kuwa jambo unalochagua asubuhi ambayo una muda wa kuishughulikia. Kwanza tengeneza dump kila mara.

docker compose pull
sh run.sh recreate

recreate husimamisha stack na kuianzisha tena kwa kutumia image mpya. Data yako inabaki salama kwa sababu imehifadhiwa kwenye bind mounts za host, si ndani ya container. Soma CHANGELOG.md katika repository kabla ya kuruka toleo kubwa (major version), kwa sababu upgrades za Postgres hazifanyiki kiotomatiki na zinahitaji dump na restore.

Ili kupata mabadiliko ya faili ya Compose yenyewe, clone repository ya upstream tena na unakili saraka yake ya docker juu ya mradi wako, ukiwa mwangalifu usifute .env.

Uwekaji upya kamili (full reset), ambao huharibu kila kitu ikiwemo database, ni script tofauti na huomba uthibitisho:

sh reset.sh

FAQ

Kwa nini maombi yangu ya API yanarejesha "Invalid authentication credentials"?

ANON_KEY yako au SERVICE_ROLE_KEY yako haikusainiwa kwa kutumia JWT_SECRET iliyo kwenye .env kwa sasa. Lango (gateway) huhakiki sahihi ya kila ombi na kukataa kama kuna tofauti. Tengeneza upya vyote vitatu kwa kutumia sh utils/generate-keys.sh --update-env, kisha endesha sh run.sh recreate ili huduma zisome thamani mpya.

Je, ninaweza kuendesha Supabase iliyojihost kwenye VPS ya 2 GB?

Si kwa uhakika. Stack hii hutumia takriban 3 GB ikiwa haifanyi kazi kufikia Julai 2026 kwa sababu inaendesha huduma kumi na nne, hivyo seva ya 2 GB itapoteza containers kutokana na out of memory killer na utaona exit code 137 kwenye docker compose ps. Tumia 8 GB kwa ajili ya uzalishaji na 4 GB kama kiwango cha chini kwa ajili ya maendeleo ya mtu binafsi.

Je, Supabase iliyojihost inajumuisha edge functions?

Ndiyo. Faili ya Compose inajumuisha runtime ya functions inayotegemea Deno, na inahudumia chochote unachoweka chini ya ./volumes/functions. Haijumuishi mtandao wa usambazaji wa kimataifa wa jukwaa lililohostiwa, kwa hivyo functions zako zinaendeshwa kwenye seva yako moja, katika eneo moja.

Ninaunganishaje kwenye database ya Postgres moja kwa moja?

Tumia docker exec -it supabase-db psql -U postgres kwa ajili ya shell ya maingiliano kwenye seva yenyewe. Kwa mteja wa nje, unganisha kupitia Supavisor kwenye port 5432 ukitumia mtumiaji postgres.<POOLER_TENANT_ID> na POSTGRES_PASSWORD yako. Usifungue port hiyo kwenye Internet. Ifikie kupitia VPN au SSH tunnel.

Kwa nini viungo vya barua pepe za uthibitishaji wa auth vilielekeza kwenye localhost?

SITE_URL na API_EXTERNAL_URL katika .env ziliachwa kwenye thamani zake za awali (defaults). Huduma ya auth hujenga kila kiungo cha uthibitishaji na kuweka upya nenosiri kutoka kwa thamani hizo mbili, kwa hivyo hutuma anwani iliyoambiwa itume. Weka zote mbili kwenye URL yako halisi ya umma na uunde upya stack hiyo.