Jinsi ya kutumia Halcyon na Jellyfin kama duka la kanda

Jinsi Halcyon inavyoshughulikia maktaba yako ya Jellyfin

Halcyon Video inabadilisha mwonekano wa maktaba yako ya Jellyfin kuwa duka la kanda za video la miaka ya 1990 unaloweza kutembea ndani yake kupitia kivinjari. Kila filamu uliyonayo inakuwa jalada kwenye rafu. Unatembea kwenye njia za katikati ya rafu chini ya taa za neon, unashusha sanduku, unaligeuza ili kusoma maelezo yaliyo nyuma, na unalibeba hadi kwenye kaunta ili kuanza kucheza filamu. Taarifa za kuanza, maendeleo na kusimama kwa filamu hurudishwa kwenye Jellyfin, hivyo sehemu uliyoshia na historia ya kutazama hubaki sahihi.

Halcyon inasoma seva ya Jellyfin iliyopo kupitia Jellyfin API na haina maktaba yake yenyewe. Mwongozo huu unachukulia kuwa Jellyfin tayari inafanya kazi na inachanganua faili bila matatizo. Ikiwa sivyo, sanidi Jellyfin kama seva ya midia 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 ya mradi huu ni ya haraka na hakuna msimamizi wa pili wa kurekebisha hitilafu (regression), 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 jalada la kisanduku 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 hii kwa urahisi, kwa sababu kuihudumia kunamaanisha kutoa faili tuli kupitia HTTP. Kompyuta ya mkononi, kompyuta kibao au televisheni inayoendesha kivinjari ndiyo inayoamua kama duka litasonga vizuri au litasua.

Kipengele kimoja huvunja kanuni hiyo. Remote Play huunda mifano ya Chromium isiyo na kiolesura (headless) kwenye seva na kutiririsha duka lililotolewa kwenye simu au kisanduku cha set-top 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 yenye core mbili huhisi kila mtazamaji wa ziada.

Yale ambayo duka husoma kutoka kwenye maktaba yako

Njia za kupita zinatokana na muundo wa Jellyfin yenyewe. Halcyon hupanga sehemu kutoka kwenye maktaba na aina za maudhui (genres) zako, na huweka pamoja mfululizo wa filamu (sequels) kutoka kwenye BoxSets zako. Maelezo ya kiufundi yaliyochapishwa nyuma ya kila jalada yanatokana na metadata ya MediaStreams ambayo Jellyfin tayari inayo, jambo linalomaanisha kuwa chochote kinachokosekana kwenye Jellyfin hakitaonekana kwenye rafu.

Hii inafanya duka kuwa kioo sahihi cha metadata yako. Maktaba inayolishwa na an arr stack in Docker Compose ikiwa na picha za jalada na aina za maudhui zilizojazwa tayari huonekana vizuri zaidi hapa kuliko folda ya faili zilizotawanyika zenye majina ya kawaida. Maktaba za picha zina utegemezi uleule kwa chochote kilichoziorodhesha, jambo ambalo ni muhimu kukumbuka unapopima PhotoPrism against Immich kwa ajili ya picha zilizohifadhiwa kwenye seva hiyo hiyo.

Jaribu onyesho la duka la video kabla ya kusakinisha chochote

Mradi huu huchapisha duka zima likiwa linafanya kazi dhidi ya maktaba ya majaribio kwenye onyesho lililopangishwa. Kuongeza ?demo=1 kwenye URL yoyote ya Halcyon hufanya vivyo hivyo kwenye usakinishaji wako mwenyewe.

Itumie kama kipimo cha uwezo wa maunzi. Maktaba ya onyesho ina takriban vichwa 2,000 na inahitaji takriban 2 GB ya kumbukumbu ya kivinjari, ambayo ni nzito kuliko maktaba nyingi za kibinafsi. Ikiwa onyesho litakwama kwenye kifaa unachopanga kutumia kuvinjari, maktaba yako mwenyewe itakwama pia, na suluhisho ni hali 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 kuwa imeanza kufanya kazi.

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 inayozima 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, siyo kwa ajili ya duka. WebRTC lazima itangaze anwani halisi ya mashine kwa kifaa kinachotaka stream hiyo. Nyuma ya Docker bridge ya kawaida, container inajua tu anwani yake ya 172.x, ambayo simu yoyote kwenye mtandao wako haiwezi kuifikia, kwa hivyo stream haiwezi kuunganishwa. 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 na mashine hiyo, 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 ya Compose iliyopo hujenga kutoka kwenye source kwa chaguo-msingi na ina mstari wa image: ukiwa umewekewa komenti, kwa hivyo ondoa komenti kwenye mstari huo ikiwa unataka kutumia image iliyochapishwa chini ya Compose.

Kikomo kimoja kigumu 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.

