Jinsi ya kutumia Halcyon na Jellyfin kama duka la kanda

Jinsi Halcyon inavyoshughulikia maktaba yako ya Jellyfin

Halcyon Video inabadilisha maktaba yako ya Jellyfin kuwa duka la kanda la miaka ya 1990 unaloweza kutembea ndani yake kupitia kivinjari. Kila filamu uliyonayo inakuwa kama kasha kwenye rafu. Unatembea kwenye njia za kati chini ya taa za neon, unashusha kasha, unaligeuza ili kusoma maelezo yaliyo nyuma, na unalibeba hadi kwenye kaunta ili kuanza kucheza filamu. Taarifa za kuanza, maendeleo, na kusitisha filamu hurudishwa kwenye Jellyfin, hivyo sehemu ulipoishia na historia ya kutazama hubaki sahihi.

Halcyon inasoma seva ya Jellyfin iliyopo kupitia Jellyfin API na haihifadhi maktaba yake yenyewe. Mwongozo huu unachukulia kuwa Jellyfin tayari inafanya kazi na inachanganua maudhui vizuri. Ikiwa sivyo, sanidi Jellyfin kama seva ya media kwenye VPS kwanza na urudi mara tu maktaba yako itakapoonekana vizuri kwenye client ya kawaida ya wavuti. Hii ni aina ya programu unayoisakinisha kwa sababu maktaba tayari ipo, si kwa sababu ulihitaji huduma nyingine kwenye orodha yako ya self-hosting.

Mradi huu una leseni ya GPL-3.0 na umeandikwa na mtu mmoja, na README inasema wazi kuwa haikubali pull requests. Maendeleo yanaenda kwa kasi na hakuna msimamizi wa pili wa kurekebisha makosa yanayoweza kujitokeza, kwa hivyo funga (pin) toleo la image kabla ya kuonyesha duka hilo kwa mtu mwingine yeyote. Sehemu ya mwisho inaelezea jinsi ya kufanya hivyo.

Utoaji wa picha (rendering) hufanyika wapi?

Hufanyika kwenye kivinjari. Halcyon ni programu ya Vite na TypeScript iliyojengwa kwa kutumia three.js, maktaba ya JavaScript inayochora michoro ya 3D kupitia WebGL (web graphics library, kiolesura cha kivinjari kuelekea GPU). Jiometri ya duka na picha za boksi huunganishwa na mashine inayoshikilia skrini.

Container hufanya kazi kidogo sana. Inaendesha npm run serve, ambayo ni vite preview --port 1420 --strictPort --host, na kuhudumia faili zilizojengwa pamoja na njia chache ndogo za middleware. Halcyon haiongezi transcoding yoyote na haiendeshi injini yoyote kwenye seva.

Kwa hivyo, swali la GPU linahusu mteja. VPS ndogo inaweza kuhudumia hili kwa urahisi, kwa sababu kuhudumia huku kunamaanisha faili tuli kupitia HTTP. Kompyuta ya mkononi, kompyuta kibao au televisheni inayoendesha kivinjari ndiyo inayoamua kama duka linasonga vizuri au linasua.

Kipengele kimoja huvunja kanuni hiyo. Remote Play huunda mifano ya Chromium isiyo na kiolesura (headless) kwenye seva na kutiririsha duka lililotolewa kwenye simu au set top box kupitia WebRTC (web real time communication). Njia hiyo hutoa picha kwenye seva, ikiwa na kikomo cha mifano miwili kwa chaguo-msingi na inayoweza kurekebishwa kwa REMOTE_PLAY_MAX_INSTANCES. Bila kifaa cha /dev/dri kilichowekwa ramani, mifano hiyo hutoa picha kwenye CPU, kwa hivyo VPS ya core mbili huhisi kila mtazamaji wa ziada.

Yale ambayo duka husoma kutoka kwenye maktaba yako

