SZOPA NA WSI
instrukcja obsługi

1. Czym jest ta strona

Szopa na Wsi to strona warsztatu technologicznego z własnym systemem zarządzania treścią. Nie korzysta z WordPressa ani żadnej usługi zewnętrznej — cała treść, zdjęcia i baza danych leżą na Waszym serwerze.

Co jest gdzie

2. Pierwsze uruchomienie

Na komputerze, na którym strona ma działać, potrzebny jest Node.js w wersji 20 lub nowszej.

npm install          # instalacja zależności (raz)
cp .env.example .env # konfiguracja
npm run setup        # baza danych + treści startowe
npm run dev          # uruchomienie w trybie roboczym

Strona działa pod adresem http://localhost:3000, panel pod http://localhost:3000/admin.

Plik konfiguracyjny .env

3. Panel administracyjny

Wejdźcie na /admin. Jeśli nie jesteście zalogowani, strona przekieruje na formularz logowania. Sesja trwa 7 dni.

Co jest w panelu

Zmiana hasła

Ustawienia → Zmiana hasła. Podajecie obecne i nowe (min. 10 znaków). Zróbcie to zaraz po pierwszym zalogowaniu.

4. Jak dodać artykuł

1. Panel → Artykuły → „+ Nowy artykuł”.
2. Wpiszcie tytuł. Adres strony (slug) utworzy się sam — np. „Jak dobrać frez” zamieni się w /artykuly/jak-dobrac-frez. Można go nadpisać ręcznie.
3. Napiszcie lead — jedno do trzech zdań widocznych na liście artykułów i w wynikach Google.
4. Wybierzcie zdjęcie główne — kliknijcie kwadrat „+ Wybierz zdjęcie”, wgrajcie plik albo wskażcie istniejący.
5. Ustawcie kategorię (AI, PROGRAMOWANIE, CNC, 3D, DREWNO, EKSPERYMENTY, PORADNIKI) i opcjonalnie serię.
6. Napiszcie treść w edytorze — opis narzędzi niżej.
7. Kliknijcie „Publikuj”. Wpis pojawia się na stronie.

Statusy

Przycisk Publikuj przełącza między szkicem a publikacją. Wpis już opublikowany ma przycisk Cofnij do szkicu.

5. Edytor treści

Piszecie jak w edytorze tekstu — nie trzeba znać HTML-a. Pasek narzędzi nad polem:

Miejsce na zdjęcie

W treściach przygotowanych wcześniej znajdziecie ramki z napisem MIEJSCE NA ZDJĘCIE i opisem, co ma się w nich znaleźć. Żeby je zastąpić: ustawcie kursor w ramce, skasujcie ją klawiszem Backspace, po czym wstawcie zdjęcie przyciskiem ZDJĘCIE.

6. Jak dodać projekt

Projekt ma więcej pól niż artykuł, bo opisuje realizację od problemu do wniosków.

1. Panel → Projekty → „+ Nowy projekt”.
2. Kod — oznaczenie widoczne na karcie, np. CNC-017. Konwencja: skrót dziedziny plus numer.
3. Tytuł i podtytuł (jedno zdanie doprecyzowujące).
4. Krótki opis — trafia na kartę w siatce projektów i do podglądu przy udostępnianiu.
5. Sekcje — wypełnijcie te, które macie czym wypełnić. Puste nie wyświetlą się na stronie.
6. Zdjęcie główne, galeria, dane techniczne, tagi.
7. Publikuj.

Sekcje strony projektu

Dane techniczne

Pary etykieta–wartość wyświetlane w pasku pod tytułem: TOOL → 6 mm END MILL, MATERIAL → SKLEJKA 18. Dodajcie tyle, ile ma sens — cztery wyglądają najlepiej. Pola PROJECT, STATUS i DATA dopisują się same.

Wyróżnienie i kolejność

Wyróżniony — projekt trafia na stronę główną. Kolejność — mniejsza liczba znaczy wyżej na liście.

7. Jak zmienić grafikę

Są trzy sytuacje. Wszystkie robi się w przeglądarce, bez kopiowania plików na serwer.

A. Zdjęcie główne artykułu lub projektu

