DataBase per Collezzionisti via Web

Per la mia collezione di carte Pokemon (poteva essere di monete o altro) uso un App a pagamento che ha anche un accesso via Web. Il costo però è piuttosto alto, circa 50 euro ad anno, ho deciso quindi di creare qualcosa di mio.

Avendo un PC su cui ho installato il sistema di virtualizzazione Proxmox, posso creare virtual machine VM a costo zero. Avendo anche una linea internet in Fibra, anche la parte di connettività è eccellente.

Ho quindi creato una nuova VM linux su base Debian ultima release, dando 2 CPU, 4G di Ram e 40Gb di disco. Durante l’installazione dare come nome macchina “pokemon” o quello che volete, nella sezione dominio non mettere nulla e infine alla schermata “Software selection” Lascia selezionato solo:

✅ SSH server

✅ Standard system utilities

e deseleziona:

❌ Debian desktop environment

❌ GNOME

❌ KDE

❌ XFCE

❌ Web server

❌ Tutto il resto

Vogliamo una Debian server minimale.

Da root esegui:
apt update
apt full-upgrade -y

al termine:
reboot

Rientra poi nella VM e verifica che sia tutto ok:

uname -a
apt list --upgradable

Se il secondo comando non mostra pacchetti da aggiornare (o ne mostra pochissimi), siamo pronti per il passo successivo.

Da root esegui:
apt install -y docker.io docker-compose-v2 git curl nano

Al termine verifica: 
docker --version

e anche:
docker compose version

Dovresti ottenere qualcosa di simile: Docker version 28.x, Docker Compose version v2.x

Poi crea la struttura del progetto:

mkdir -p /opt/pokemon
cd /opt/pokemon

verifica con:
pwd

deve mostrare:
/opt/pokemon

Installa quindi Docker-Compose:
apt install -y docker.io docker-compose git curl nano

Poi verifica:

Verifica che Docker parta automaticamente

systemctl enable --now docker
systemctl status docker

Dovrebbe comparire:
active (running)

Crea la struttura del progetto:

mkdir -p /opt/pokemon
cd /opt/pokemon

Verifica:
pwd

Output atteso:
/opt/pokemon

Poi crea le cartelle del progetto:

mkdir postgres backend frontend backups imports
ls -l

Dovresti vedere:
backend
backups
frontend
imports
postgres

Creare docker-compose.yml

cd /opt/pokemon
nano docker-compose.yml

Aperto il file inserisci:

services:
  postgres:
    image: postgres:17
    container_name: pokemon-postgres
    restart: unless-stopped

    environment:
      POSTGRES_DB: pokemon
      POSTGRES_USER: pokemon
      POSTGRES_PASSWORD: pokemon123

    ports:
      - "5432:5432"

    volumes:
      - ./postgres:/var/lib/postgresql/data

Per salvare CTRL+X e poi Y e invio

Avvio del database

docker-compose up -d
docker ps

Dovresti vedere qualcosa simile a:
pokemon-postgres
postgres:17
Up

Verifica PostGres

sempre da Root esegui:

docker exec -it pokemon-postgres psql -U pokemon -d pokemon

Se tutto è corretto vedrai:
pokemon=#

digita:
SELECT version();

vedrai una struttura vuota che però indica che il DB è funzionante e pronto ad essere riempito, per uscire digita:
q
e torni al prompt PostgreSQL:
pokemon=#

Poi esci da PostgreSQL:
\q

Abbiamo completato tutta la parte infrastrutturale.

Prossimo passo: progettare il database

Prima di creare le tabelle voglio che decidiamo bene come gestire la collezione.

La mia proposta è:

Catalogo Ufficiale (contiene tutte le carte esistenti)
- sets
- cards

Collezione Paolo (Marco.. Giada etc..) contiene solo quelle possedute
- collection

Come registrare le copie? Ti propongo questa struttura:
Carta: Charizard ex 125/197
- Quantità: 3
- Lingua: ITA
- Condizione: Near Mint

e una seconda riga:
- Quantità: 1
- Lingua: ENG
- Condizione: Mint

Così puoi distinguere facilmente le varie versioni senza complicare troppo il database

