Installazione e configurazione di SplitPro come container Docker su Raspberry Pi

SplitPro è un’alternativa open source e self-hosted a Splitwise, pensata per gestire e dividere le spese con amici, coinquilini o famigliari senza dover affidare i propri dati a servizi di terze parti. Il progetto è interamente open source, sviluppato in Next.js, e può essere installato molto facilmente tramite Docker.

Panoramica delle caratteristiche:

• Gestione di spese singole (con un amico) o di gruppo
• Diversi metodi di suddivisione: in parti uguali, percentuale, quote, importo esatto, aggiustamenti manuali e saldi (settlements)
• Categorie, valute multiple, date e allegati (ricevute/scontrini) per ogni spesa
• Supporto per le spese negative, utili per rimborsi e correzioni
• Applicazione PWA, installabile su smartphone, con supporto alle notifiche push
• Feed delle attività, comprensivo di modifiche e cancellazioni
• Bilanci dettagliati, sia per singola persona che per gruppo
• Conversione automatica tra valute diverse
• Importazione di amici e gruppi da Splitwise
• Spese ricorrenti (richiede l’estensione Postgres pg_cron)
• Autenticazione tramite email (magic link), Google OAuth oppure provider OIDC (Authentik, Keycloak, ecc.)

È possibile ottenere maggiori informazioni a riguardo qui (sito ufficiale) oppure qui (repository GitHub del progetto).

Fatta questa premessa, per poter procedere all’installazione di SplitPro come container in Docker è ovviamente necessario disporre di:

• Un Raspberry Pi (o un qualsiasi host Linux/NAS);
• Docker e Docker Compose installati (qui una guida su come installarlo su Raspberry Pi);
• Un DDNS o un indirizzo IP Pubblico (per accesso da remoto);

Detto questo, procediamo con la creazione di una cartella che a sua volta conterrà il file compose.yml necessario per creare e configurare i nostri container.

mkdir splitpro
cd splitpro
nano compose.yml

e riportiamo quanto segue (configurazione ufficiale consigliata dal progetto, con Postgres già predisposto per le spese ricorrenti grazie a pg_cron):

name: split-pro-prod

services:
  postgres:
    image: ossapps/postgres:17.7-trixie
    container_name: ${POSTGRES_CONTAINER_NAME:-splitpro-db}
    restart: always
    environment:
      - POSTGRES_USER=${POSTGRES_USER:?err}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?err}
      - POSTGRES_DB=${POSTGRES_DB:?err}
      - POSTGRES_PORT=${POSTGRES_PORT:-5432}
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}']
      interval: 10s
      timeout: 5s
      retries: 5
    command: >
      postgres
      -c shared_preload_libraries=pg_cron
      -c cron.database_name=${POSTGRES_DB:-splitpro}
      -c cron.timezone=UTC
    env_file: .env
    volumes:
      - database:/var/lib/postgresql/data

  splitpro:
    image: ossapps/splitpro:latest
    container_name: splitpro
    restart: always
    ports:
      - ${PORT:-3000}:${PORT:-3000}
    environment:
      - PORT=${PORT:-3000}
      # - HOSTNAME=0.0.0.0 # da scommentare se si utilizza un reverse proxy (es. NGINX Proxy Manager) tramite rete Docker interna
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - uploads:/app/uploads

volumes:
  database:
  uploads:

Una volta incollato il testo, possiamo chiudere il file digitando CRTL+X dopo di che digitiamo Y o S (a seconda della lingua impostata) ed infine premiamo il tasto ENTER per confermare.

Come si può notare, il file compose.yml fa riferimento a diverse variabili d’ambiente che andremo a definire in un file .env, per cui procediamo alla sua creazione:

nano .env

e riportiamo quanto segue, sostituendo i valori evidenziati con i propri:

# Nome del container e credenziali del database Postgres
POSTGRES_CONTAINER_NAME=splitpro-db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=una-password-sicura
POSTGRES_DB=splitpro
POSTGRES_PORT=5432
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@splitpro-db:5432/${POSTGRES_DB}