1. Otwórzcie wpis w panelu (albo kliknijcie ✎ Zdjęcie na stronie publicznej).
2. Najedźcie na miniaturę po prawej — pojawi się napis ✎ Zmień.
3. Kliknijcie. Otworzy się biblioteka.
4. Wgrajcie nowy plik przyciskiem + Wgraj albo przeciągnijcie go w okno; można też wybrać istniejący.
5. Kliknijcie zdjęcie i Wstaw (albo dwuklik — od razu wstawia).
6. Zapisz.

B. Zdjęcie w treści

Kliknijcie zdjęcie w edytorze i skasujcie Backspace, potem wstawcie nowe przyciskiem ZDJĘCIE.

C. Zdjęcia warsztatu na stronie głównej

Sekcja Wall of experiments pobiera sześć najnowszych zdjęć z biblioteki. Żeby ją zmienić, wgrajcie nowe pliki w Media — pojawią się tam automatycznie. Sloty bez zdjęcia pokazują techniczny rysunek z opisem, czego brakuje.

Jakie pliki wgrywać

8. Biblioteka mediów

Panel → Media. Tu leżą wszystkie zdjęcia.

• Wgrywanie — przycisk + Wgraj pliki albo przeciągnięcie plików na przerywaną ramkę. Można wiele naraz.
• Opis — kliknijcie miniaturę, otworzy się panel szczegółów. Uzupełnijcie ALT i podpis, kliknijcie Zapisz opis.
• Kopiowanie ścieżki — przycisk Kopiuj ścieżkę, gdy chcecie wstawić zdjęcie ręcznie.
• Usuwanie — kasuje rekord i wszystkie wersje pliku z dysku. Nieodwracalne.
• Szukanie — po nazwie pliku, opisie ALT i podpisie.

9. Diagramy procesu

Artykuł i projekt mogą mieć animowany schemat. Wybiera się go z listy — pole DIAGRAM PROCESU w prawej kolumnie edytora. Nie trzeba nic rysować.

Diagram pojawia się pod leadem artykułu albo po opisie projektu. Żeby go usunąć, wybierzcie pozycję brak.

Dla programisty: nowy diagram

Schematy blokowe opisuje się danymi, nie rysuje. Jeden wpis w src/components/diagrams/specs.tsx to jeden diagram:

'moj-diagram': {
  title: 'MOJ.FLOW',
  accent: 'var(--color-ai)',
  steps: [
    { label: 'WEJŚCIE', kind: 'input' },
    { label: 'DECYZJA', kind: 'decide' },
    { label: 'WYNIK', kind: 'output' },
  ],
  loops: [{ from: 3, to: 2, label: 'POPRAWKA' }],
}

Typ kroku (input, decide, tool, process, control, store, output) decyduje o kształcie i kolorze węzła. Układ i połączenia liczą się same. Dostępne są dwa układy: serpentine (domyślny) i ring dla procesów cyklicznych.

10. Serie artykułów

Seria grupuje wpisy w cykl czytany po kolei. Pole SERIA w edytorze artykułu.

Serie wyświetlają się jako cztery kafle na górze /artykuly; kliknięcie filtruje listę. Na stronie artykułu seria jest plakietką nad tytułem.

Nową serię dodaje programista w pliku src/lib/taxonomy.ts — tablica SERIES i opis w SERIES_META.

11. Podstrony i nawigacja

Strony takie jak /o-nas są częścią kodu, nie bazy danych — dzięki temu mogą mieć własny układ. Dodanie nowej wymaga programisty, ale jest proste.

1. Utwórzcie plik src/app/(site)/nazwa/page.tsx.
2. Skopiujcie strukturę z o-nas/page.tsx jako punkt wyjścia.
3. Dodajcie pozycję do menu w src/components/site/Header.tsx, tablica NAV.
4. Jeśli strona ma być w Google — dopiszcie ją w src/app/sitemap.ts.

Katalog (site) w nazwie jest celowy: wszystko w nim dostaje nagłówek, stopkę i efekty części publicznej. Panel administracyjny leży poza nim i ma własną, surową ramę.

Zmiana menu

const NAV = [
  { label: 'START', href: '/', accent: 'var(--color-ink)' },
  { label: 'PROJEKTY', href: '/projekty', accent: 'var(--color-cnc)' },
  { label: 'CNC', href: '/projekty?tag=CNC', accent: 'var(--color-cnc)' },
  // ...
]