Elekeza 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 ni kwa ajili ya maendeleo ya ndani pekee. Vite hufichua vigezo vyenye kiambishi awali cha VITE_ kwa msimbo wa upande wa mteja, kwa hivyo nenosiri la Jellyfin lililoandikwa hapo huingizwa kwenye JavaScript bundle ambayo kila mgeni huipakua. Kwenye seva inayoweza kufikiwa na watu wengine, ingia kupitia kiolesura.

Kivinjari huwasiliana na Jellyfin moja kwa moja. Kontena ya Halcyon haifanyi proxy ya API ya Jellyfin, na hilo lina matokeo mawili ambayo ni muhimu kuyajua kabla ya kuanza kutatua hitilafu.

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 kwa anwani ya Halcyon kwenda kwa ya Jellyfin. Jellyfin hujibu maombi ya API kwa Access-Control-Allow-Origin: * kwa chaguomsingi, kwa hivyo hufanya kazi bila usanidi wa ziada. Ikiwa umepunguza mpangilio huo, au umeweka proxy ya uthibitishaji mbele ya API ya Jellyfin, konsole ya kivinjari 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 majaribio. Haimalizi TLS (transport layer security) na haina udhibiti wa ufikiaji wake yenyewe, kwa hivyo inapaswa kuwekwa nyuma ya nginx au Caddy kwenye mfumo 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) lililo mbele ya container linahitaji mpangilio mmoja zaidi. Halcyon hujibu localhost, anwani za IP za moja kwa moja, 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 nje kinachoweza kuifikia.

Mara tu duka linapotolewa 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. Toa huduma 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 hukutana na skrini ya kuingia. Kipengele kimoja hubadilisha hilo. Kuwasha Remote Play, chini ya Settings na kisha Connection, hutoa session yako ya Jellyfin kwa seva ili wageni wa /remote.html wapate instance yao wenyewe ya maktaba yako halisi. Hilo ndilo lengo la kipengele hicho, na inamaanisha usiri wa URL ndio unaozuia mtandao kufikia 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 a WireGuard tunnel inayodhibitiwa na wg-easy.

Maelezo mawili yanaambatana na hayo. 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 TURN relay iliyojumuishwa inatumiwa. Na docker run ya kawaida hapo juu haihifadhi volume yoyote, kwa hivyo mbegu ya Remote Play hainusuriki 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 (on demand). Duka lisilokuwa na shughuli halitengenezi fremu zozote, na kupoteza focus ya dirisha husimamisha mzunguko wa uhuishaji, ndiyo maana tab iliyoachwa wazi haimalizi betri ya laptop. Hii husaidia mashine iliyo katika hali ya kawaida. Haifanyi lolote kwa mashine ambayo haiwezi kuchora duka hilo hata kidogo.

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

Wakati mteja ni mdogo sana kwa duka la 3D, hitilafu huwa dhahiri. Tab inajiload yenyewe, au kivinjari kinaripoti kupotea kwa WebGL context, kwa kawaida wakati rafu bado zinajaa. Hamishia kifaa hicho kwenye 2.5D badala ya kupunguza maktaba yako.

Bandika picha (image), na uhakiki kabla ya kuivuta (pull)

Chukulia sehemu hii kwa uzito. Lebo (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 uwekaji (push) wa picha ya v0.2.0. Ripoti za hitilafu zinakaribishwa kwenye chanzo (upstream), lakini viraka (patches) havikaribishwi, kwa hivyo mtiririko wa matoleo ni hali ya kazi ya mtu mmoja.

Kuendesha latest kwa mazoea ya docker pull inamaanisha kuwa hifadhi inaweza kubadilika bila wewe kujua siku yoyote ya kawaida ya Jumanne. Bandika kwa kutumia digest, rejeleo pekee ambalo haliwezi kubadilika.

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

Hiyo huchapisha digest iliyo nyuma ya lebo hiyo. Itumie badala ya lebo.

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 ile ya sasa wewe mwenyewe badala ya kuinakili, na usome maelezo ya toleo kabla ya kuhama, kwa sababu toleo la kiraka hapa linaweza kuleta mabadiliko ya mpangilio wa hifadhi pamoja na marekebisho.

FAQ

Je, Halcyon inahitaji GPU kwenye VPS yangu?

Si 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 uweke /dev/dri kwenye kontena kwa ajili ya hardware acceleration.

Je, ninaweza kuweka Halcyon kwenye mtandao wa umma?

Ni pale tu inapokuwa nyuma ya uthibitishaji (authentication). Duka huomba vitambulisho vya Jellyfin, lakini kuwasha Remote Play hutoa 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 kufikiwa 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 inamaanisha 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 sana ya host.

Ni image tag ipi ninayopaswa kutumia?

Tumia digest badala ya latest. Soma digest kwa ajili 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.