docs: runbook wdrożenia share od zera na nodzie #24

Merged

gitea merged 1 commits from docs-share-node-setup into main 2026-08-12 15:44:16 +00:00

Conversation 0 Commits 1 Files Changed 3

+156 -2

gitea commented 2026-08-12 15:33:39 +00:00

Owner

Copy Link

Copy Source

Brakowało opisu "co node musi mieć" — FILE_SHARING.md tłumaczy jak działa funkcja i zakłada, że node już stoi.

Nowe: docs/deployment/SHARE_NODE_SETUP.md

• cztery katalogi na hoście + co się gdzie montuje,
• uprawnienia do biblioteki — Apache serwuje jako www-data (uid 33 w kontenerze), więc uid 33 musi móc czytać /srv/share/media; to klasyczna przyczyna "wszystkie linki 403",
• deploy stacka musician+share (Portainer albo CLI),
• przekierowanie /share/ z reverse proxy (snippety nginx i Apache) + DNS/firewall,
• wpięcie po stronie musiciana (CONJURER_SHARE_*),
• weryfikacja po każdym kroku, w tym że listing katalogu musi dawać 403 (inaczej wycieka cały zestaw żywych tokenów) i że pliki stanu revokera nie są serwowane,
• tabelka troubleshootingu (404 vs 403 vs pusty /get_share_list vs linki, które nie wygasają).

Trzy sprzężenia, które to realnie psują

1. Biblioteka musi być zamontowana pod tą samą ścieżką kontenerową (/mnt/shares) w obu kontenerach — indeks zapisuje ścieżki absolutne, a symlinki są absolutne.
2. Katalog linków i indeksu musi być współdzielony (ten sam host albo wspólny storage) — inaczej musician tworzy linki, których share nie widzi.
3. CONJURER_SHARE_BASE_URL musi odpowiadać realnemu publicznemu URL-owi — nie ma go w dołączonym stacku, więc po cichu wpada na default https://czernobog.pl/share.

Czego node NIE potrzebuje

Ani Apache na hoście, ani crona, ani Pythona, ani ręcznie podłożonych skryptów — Apache, vhost, scan_shares.py i revoke_shares.py są w obrazie (COPY w Dockerfile.share).

🤖 Generated with Claude Code

Brakowało opisu "co node musi mieć" — `FILE_SHARING.md` tłumaczy jak działa funkcja i zakłada, że node już stoi. ## Nowe: `docs/deployment/SHARE_NODE_SETUP.md` - cztery katalogi na hoście + co się gdzie montuje, - **uprawnienia do biblioteki** — Apache serwuje jako `www-data` (**uid 33 w kontenerze**), więc uid 33 musi móc czytać `/srv/share/media`; to klasyczna przyczyna "wszystkie linki 403", - deploy stacka musician+share (Portainer albo CLI), - przekierowanie `/share/` z reverse proxy (snippety nginx i Apache) + DNS/firewall, - wpięcie po stronie musiciana (`CONJURER_SHARE_*`), - **weryfikacja po każdym kroku**, w tym że listing katalogu **musi** dawać 403 (inaczej wycieka cały zestaw żywych tokenów) i że pliki stanu revokera nie są serwowane, - tabelka troubleshootingu (404 vs 403 vs pusty `/get_share_list` vs linki, które nie wygasają). ## Trzy sprzężenia, które to realnie psują 1. Biblioteka musi być zamontowana pod **tą samą ścieżką kontenerową** (`/mnt/shares`) w **obu** kontenerach — indeks zapisuje ścieżki absolutne, a symlinki są absolutne. 2. Katalog linków i indeksu musi być współdzielony (ten sam host albo wspólny storage) — inaczej musician tworzy linki, których share nie widzi. 3. `CONJURER_SHARE_BASE_URL` musi odpowiadać realnemu publicznemu URL-owi — **nie ma go w dołączonym stacku**, więc po cichu wpada na default `https://czernobog.pl/share`. ## Czego node NIE potrzebuje Ani Apache na hoście, ani crona, ani Pythona, ani ręcznie podłożonych skryptów — Apache, vhost, `scan_shares.py` i `revoke_shares.py` są w obrazie (`COPY` w `Dockerfile.share`). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gitea self-assigned this 2026-08-12 15:33:39 +00:00

gitea added 1 commit 2026-08-12 15:33:39 +00:00

docs: from-zero node runbook for the share service ... d0c7ab61a7

FILE_SHARING.md explains how the feature works and assumes you already know
the node story; there was nothing describing what a fresh box has to provide.
SHARE_NODE_SETUP.md fills that: the four host directories, the uid-33
readability requirement on the media library, deploying the musician+share
stack (Portainer or CLI), forwarding /share from the reverse proxy, and the
musician-side CONJURER_SHARE_* wiring - each with its verification command.

Calls out the three couplings that actually break it in practice: the media
must be mounted at the SAME container path on both containers (index paths and
symlinks are absolute), the link/index dirs must be shared, and
CONJURER_SHARE_BASE_URL must match the real public URL - it is not set in the
bundled stack file and silently falls back to czernobog.pl.

Also records what the node does NOT need: no host Apache, no cron, no Python,
no hand-placed scripts - Apache, the vhost, scan_shares.py and
revoke_shares.py are all baked into the image.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

gitea merged commit d0c7ab61a7 into main 2026-08-12 15:44:16 +00:00

gitea deleted branch docs-share-node-setup 2026-08-12 15:44:16 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

gitea

No Assignees gitea

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: gitea/conjurer#24