Vai al contenuto

Linux (consigliato)

Queste istruzioni sono rivolte a chi amministra l'istanza (profilo più tecnico-operativo).

Prerequisiti (Ubuntu)

  1. Installa le dipendenze:
sudo apt update && sudo apt install -y git docker.io docker-compose-plugin
  1. Aggiungi il tuo utente al gruppo Docker:
sudo usermod -aG docker $USER
  1. Effettua logout/login per applicare il permesso del gruppo.

Osservazione:

  • Se non disponi di permessi di root, usa sudo quando necessario.

Installazione

  1. Scarica il repository ed entra nella cartella:
git clone https://gitlab.com/yndexa/farinha.git
cd farinha
  1. Avvia Farinha:
./run.sh

Alla prima esecuzione, run.sh:

  • crea automaticamente il file .env a partire da .env-sample;
  • chiede quale sarà l'indirizzo pubblico di Farinha (in portoghese e inglese). Se ancora non lo conosci, premi Enter per lasciarlo vuoto e proseguire; potrai modificare .env in seguito;
  • genera una SECRET_KEY sicura, senza dipendere da Django installato sul server;
  • crea un utente amministratore admin con password casuale, mostrata in console una sola volta. Annota la password prima di chiudere il terminale.

La chiave automatica non contiene $. Se crei manualmente una SECRET_KEY e questa contiene $, lo script avviserà che Docker Compose può interpretare questo carattere come variabile d'ambiente e proporrà di generare una nuova chiave sicura.

Per determinare quale ambiente sarà usato (sviluppo o produzione), lo script legge la variabile ENV dal .env. Il file .env-sample include ENV=prod e DEBUG=False, valori adatti a un'installazione reale.

HTTPS e certificati

Farinha usa Caddy per servire HTTPS:

  • Con un indirizzo pubblico configurato, i certificati gratuiti vengono ottenuti e rinnovati automaticamente.
  • Per usare certificati propri, inserisci fullchain.pem e privkey.pem nella cartella certs/, nella radice del progetto.
  • Senza indirizzo pubblico e senza certificati propri (ad esempio, localhost), HTTPS viene disattivato automaticamente.

Vedi i dettagli in Sicurezza e HTTPS, inclusa la variabile DISABLE_HTTPS e la protezione contro i bot (Anubis).

Regolazione manuale opzionale

Se devi rivedere o modificare le impostazioni, apri .env con il tuo editor di testo preferito:

nano .env

Aggiornamento

  1. Entra nella cartella in cui Farinha è stato installato:
cd farinha
  1. Arresta, aggiorna e riavvia:
./down.sh && git pull && ./run.sh

Buone pratiche

  • Annota la password dell'utente admin mostrata alla prima esecuzione; non viene più visualizzata.
  • Mantieni DEBUG=False nel .env nelle installazioni reali.
  • Fai un backup del database (db/) prima degli aggiornamenti e conserva la cartella certs/ se usi certificati propri.
  • Preferisci aggiornare arrestando e riavviando tutto (down + pull + run), invece di ricreare un solo container.

Problemi comuni

  • "permission denied" durante l'uso di Docker: il tuo utente non è nel gruppo Docker. Esegui sudo usermod -aG docker $USER ed effettua logout/login (oppure usa sudo, quando appropriato).
  • Lo script si arresta senza avviarsi: verifica che la SECRET_KEY sia presente nel .env e non contenga $.
  • Ho perso la password dell'utente admin: crea un altro superutente dal terminale, all'interno del container:
docker compose -f docker-compose.prod.yml exec web python manage.py createsuperuser
  • Riesco ad accedere solo via HTTP: con localhost o un IP, HTTPS viene disattivato; configura un dominio o certificati propri. Vedi Sicurezza e HTTPS.
  • Il pannello interno non si apre su /admin/: qualcuno potrebbe aver modificato ADMIN_PATH nel .env. Vedi Utente SuperAdmin.