Pozycja menu może wskazywać na filtr — np. /projekty?tag=WOOD pokaże tylko projekty z tagiem WOOD. accent to kolor kreski pod pozycją.

12. Ustawienia strony

Panel → Ustawienia. Te pola widać na stronie publicznej:

Zmiany widać na stronie w ciągu minuty (strona odświeża treści cyklicznie).

13. Dźwięk i multimedia

Dźwięk migawki

Karty projektów wydają dźwięk mechanizmu przy rozsuwaniu. Przełącznik głośnika jest w nagłówku, wybór zapamiętuje się w przeglądarce. Przy systemowym ustawieniu ograniczonego ruchu dźwięk jest domyślnie wyciszony.

Pliki generuje skrypt: npm run sounds. Parametry brzmienia są opisane w scripts/generate-sounds.mjs.

Nagrania i utwory

Niektóre projekty mają odtwarzacz z przebiegiem fali (ACP/2, AURORA). Plik audio pobiera się dopiero po naciśnięciu play — nic nie gra samo z siebie i nic nie obciąża strony, dopóki ktoś nie kliknie.

Pliki leżą w public/audio/. Żeby dodać własny, wrzućcie tam plik MP3 i poproście programistę o podpięcie odtwarzacza.

14. SEO i widoczność

Większość dzieje się automatycznie. Wasza rola to trzy pola przy każdym wpisie:

Automatycznie generowane są: mapa witryny (/sitemap.xml), plik /robots.txt, podglądy linków dla mediów społecznościowych oraz dane strukturalne dla wyszukiwarek. Panel i wyszukiwarka są wyłączone z indeksowania.

15. Kopie zapasowe

Jedno polecenie kopiuje bazę danych, wszystkie wgrane zdjęcia i konfigurację:

npm run backup

Kopie lądują w backups/RRRR-MM-DD_GG-MM/. Starsze niż 14 dni kasują się same (BACKUP_KEEP_DAYS zmienia ten okres).

Automatyczna kopia codziennie

0 3 * * * cd /var/www/szopanawsi && /usr/bin/npm run backup

Odtworzenie z kopii

1. Zatrzymajcie stronę: systemctl stop szopanawsi
2. Skopiujcie database.db z kopii do prisma/dev.db
3. Skopiujcie katalog uploads z kopii w miejsce istniejącego
4. Uruchomcie ponownie: systemctl start szopanawsi

16. Wdrożenie na serwer

Ten rozdział opisuje rzeczywistą instalację działającą pod adresem szopanawsi.pl, a nie wariant przykładowy. Strona stoi na tej samej maszynie co Nextcloud, Jellyfin, Immich i pozostałe usługi domowe, dlatego kilka rozwiązań odbiega od typowego poradnika — i warto wiedzieć dlaczego.

Skąd bierze się build

Strona jest budowana na serwerze, nie na komputerze. To nie jest kwestia wygody: Prisma i sharp zawierają biblioteki natywne skompilowane pod konkretny system, więc paczka złożona na Windows nie uruchomi się na Linuksie. Dlatego wysyłamy źródła (około 4 MB), a nie gotowy katalog .next (ponad 300 MB).

Wdrożenie jednym poleceniem

Z katalogu projektu na komputerze:

DEST=/home/ardmin/szopanawsi PORT=3005 bash deploy/deploy.sh szopa

szopa to wpis w ~/.ssh/config wskazujący na serwer i klucz szopanawsi_deploy. Skrypt pakuje źródła, wysyła je, instaluje zależności, generuje klienta Prismy, buduje stronę i restartuje proces.

Domyślnie skrypt nie dotyka bazy ani zdjęć. To zabezpieczenie, nie niedopatrzenie: treści dodane przez panel /admin istnieją tylko na serwerze i są nowsze niż kopia lokalna. Nadpisanie ich flagą --with-data jest decyzją świadomą, a skrypt i tak najpierw odkłada starą bazę do backups/:

DEST=/home/ardmin/szopanawsi PORT=3005 bash deploy/deploy.sh szopa --with-data

Ręczne sterowanie procesem

Wysyłanie zdjęć z laptopa — bez szukania serwera

W katalogu projektu leży wyslij.cmd. Przeciągnij na niego zdjęcia albo cały folder — trafią do biblioteki mediów i pojawią się w panelu, gotowe do wstawienia w projekt czy artykuł.