Njia za kupita zinatokana na muundo wa ndani wa Jellyfin. Halcyon hupanga sehemu kutoka kwenye maktaba na aina zako za midia, na huweka pamoja mfululizo wa filamu kutoka kwenye BoxSets zako. Maelezo ya kiufundi yaliyochapishwa nyuma ya kila jalada hutoka kwenye metadata ya MediaStreams ambayo Jellyfin tayari inayo, jambo linalomaanisha kuwa chochote kinachokosekana kwenye Jellyfin kitakosekana pia kwenye rafu.

Hii inafanya duka kuwa kioo sahihi cha metadata yako. Maktaba inayolishwa na an arr stack in Docker Compose yenye picha za jalada na aina za midia zilizojazwa vizuri huonekana bora zaidi hapa ikilinganishwa na folda ya faili zilizotawanyika zenye majina ya kawaida.

Jaribu demo ya duka la video kabla ya kusakinisha chochote

Mradi huu huchapisha duka zima likiwa linafanya kazi dhidi ya maktaba ya majaribio kwenye demo inayopangishwa. Kuongeza ?demo=1 kwenye URL yoyote ya Halcyon hufanya vivyo hivyo kwenye deployment yako mwenyewe.

Itumie kama jaribio la maunzi. Maktaba ya demo ina takriban vichwa 2,000 na inahitaji takriban 2 GB ya kumbukumbu ya kivinjari, ambayo ni nzito kuliko maktaba nyingi za kibinafsi. Ikiwa demo itasita-sita kwenye kifaa unachopanga kukitumia kuvinjari, maktaba yako nayo itasita-sita, na suluhisho ni mode ya 2.5D iliyoelezwa hapa chini badala ya VPS kubwa zaidi.

Iendeshe kwa Docker

Hii ndiyo amri inayopendekezwa kwenye nyaraka za msanidi.

docker run -d --name halcyon --network host --restart unless-stopped \
  ghcr.io/halcyon-video/halcyon-video

Kisha hakikisha imewaka.

docker logs halcyon
curl -I http://127.0.0.1:1420

Log inapaswa kuonyesha seva ya preview ikisikiliza kwenye port 1420, na curl inapaswa kujibu HTTP/1.1 200 OK. Container inayozimika ndani ya sekunde chache karibu kila mara inatokana na tatizo la port. --strictPort inamaanisha seva inakataa kuhama kwenda 1421 wakati 1420 inatumiwa, hivyo inasimama badala yake.

--network host ipo kwa ajili ya Remote Play, si kwa ajili ya duka. WebRTC inabidi itangaze anwani halisi ya mashine kwa kifaa kinachotaka stream hiyo. Nyuma ya Docker bridge ya kawaida, container inajua anwani yake ya 172.x pekee, ambayo simu yoyote kwenye mtandao wako haiwezi kuifikia, hivyo stream haiungani kamwe. Ikiwa unataka duka kwenye kivinjari pekee, publish port hiyo badala yake.

docker run -d --name halcyon -p 1420:1420 --restart unless-stopped \
  ghcr.io/halcyon-video/halcyon-video

Hiyo ndiyo chaguo bora zaidi kwenye VPS, kwa sababu host networking huiweka container kwenye kila interface iliyo nayo mashine, ikiwemo ile ya umma. Kuendesha Docker kwenye VPS inaelezea zaidi kuhusu uwiano huo. --restart unless-stopped ndiyo inayorejesha duka baada ya reboot, wazo lilelile kama Compose services zinazoanza wakati wa boot.

Kucopy repository na kuendesha docker compose up -d hujenga image hiyo ndani ya mfumo wako badala yake. Faili la Compose lililopo hujenga kutoka kwenye source kwa kawaida na lina mstari wa image: ukiwa umewekewa komenti, kwa hivyo ondoa komenti kwenye mstari huo ikiwa unataka kutumia image iliyochapishwa chini ya Compose.

