InfoShock

Piattaforma multi-tenant per infoshop indipendenti e librerie personali. Ogni infoshop gestisce il proprio catalogo, gli ordini e i pagamenti attraverso un'unica installazione. Gli utenti possono anche creare librerie personali per gestire la propria collezione di libri, con prestiti e stato di lettura.

Funzionalita

• Multi-tenancy — ogni infoshop ha il proprio spazio (/<slug>/), tema, lingua e configurazione
• Librerie personali — collezioni private con stato di lettura, prestiti e possibilita di promozione a infoshop
• Catalogo — ricerca libri per ISBN con import automatico da Open Library e Google Books
• Inventario per infoshop — prezzi, disponibilita, sconti e condizioni personalizzabili per ogni copia
• Modalita di prezzo — prezzo fisso, prezzo libero (pay what you want) o gratuito
• Prestiti — gestione completa del ciclo di prestito con richieste pubbliche e notifiche email
• Carrello e ordini — carrello in sessione, checkout per utenti registrati o anonimi, ritiro o spedizione
• Pagamenti — integrazione Stripe con chiavi API per infoshop
• Notifiche email — avviso automatico alla infoshop per nuovi ordini e richieste di prestito
• Ricerca globale — ricerca cross-tenant tra tutti i cataloghi pubblici (/search/)
• Registrazione self-service — creazione autonoma di librerie personali o infoshop (/register/)
• API REST — endpoint pubblici per libri, infoshop e cataloghi con filtri e ricerca (/api/v1/)
• Internazionalizzazione — italiano, inglese, spagnolo, tedesco, francese
• Federazione — predisposto per ActivityPub (fase 2)

Stack

• Python 3.12, Django 5.2, PostgreSQL
• django-htmx, Django REST Framework, Stripe
• Whitenoise per i file statici, httpx per le API esterne

Installazione

Si consiglia uv per la gestione delle dipendenze:

git clone https://git.lattuga.net/jops/infoshock.git
cd infoshock
uv sync
cp .env.example .env  # configurare le variabili
uv run python manage.py migrate
uv run python manage.py setup_demo  # dati di esempio
uv run python manage.py runserver

In alternativa, con pip:

pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py setup_demo
python manage.py runserver

Il comando setup_demo crea:

• Un superadmin (admin/admin)
• Circolo Berneri — infoshop con ~240 libri (berneri/berneri)
• Test Infoshop — infoshop con un sottoinsieme del catalogo (testshop/testshop)
• La mia libreria — libreria personale con 15 libri, stati di lettura e un prestito di esempio (lettore/lettore)

Per scaricare anche le copertine dei libri da Open Library e Google Books:

uv run python manage.py setup_demo --covers

I file requirements.txt e requirements-dev.txt sono export generati da uv (non la sorgente delle dipendenze). Per rigenerarli:

uv lock
uv export --format requirements.txt --no-dev --no-hashes --no-emit-project -o requirements.txt
uv export --format requirements.txt --all-groups --no-hashes --no-emit-project -o requirements-dev.txt

Libreria personale

Le librerie personali sono private (visibili solo al proprietario) e pensate per gestire la propria collezione di libri. Rispetto agli infoshop non hanno carrello, ordini o pagamenti, ma offrono:

• Stato di lettura — letto, in lettura, non letto, abbandonato
• Prestiti — dalla pagina di dettaglio di un libro ("Lend this book"), gestibili da /<slug>/manage/loans/
• Promozione — una libreria personale puo essere convertita in infoshop pubblico da /<slug>/manage/promote/

Per registrare una nuova libreria personale: http://localhost:8000/register/

Con Docker

cp .env.example .env
docker compose up -d
docker compose exec web python manage.py migrate
docker compose exec web python manage.py setup_demo

Il compose avvia due servizi:

• db — PostgreSQL 16 (Alpine), crea automaticamente database e utente al primo avvio. I dati sono persistiti nel volume postgres_data.
• web — l'applicazione Django servita da Gunicorn sulla porta 8000.

Il servizio web attende che PostgreSQL sia pronto (healthcheck) prima di partire. La variabile DATABASE_URL viene sovrascritta per puntare al container db.

Per fermare i servizi:

docker compose down      # ferma i container, mantiene i dati
docker compose down -v   # ferma i container e cancella il volume (reset completo)

Per ricostruire l'immagine dopo modifiche al codice:

docker compose up -d --build

Database

Il progetto richiede PostgreSQL. Creare il database e l'utente:

sudo -u postgres psql

CREATE USER infoshock WITH PASSWORD 'infoshock';
CREATE DATABASE infoshock OWNER infoshock;
\q

Configurare la connessione nel file .env tramite DATABASE_URL (vedi sotto).

SECRET_KEY

In produzione e necessario generare una chiave segreta sicura. Si puo usare Django stesso:

uv run python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Copiare il valore generato nella variabile SECRET_KEY del file .env.

Variabili d'ambiente

Variabile	Descrizione	Default
SECRET_KEY	Chiave segreta Django (vedi sopra)	insecure-dev-key-change-me
DEBUG	Modalita debug (True/False)	True
DATABASE_URL	URL connessione PostgreSQL (postgres://user:password@host:port/dbname)	postgres://infoshock:infoshock@localhost:5432/infoshock
ALLOWED_HOSTS	Host consentiti (separati da virgola)	localhost,127.0.0.1
STRIPE_PUBLISHABLE_KEY	Chiave pubblica Stripe (fallback)	—
STRIPE_SECRET_KEY	Chiave segreta Stripe (fallback)	—
STRIPE_WEBHOOK_SECRET	Segreto webhook Stripe	—
EMAIL_BACKEND	Backend email Django	django.core.mail.backends.console.EmailBackend
EMAIL_HOST	Server SMTP	localhost
EMAIL_PORT	Porta SMTP	587
EMAIL_USE_TLS	Abilita TLS	True
EMAIL_HOST_USER	Utente SMTP	—
EMAIL_HOST_PASSWORD	Password SMTP	—
DEFAULT_FROM_EMAIL	Mittente predefinito	noreply@infoshock.local

Le chiavi Stripe possono essere configurate anche per singolo infoshop dal pannello di gestione.

Email

Di default le email vengono stampate in console (ideale per lo sviluppo). Per inviare email reali in produzione, configurare un backend SMTP nel file .env:

EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.example.com
EMAIL_HOST_USER=your-email@example.com
EMAIL_HOST_PASSWORD=your-password

Il destinatario delle notifiche e l'indirizzo email configurato nelle impostazioni di ciascun infoshop. Se il campo email e vuoto, le notifiche non vengono inviate.

Test

uv sync --group dev
uv run pytest

Oppure con pip:

pip install -r requirements-dev.txt
pytest

Struttura URL

/                          landing page
/register/                 registrazione nuova libreria/infoshop
/login/                    login globale
/search/                   ricerca globale cross-tenant
/admin/                    admin Django
/api/v1/                   API REST
/<slug>/                   homepage infoshop/libreria
/<slug>/books/             catalogo
/<slug>/books/<id>/loan-request/  richiesta prestito (librerie con prestiti attivi)
/<slug>/cart/              carrello (solo infoshop)
/<slug>/orders/            ordini (solo infoshop)
/<slug>/manage/            pannello gestione
/<slug>/manage/loans/      gestione prestiti
/<slug>/manage/loans/requests/  richieste di prestito ricevute
/<slug>/manage/promote/    promozione libreria personale → infoshop

Licenza

Questo progetto e rilasciato sotto licenza GNU Affero General Public License v3.0.

Autore

jops