Narzędzie nie potrzebuje SSH ani znajomości adresu serwera: idzie przez publiczne HTTPS, więc działa tak samo w domu, jak i poza nim. Pliki przechodzą tę samą ścieżkę co upload z panelu — przeskalowanie, warianty AVIF i WEBP, sprawdzenie typu — a nie osobną, która mogłaby się z panelem rozjechać.

wyslij.cmd zdjecie.jpg
node deploy/wyslij.mjs C:zdjeciawarsztat

Wdrożenie bez pamiętania, w jakiej jesteś sieci

Kod wysyła się jednym poleceniem z trasą auto. Skrypt sam sprawdza po kolei sieć domową, tailnet i adres publiczny, i używa pierwszej, która odpowiada:

DEST=/home/ardmin/szopanawsi PORT=3005 bash deploy/deploy.sh auto

W domu wybierze szopa-lan, bo jest najszybsza. Poza domem zadziała dopiero wtedy, gdy serwer będzie w tailnecie — port 22 nie jest już wystawiony na publiczny adres.

Konfiguracja Apache

Plik deploy/apache-szopanawsi.conf zawiera dwa vhosty: na porcie 80 (przekierowanie na HTTPS plus wyjątek dla odnawiania certyfikatu) i na 443 (proxy na 127.0.0.1:3005). Instalacja wymaga uprawnień administratora:

sudo cp /home/ardmin/szopanawsi/deploy/apache-szopanawsi.conf /etc/apache2/sites-available/szopanawsi.conf
sudo a2ensite szopanawsi
sudo apache2ctl configtest && sudo systemctl reload apache2

Vhost ustawia LimitRequestBody na 32 MB, żeby panel przyjmował duże zdjęcia z warsztatu, oraz roczny cache dla /_next/static/ i /media/ — pliki w obu ścieżkach mają w nazwie skrót treści, więc nie zmieniają się w miejscu.

Powrót do poprzedniej strony

Poprzednia strona (Grav) nie została skasowana — jej pliki leżą w /srv/www/grav, a konfiguracja pozostaje w sites-available. Powrót zajmuje kilka sekund:

sudo a2dissite szopanawsi && sudo a2ensite grav grav-le-ssl && sudo systemctl reload apache2

Certyfikat

Certyfikat www.szopanawsi.pl był wystawiony jeszcze dla vhosta Grava i został przejęty przez nową konfigurację. Po przełączeniu warto sprawdzić, czy odnawianie nadal działa — inaczej problem wyjdzie dopiero w dniu wygaśnięcia:

sudo certbot renew --dry-run

Po pierwszym uruchomieniu

Konto administratora przyjeżdża razem z bazą, więc logowanie działa tymi samymi danymi co lokalnie. Hasło trzeba zmienić, bo strona jest już publiczna — w panelu /admin, w ustawieniach konta. Pola ADMIN_EMAIL i ADMIN_PASSWORD w serwerowym .env służą wyłącznie do zakładania konta przy pustej bazie i nie mają wpływu na logowanie.

Plik .env powstaje na serwerze przy pierwszym wdrożeniu i ma własny, losowy AUTH_SECRET. Kolejne wdrożenia go nie ruszają — sekret zostaje ten sam, dzięki czemu sesje zalogowanych osób przeżywają aktualizację.

17. Aktualizacja i utrzymanie

Wgranie zmian w kodzie

cd /var/www/szopanawsi
npm run backup            # najpierw kopia
git pull
npm ci
npx prisma db push        # gdy zmieniła się struktura bazy
npm run build
sudo systemctl restart szopanawsi

Podgląd dziennika

sudo journalctl -u szopanawsi -f       # na żywo
sudo journalctl -u szopanawsi -n 100   # ostatnie 100 linii

Ile miejsca zajmuje strona

18. Rozwiązywanie problemów

19. Ściąga

npm run dev       # tryb roboczy
npm run build     # budowanie
npm start         # uruchomienie
npm run backup    # kopia zapasowa

npm run db:studio # podgląd bazy
npm run sounds    # dźwięki migawki
npm run typecheck # kontrola kodu

Najkrótsza droga do opublikowania artykułu

/ADMIN → ARTYKUŁY → + NOWY ARTYKUŁ → TYTUŁ → LEAD → ZDJĘCIE GŁÓWNE → TREŚĆ → PUBLIKUJ