Kikwazo kimoja kufikia Agosti 2026: image iliyochapishwa ni ya linux/amd64 pekee. Sehemu ya arm64 ya multi-architecture push ilifeli chini ya emulation na inasubiri arm runners asilia. Kwenye VPS ya arm64, pull inafeli kwa no matching manifest for linux/arm64/v8 in the manifest list entries, na kujenga kutoka kwenye clone ndiyo njia ya kutatua tatizo hilo.

Ielekeze kwenye seva yako ya Jellyfin

Fungua http://<host>:1420 na uingie kwa kutumia anwani ya seva yako ya Jellyfin, jina la mtumiaji, na nenosiri. Faili ya .env.local.example iliyo kwenye hazina (repository) ni kwa ajili ya maendeleo ya ndani (local development) pekee. Vite hufichua vigezo (variables) vyenye kiambishi awali cha VITE_ kwenye msimbo wa upande wa mteja (client side code), kwa hivyo nenosiri la Jellyfin lililoandikwa hapo huunganishwa kwenye JavaScript bundle ambayo kila mgeni huipakua. Kwenye seva inayoweza kufikiwa na watu wengine, ingia kupitia kiolesura (interface).

Kivinjari huwasiliana na Jellyfin moja kwa moja. Kontena la Halcyon halifanyi proxy ya API ya Jellyfin, na hilo lina matokeo mawili ambayo ni vyema kuyafahamu kabla ya kuanza kutatua hitilafu (debugging).

Kwanza, Jellyfin lazima iweze kufikiwa kutoka kwenye kivinjari, si tu kutoka kwa VPS inayohudumia Halcyon. Jellyfin iliyofungwa kwenye 127.0.0.1:8096 inafaa kwa jaribio la ndani lakini itafanya rafu zionekane tupu kwa watu wengine wote.

Pili, ombi hilo ni la asili tofauti (cross origin), kutoka kwenye anwani ya Halcyon kwenda kwenye ya Jellyfin. Jellyfin hujibu maombi ya API kwa Access-Control-Allow-Origin: * kwa chaguomsingi, kwa hivyo inafanya kazi bila usanidi wa ziada. Ikiwa umepunguza mpangilio huo, au umeweka proxy ya uthibitishaji mbele ya API ya Jellyfin, konso ya kivinjari (browser console) itaripoti blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource na duka litapakia likiwa na rafu tupu.

Iweke nyuma ya reverse proxy, ikiwa na uthibitishaji mbele yake

vite preview ni seva ya awali. Haimalizi TLS (transport layer security) na haina udhibiti wa ufikiaji, kwa hivyo inapaswa kuwekwa nyuma ya nginx au Caddy kwenye mtandao wowote wa umma.