# Porta sulla quale verrà pubblicata l'applicazione
PORT=3000

# Next Auth: chiave segreta utilizzata per firmare le sessioni
NEXTAUTH_SECRET=chiave-generata-con-openssl
NEXTAUTH_URL=http://IP-DEL-TUO-SERVER:3000

# Inviti e registrazione
ENABLE_SENDING_INVITES=false
DISABLE_EMAIL_SIGNUP=false

La variabile NEXTAUTH_SECRET deve essere una stringa casuale e sicura: possiamo generarla comodamente da terminale con il comando:

openssl rand -base64 32

Il valore NEXTAUTH_URL deve invece corrispondere all’indirizzo (IP oppure dominio) con cui raggiungeremo SplitPro, comprensivo di porta se non utilizziamo un reverse proxy.

Configurazione dell’autenticazione

SplitPro non prevede un login classico con username e password: è necessario configurare almeno uno tra i seguenti metodi di accesso, aggiungendo le relative variabili all’interno del file .env:

• Email (magic link), tramite un server SMTP: FROM_EMAIL, EMAIL_SERVER_HOST, EMAIL_SERVER_PORT, EMAIL_SERVER_USER, EMAIL_SERVER_PASSWORD
• Google OAuth: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
• OIDC (Authentik, Keycloak o provider generico): AUTHENTIK_ID/AUTHENTIK_SECRET/AUTHENTIK_ISSUER, oppure le variabili equivalenti per Keycloak o un provider OIDC custom

Un’altra funzionalità opzionale sono le notifiche push (necessarie per l’app PWA): per abilitarle occorre generare una coppia di chiavi VAPID con il comando

npx web-push generate-vapid-keys --json

e riportare i valori ottenuti nelle variabili WEB_PUSH_PUBLIC_KEY, WEB_PUSH_PRIVATE_KEY e WEB_PUSH_EMAIL (quest’ultima è un semplice indirizzo email di contatto richiesto dallo standard Web Push).

Tutte le variabili opzionali (incluse quelle per l’integrazione con conti bancari tramite GoCardless o Plaid) sono elencate e commentate nel file .env.example presente nella repository ufficiale.

Una volta terminata la modifica del file .env, possiamo chiuderlo digitando CRTL+X dopo di che digitiamo Y o S (a seconda della lingua impostata) ed infine premiamo il tasto ENTER per confermare.

Arrivati a questo punto non ci resta che tirare su i container con il seguente comando:

docker compose up -d

Il comando scaricherà le immagini ufficiali ossapps/postgres e ossapps/splitpro e avvierà i due container: grazie alla condizione service_healthy impostata nel compose.yml, SplitPro attenderà automaticamente che il database Postgres sia pronto prima di partire.

Possiamo verificare che tutto sia partito correttamente controllando i log con:

docker compose logs -f splitpro

attendiamo qualche secondo, dopo di che apriamo il web browser che preferiamo e digitiamo nella barra dell’indirizzo:

http://[IP-DEL-TUO-SERVER]:3000

e procediamo con l’accesso utilizzando il metodo di autenticazione che abbiamo configurato in precedenza (email o Google), creando così il nostro primo account.

Per poter rendere accessibile questo servizio dall’esterno della nostra rete, dobbiamo “nattare” ad esempio la porta TCP 443 (esterna) con l’IP (LAN) del nostro server sulla porta TCP 3000. Inoltre, se avete un IP dinamico con il vostro ISP (Internet Service Provider), assicuratevi di aver configurato un DDNS (qui una guida su come abilitarlo e configurarlo utilizzando DuckDNS) oppure di disporre di un indirizzo IP Statico con un Nome di Dominio registrato.

Per esporre SplitPro in HTTPS consiglio di installare e configurare NGINX Proxy Manager (qui una guida su come installarlo come container in Docker), collegando SplitPro alla stessa rete Docker del proxy e ricordandosi di scommentare la riga HOSTNAME=0.0.0.0 nel compose.yml in modo che il servizio sia raggiungibile anche attraverso la rete interna di Docker.

Buon divertimento!