Il DB sarà anche multiutente

Fase 1 – Creazione schema database V1

Entriamo in PostgreSQL:
docker exec -it pokemon-postgres psql -U pokemon -d pokemon

Creiamo la Tabella utenti digitando:
CREATE TABLE users (
    id              BIGSERIAL PRIMARY KEY,
    username        VARCHAR(50) UNIQUE NOT NULL,
    email           VARCHAR(255) UNIQUE NOT NULL,
    password_hash   VARCHAR(255) NOT NULL,
    display_name    VARCHAR(100),
    is_admin        BOOLEAN DEFAULT FALSE,
    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Per la Tabella Espansioni digitare:
CREATE TABLE sets (
    id              VARCHAR(50) PRIMARY KEY,
    name            VARCHAR(255) NOT NULL,
    series          VARCHAR(255),
    release_date    DATE,
    total_cards     INTEGER,
    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Per la Tabella Carte digitare:
CREATE TABLE cards (
    id              VARCHAR(100) PRIMARY KEY,
    set_id          VARCHAR(50) NOT NULL,

    card_number     VARCHAR(20),
    name            VARCHAR(255) NOT NULL,

    rarity          VARCHAR(100),
    supertype       VARCHAR(100),

    image_small     TEXT,
    image_large     TEXT,

    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    CONSTRAINT fk_cards_set
      FOREIGN KEY (set_id)
      REFERENCES sets(id)
);

Per la Tabella Collezioni digitare:
CREATE TABLE collection (
    id              BIGSERIAL PRIMARY KEY,

    user_id         BIGINT NOT NULL,
    card_id         VARCHAR(100) NOT NULL,

    quantity        INTEGER NOT NULL DEFAULT 1,

    language        VARCHAR(10) NOT NULL,
    condition       VARCHAR(30) NOT NULL,

    variant         VARCHAR(30) NOT NULL,

    graded          BOOLEAN DEFAULT FALSE,

    notes           TEXT,

    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    CONSTRAINT fk_collection_user
      FOREIGN KEY (user_id)
      REFERENCES users(id),

    CONSTRAINT fk_collection_card
      FOREIGN KEY (card_id)
      REFERENCES cards(id)
);

Per la Tabella Wishlist digitare:
CREATE TABLE wishlist (
    id              BIGSERIAL PRIMARY KEY,

    user_id         BIGINT NOT NULL,
    card_id         VARCHAR(100) NOT NULL,

    priority        SMALLINT DEFAULT 1,
    notes           TEXT,

    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    CONSTRAINT fk_wishlist_user
      FOREIGN KEY (user_id)
      REFERENCES users(id),

    CONSTRAINT fk_wishlist_card
      FOREIGN KEY (card_id)
      REFERENCES cards(id)
);

Per la Tabella Indici digitare:
CREATE INDEX idx_cards_name
ON cards(name);

CREATE INDEX idx_cards_set
ON cards(set_id);

CREATE INDEX idx_collection_user
ON collection(user_id);

CREATE INDEX idx_collection_card
ON collection(card_id);

Primo utente amministratore:
INSERT INTO users (
    username,
    email,
    password_hash,
    display_name,
    is_admin
)
VALUES (
    'paolo',
    'paolo@local',
    'TEMP',
    'Paolo',
    TRUE
);

Verifica finale:
\dt

Dovresti vedere:
cards
collection
sets
users
wishlist

Per verifica l'utente:
SELECT * FROM users;

Prossimo passo: Backend FastAPI

/opt/pokemon

├── backend
├── frontend
├── postgres
├── imports
└── docker-compose.yml

Creiamo il backend:
cd /opt/pokemon/backend
mkdir app
cd app
touch main.py

Verifica: (se non hai tree: apt install tree -y)
tree /opt/pokemon/backend

Dovresti vedere:
backend
└── app
    └── main.py

Esegui:
mkdir -p /opt/pokemon/backend/app
touch /opt/pokemon/backend/app/main.py

Adesso creiamo il primo backend minimale e lo facciamo girare in Docker. Passo 1: file Python

nano /opt/pokemon/backend/app/main.py

Il resto della guida nei prossimi giorni..