server {
  listen 443 ssl;
  server_name halcyon.example.com;

  location / {
    proxy_pass http://127.0.0.1:1420;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Jina la kikoa (domain name) lililowekwa mbele ya container linahitaji mpangilio mmoja zaidi. Halcyon hujibu maombi ya localhost, anwani za IP, na majina ya mashine inayoendesha, kama kinga dhidi ya DNS rebinding. Ndani ya container, mashine inayoendesha ni container yenyewe, kwa hivyo hostname yake si yako. Ombi linalofika kama halcyon.example.com hukataliwa, na jibu huonyesha jina la host lililokataa ombi hilo. Ongeza jina hilo.

docker run -d --name halcyon -p 127.0.0.1:1420:1420 --restart unless-stopped \
  -e HALCYON_ALLOWED_HOSTS=halcyon.example.com \
  ghcr.io/halcyon-video/halcyon-video

Thamani hiyo hutenganishwa kwa koma, nukta ya mwanzo kama .example.com inalingana na subdomains, na all huzima ukaguzi huo. Tumia all kwenye mashine ambayo hakuna kitu cha nje kinachoweza kuifikia.

Mara tu duka linapohudumiwa kupitia https://, anwani ya Jellyfin unayoandika wakati wa kuingia lazima iwe https:// pia. Kivinjari huzuia ombi la kawaida la http:// API linalofanywa kutoka ukurasa wa HTTPS, na console husoma Mixed Content: The page at 'https://halcyon.example.com/' was loaded over HTTPS, but requested an insecure resource. Kuingia hufeli tu, bila maelezo yoyote ndani ya Halcyon. Hudumia zote mbili kupitia TLS, au ziweke zote kwenye HTTP ya kawaida ndani ya mtandao wa kibinafsi.

Kisha uthibitishaji. Duka huomba vitambulisho vya Jellyfin, kwa hivyo mgeni anayepata URL hiyo atakutana na skrini ya kuingia. Kipengele kimoja hubadilisha hilo. Kuwasha Remote Play, chini ya Settings kisha Connection, hutoa session yako ya Jellyfin kwa seva ili wageni wa /remote.html wapate mfano wao wenyewe wa maktaba yako halisi. Hilo ndilo lengo la kipengele hicho, na inamaanisha usiri wa URL ndio kizuizi kati ya mtandao na filamu zako. Ikiwa utawasha Remote Play, weka single sign on mbele ya tovuti nzima kwa kutumia Authentik kama gateway ya SSO inayojiendesha, au ondoa hostname ya umma na ufikie duka kupitia tunnel ya WireGuard inayodhibitiwa na wg-easy.

Maelezo mawili huambatana na hilo. Reverse proxy hubeba duka pekee: mtiririko wa Remote Play ni WebRTC kupitia UDP na hausafiri kupitia HTTP proxy, kwa hivyo unahitaji njia yake kwenye 3478/udp na kwenye 49200 hadi 49260/udp wakati relay ya TURN iliyojumuishwa inatumika. Na docker run ya kawaida hapo juu haihifadhi volume, kwa hivyo mbegu ya Remote Play hainusuriki baada ya docker rm. Faili ya Compose huweka volume ya halcyon-data kwenye /data na kuweka REMOTE_PLAY_SEED kuwa /data/remote-play-seed.json kwa sababu hiyo hasa.

Nini cha kufanya wakati duka linafanya kazi vibaya

Halcyon hutoa picha kwa mahitaji. Duka lisilo na shughuli halitengenezi fremu zozote, na kupoteza focus ya dirisha husimamisha mzunguko wa uhuishaji, ndiyo maana kichupo kilichoachwa wazi hakimalizi betri ya laptop. Hii husaidia mashine iliyo katika hali ya wastani. Haina msaada wowote kwa mashine ambayo haiwezi kuchora duka hilo kabisa.

Kwa wateja hao, kuna hali ya 2.5D, HTML na CSS ya kawaida bila WebGL, iliyokusudiwa kwa maunzi madogo kama Raspberry Pi. Unabadilisha kati ya 3D na 2.5D kutoka kwenye mipangilio au menyu ya nishati bila kulazimika kupakia upya ukurasa, kwa hivyo kujaribu zote mbili kwenye kifaa kimoja huchukua sekunde chache. Kuwa mkweli kuhusu kile unachopata: mwandishi anaelezea hali ya bapa (flat mode) kama mbichi na bado inaendelezwa. Ichukulie kama njia mbadala kwa wateja dhaifu.

Wakati mteja ni mdogo sana kwa duka la 3D, hitilafu huwa dhahiri. Kichupo hujipakia upya chenyewe, au kivinjari huripoti kupotea kwa WebGL context, kwa kawaida wakati rafu bado zinajaa. Hamishia kifaa hicho kwenye 2.5D badala ya kupunguza maktaba yako.

Funga toleo la image, na uhakiki kabla ya kufanya pull

Chukulia hatua hii kwa uzito. Tags v0.1.0 hadi v0.3.1 zote zilitolewa ndani ya siku chache, na v0.2.1 ipo kwa sababu tu ya kufeli kwa image push ya v0.2.0. Ripoti za hitilafu (bug reports) zinakaribishwa kwenye upstream, lakini patches hazikubaliwi, kwa hivyo mkondo wa releases ni hali ya kazi ya mtu mmoja tu.

Kuendesha latest kwa mazoea ya docker pull kunamaanisha kuwa hifadhi inaweza kubadilika bila wewe kujua siku yoyote ya Jumanne ya kawaida. Funga toleo kwa kutumia digest, ambayo ndiyo rejeleo pekee lisiloweza kubadilika.

docker buildx imagetools inspect ghcr.io/halcyon-video/halcyon-video:0.3.1

Amri hiyo huchapisha digest iliyo nyuma ya tag husika. Itumie badala ya tag.

docker run -d --name halcyon -p 1420:1420 --restart unless-stopped \
  ghcr.io/halcyon-video/halcyon-video@sha256:747dcc821a3d2fa318b50e76024783c1835609047e84f502e23d021bc1898b20

Digest hiyo ilikuwa 0.3.1 mnamo tarehe 10 Agosti 2026. Soma digest ya sasa wewe mwenyewe badala ya kuinakili, na usome maelezo ya release kabla ya kufanya mabadiliko, kwa sababu release ya patch hapa inaweza kuleta mabadiliko ya mpangilio wa hifadhi pamoja na marekebisho ya hitilafu.

FAQ

Je, Halcyon inahitaji GPU kwenye VPS yangu?

Haitaji kwa matumizi ya kawaida. Duka huchorwa na three.js kwenye kivinjari, kwa hivyo mashine ya mteja ndiyo inayofanya rendering na kontena hutumikia faili tuli pekee kwenye port 1420. Isipokuwa ni Remote Play, ambayo huendesha Chromium isiyo na kiolesura (headless) kwenye seva na kutiririsha matokeo. Njia hiyo hufanya rendering kwenye CPU isipokuwa uki-map /dev/dri ndani ya kontena kwa ajili ya hardware acceleration.

Je, ninaweza kuweka Halcyon kwenye mtandao wa umma?

Ni pale tu unapoiweka nyuma ya uthibitishaji (authentication). Duka huomba vitambulisho vya Jellyfin, lakini kuwasha Remote Play kunatoa session yako ya Jellyfin kwa seva, kwa hivyo mtu yeyote anayepakia /remote.html atapata mfano wa maktaba yako halisi bila kuingia (login). Weka reverse proxy yenye single sign on mbele yake, au usiiweke hostname kwenye DNS ya umma na ufikie duka hilo kupitia VPN.

Kwa nini rafu ni tupu baada ya kuingia?

Kivinjari huita API ya Jellyfin moja kwa moja, kwa hivyo Jellyfin lazima iweze kufikika kutoka kwenye kivinjari na si kutoka kwenye VPS pekee. Fungua console ya kivinjari. blocked by CORS policy inamaanisha Jellyfin haikubali ombi kutoka kwa anwani ya Halcyon. Ujumbe wa Mixed Content unamaanisha ukurasa uko kwenye HTTPS wakati anwani ya Jellyfin uliyoweka ni HTTP ya kawaida.

Je, ninahitaji --network host?

Kwa ajili ya Remote Play pekee. WebRTC lazima itangaze anwani halisi ya mashine, na nyuma ya Docker bridge kontena linaweza kutoa anwani ya 172.x pekee ambayo hakuna simu kwenye mtandao wako inayoweza kuifikia. Kwa kuvinjari duka kwenye kivinjari, -p 1420:1420 inafanya kazi na hufichua sehemu ndogo zaidi ya host.

Ni image tag ipi ninayopaswa kutumia?

Tumia digest badala ya latest. Soma digest ya toleo lenye docker buildx imagetools inspect ghcr.io/halcyon-video/halcyon-video:0.3.1, endesha digest hiyo, na uhame tu baada ya kusoma maelezo ya toleo (release notes). Kufikia Agosti 2026, image iliyochapishwa ni ya linux/amd64 pekee, kwa hivyo host ya arm64 lazima ijenge (build) kutoka kwenye clone kwa kutumia docker compose up -d.