Installare HitKeep con Homebrew su macOS e Linux

Homebrew è il percorso di installazione supportato più diretto per HitKeep su macOS con Apple Silicon e su Ubuntu Linux con AMD64 o ARM64. Il tap ufficiale installa la versione stabile corrente del binario hitkeep; HitKeep continua ad archiviare i dati localmente e usa la stessa configurazione di ogni altra installazione self-hosted.

Piattaforma	Supporto Homebrew
macOS ARM64 (Apple Silicon)	Verificato dalla CI
Ubuntu Linux AMD64/x86_64	Verificato dalla CI con Linuxbrew
Ubuntu Linux ARM64	Verificato dalla CI con Linuxbrew

A ogni rilascio, la CI installa la formula stabile, la aggiorna alla release candidate, verifica la versione installata, esegue brew test e la disinstalla su tutte le piattaforme elencate.

Avvio rapido

Installa HitKeep dal tap ufficiale:

brew install PascaleBeier/hitkeep/hitkeep
hitkeep --version

Crea directory persistenti esplicite, genera un segreto di sessione e avvia un’istanza locale:

mkdir -p "$HOME/.local/share/hitkeep"/{data,archive,backups}

export HITKEEP_PUBLIC_URL=http://localhost:8080
export HITKEEP_JWT_SECRET="$(openssl rand -hex 32)"
export HITKEEP_BIND_ADDR=127.0.0.1:7946
export HITKEEP_DB_PATH="$HOME/.local/share/hitkeep/data/hitkeep.db"
export HITKEEP_DATA_PATH="$HOME/.local/share/hitkeep/data"
export HITKEEP_ARCHIVE_PATH="$HOME/.local/share/hitkeep/archive"
export HITKEEP_BACKUP_PATH="$HOME/.local/share/hitkeep/backups"

hitkeep

Apri http://localhost:8080 e completa la procedura guidata di configurazione.

Conserva il segreto di sessione

Il comando precedente serve per un avvio rapido locale. Prima di affidarti a questa istanza, conserva un unico valore stabile di HITKEEP_JWT_SECRET in un file d’ambiente con permessi limitati oppure nella configurazione del servizio. Generare un segreto diverso a ogni avvio disconnette gli utenti.

Consulta il riferimento di configurazione per URL di produzione, posta, storage, S3, MCP e impostazioni AI opzionali.

Verifica

In un altro terminale, controlla la formula installata, esegui il test della formula del tap e interroga entrambe le sonde di runtime:

brew list --versions hitkeep
brew test PascaleBeier/hitkeep/hitkeep
curl --fail http://localhost:8080/healthz
curl --fail http://localhost:8080/readyz

/healthz conferma che il processo è attivo. /readyz conferma che il database condiviso e tutti i database dei tenant aperti sono pronti a servire traffico.

Aggiornamento

Leggi le note di rilascio, quindi aggiorna i metadati Homebrew e la formula:

brew update
brew upgrade hitkeep
brew list --versions hitkeep

Dopo l’aggiornamento, riavvia il processo HitKeep. Homebrew sostituisce l’eseguibile senza spostare né eliminare i percorsi dati configurati.

Backup

L’avvio rapido abilita il worker di backup con checkpoint di HitKeep in $HOME/.local/share/hitkeep/backups. Conserva questa directory su storage durevole e prova un ripristino prima di considerarla un backup di produzione.

Un piano di backup completo comprende:

• il percorso configurato in HITKEEP_DB_PATH;
• l’intero HITKEEP_DATA_PATH, incluso tenants/*/hitkeep.db;
• i percorsi configurati per archivi e backup;
• eventuali oggetti S3 esterni quando questi percorsi usano URL s3://.

Consulta Backup e ripristino per le procedure di ripristino e Backup S3 per lo storage fuori macchina.

Note per la produzione

• Termina HTTPS davanti a HitKeep e imposta HITKEEP_PUBLIC_URL sull’URL esatto visibile nel browser.
• Configura i proxy attendibili quando il traffico passa attraverso un reverse proxy o un bilanciatore di carico.
• Esegui HitKeep con un service manager di macOS se deve avviarsi automaticamente; non inserire segreti nella cronologia della shell o negli argomenti del comando del servizio.
• Per server gestiti con systemd, usa la guida al binario Linux.