reads — Self-hosted Bookmark & Read-later Manager

🚀 Demo Live (Staging)

Wersja demonstracyjna z przykładowymi danymi.

Czym jest reads

Self-hosted bookmark / read-later manager. Użytkownik zapisuje URL-e, system pobiera metadane (tytuł, opis, favicon, og:image), ekstrahuje treść do trybu reader, pozwala tagować, wyszukiwać i oznaczać jako przeczytane. System wspiera import/export zakładek z zachowaniem hierarchii folderów.

Projekt służy jednocześnie jako narzędzie codziennego użytku oraz publiczny showcase warsztatu technologicznego.

Trzy Zobowiązania (Project Commitments)

1. Self-hostable: Każdy może uruchomić własną instancję jedną komendą (docker compose up -d). Brak zależności od zewnętrznych usług autora.
2. Open-source-ready: Licencja MIT, jasne zasady kontrybucji i proces PR.
3. AI-agnostic: Działa w pełni bez AI (LLM_PROVIDER=none). AI tylko dodaje wartości (semantic search, TL;DR), nigdy nie jest wymagane do działania rdzenia aplikacji.

Szczegóły: Zobowiązania projektu

Demo

Instancja demo dostępna pod adresem: reads.baluarte.pl

Dostęp na żądanie: Ze względu na dogfooding (instancja zawiera prawdziwe dane autora), dostęp jest ograniczony przez Cloudflare Access. Napisz do autora, aby otrzymać zaproszenie.

Szczegóły instancji demo: Instancja demo

Szybki start (Self-hosting)

git clone https://github.com/przemyslvw/reads.git && cd reads
cp .env.example .env   # wypełnij DATABASE_URL i inne sekrety
docker compose up -d

Note

Aplikacja automatycznie wykonuje migracje bazy danych przy każdym starcie kontenera API, więc nie musisz ręcznie inicjować schematu.

Pełna instrukcja self-hostingu dostępna w dokumentacji (WIP).

Testy

pnpm -F web test:e2e

pnpm -r test:coverage

pnpm run lint

Stack technologiczny

Szczegóły techniczne znajdziesz w dokumencie Architektura.

Linki

• Jak kontrybuować
• Roadmapa projektu
• Architecture Decision Records (ADR)
• Licencja (MIT)

Infrastruktura i Utrzymanie (CI/CD)

Projekt posiada zautomatyzowane polityki czyszczenia zasobów Docker na VPS (Self-hosted runner), aby zapobiec zapełnieniu dysku:

1. Weekly Cleanup: Co niedzielę o 03:00 uruchamiany jest workflow Docker Maintenance, który wykonuje docker system prune -af --volumes dla zasobów starszych niż 7 dni.
2. Tag Retention: Pipeline wdrożeniowy (Staging) przechowuje lokalnie tylko 3 ostatnie obrazy dla każdego komponentu (api, web). Starsze obrazy są usuwane natychmiast po udanym pushu do rejestru.
3. Build Cache: Wykorzystujemy lokalny cache (type=local) z rotacją (new/old), co ogranicza niekontrolowany wzrost katalogu /tmp/.buildx-cache.
4. Dangling Images: Każdy pipeline kończy się komendą docker image prune -f, usuwając warstwy pośrednie natychmiast po budowaniu.

---

_{© 2026 Przemas Majdak. Built with ❤️ for better reading.}