Docker (Linux remoto)

Per utilizzare questa guida è necessario disporre di un computer remoto o di una VM distribuita. Sebbene sia possibile utilizzare questa guida con un'installazione locale, tieni presente che è stata scritta originariamente per la distribuzione nel cloud.

⚠️ Questa guida è stata originariamente progettata per Digital Ocean, quindi potresti dover modificare le istruzioni per altre piattaforme, ma il concetto principale rimane invariato.

Parte I: Installazione di Docker e altre dipendenze:

Ci sono molti modi per configurare Docker sui sistemi Linux. Ti guiderò attraverso il metodo migliore e consigliato basato su questa guida.

Nota che il modo "Migliore" per l'installazione di Docker su Ubuntu non significa il "più veloce" o il "più semplice". Significa il modo migliore per installarlo per un beneficio a lungo termine (ovvero aggiornamenti più rapidi, patch di sicurezza, ecc.).

1. Aggiorna e installa le dipendenze Docker

Per prima cosa, aggiorniamo l'elenco dei pacchetti e installiamo le dipendenze Docker necessarie.

sudo apt update

Quindi, utilizza il seguente comando per installare le dipendenze o i pacchetti prerequisiti.

sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release

Note sull'installazione

• Inserire "Y" per tutti i prompt del terminale [Y/n] (sì/no) presenti in questa guida.
• Dopo il primo prompt [Y/n], riceverai la prima di alcune schermate viola che richiedono il riavvio dei servizi.
  • Ogni volta che ciò accade, puoi premere tranquillamente INVIO per le opzioni predefinite, già selezionate:

• Se in qualsiasi momento la console del tuo droplet si disconnette, esegui le seguenti operazioni e poi riprendi da dove avevi interrotto:
  • Accedi nuovamente alla console come indicato sopra
  • Passa all'utente che hai creato con su - <yourusername>

2. Aggiungi il repository Docker alle sorgenti APT

Sebbene l'installazione di Docker Engine dai repository di Ubuntu sia più semplice, aggiungere il repository ufficiale di Docker ti garantisce aggiornamenti più rapidi. Ecco perché questo è il metodo consigliato.

Per prima cosa, recuperiamo la chiave GPG necessaria per connettersi al repository Docker. Per farlo, utilizza il seguente comando.

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Successivamente, aggiungi il repository all'elenco delle sorgenti. Sebbene sia possibile aggiungerlo anche manualmente, il comando seguente lo farà automaticamente per te.

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Il comando precedente compilerà automaticamente il nome in codice della tua release (jammy per 22.04, focal per 20.04 e bionic per 18.04).

Infine, aggiorna nuovamente i tuoi pacchetti.

sudo apt update

Se dimentichi di aggiungere la chiave GPG, il passaggio precedente fallirà con un messaggio di errore. Altrimenti, procediamo con l'installazione di Docker su Ubuntu.

3. Installare Docker

Qual è la differenza tra docker.io e docker-ce?

docker.io è il pacchetto docker offerto da alcune popolari distribuzioni Linux (ad esempio Ubuntu/Debian). docker-ce, d'altra parte, è il pacchetto docker proveniente dal repository ufficiale Docker. Solitamente docker-ce è più aggiornato e preferibile.

Ora installeremo il pacchetto docker-ce (e non il pacchetto docker.io)

sudo apt install docker-ce

Lo schermo viola significa premere INVIO. :)

Consigliato: dovresti assicurarti che l'utente creato sia aggiunto al gruppo docker per un utilizzo fluido dei comandi:

sudo usermod -aG docker $USER

Ora riavviamo il sistema per assicurarci che tutto sia a posto.

sudo reboot

Dopo il riavvio, se utilizzi la console del droplet nel browser, puoi fare clic su ricarica e attendere di rientrare nella console.

Promemoria: Ogni volta che riavvii con sudo reboot, dovresti passare all'utente che hai configurato in precedenza con su - <yourusername>.

4. Verifica che Docker sia in esecuzione su Ubuntu

Ci sono molti modi per verificare se Docker è in esecuzione su Ubuntu. Un metodo consiste nell'utilizzare il seguente comando:

sudo systemctl status docker

Dovresti vedere un output che indica active (running) come stato.

Esci da questo log premendo CTRL (o CMD) + C.

5. Installare Docker Compose

Dato che abbiamo già aggiunto il repository ufficiale di Docker nel passaggio 2, l'installazione di Docker Compose è semplice utilizzando il plugin ufficiale Compose:

sudo apt install docker-compose-plugin

Verifica l'installazione:

docker compose version

Nota: Docker Compose v2 utilizza il comando docker compose (senza trattino) invece del comando legacy docker-compose. Tutti i comandi in questa guida utilizzano la sintassi moderna.

6. Come parte di questa guida, ti consiglio di avere installato git e npm:

Sebbene non sia tecnicamente richiesto, avere git e npm renderà l'installazione/aggiornamento molto semplice:

sudo apt install git nodejs npm

Attiva le linee alla Matrix.

Puoi confermare che questi pacchetti siano stati installati correttamente con quanto segue:

git --version
node -v
npm -v

Nota: questo potrebbe installare versioni obsolete di Node.js e npm. Se esegui LibreChat direttamente sull'host, utilizza Node.js v24.16.0 con npm v11.16.0. Per questa guida basata su Docker, la versione di Node.js dell'host non è rilevante poiché LibreChat viene eseguito all'interno dei container.

Ok, ora che hai configurato il Droplet, procederai con la configurazione dell'app stessa

Parte II: Configurazione di LibreChat

1. Clona il repository

Dalla riga di comando del droplet (come tuo utente, non come root):

# clone down the repository
git clone https://github.com/danny-avila/LibreChat.git

# enter the project directory
cd LibreChat/

2. Crea i file di configurazione e ambiente di LibreChat

File di configurazione (librechat.yaml)

Successivamente, creiamo il file di configurazione di LibreChat, noto anche come librechat.yaml, che consente la personalizzazione delle impostazioni dell'app così come degli endpoint personalizzati.

Indipendentemente dal fatto che tu voglia personalizzare ulteriormente l'app, è richiesto per il file deploy-compose.yml che stiamo utilizzando, quindi possiamo crearne uno con il valore minimo indispensabile per iniziare:

nano librechat.yaml

Entrerai nella schermata dell'editor e potrai incollare quanto segue:

# For more information, see the Configuration Guide:
# https://www.librechat.ai/docs/configuration/librechat_yaml

# Configuration version (required)
version: 1.3.5
# This setting caches the config file for faster loading across app lifecycle
cache: true

Esci dall'editor con CTRL + X, poi Y per salvare e ENTER per confermare.

File di ambiente (.env)

I valori predefiniti sono sufficienti per iniziare e avviare l'app, consentendoti di fornire le tue credenziali dall'interfaccia web.

# Copies the example file as your global env file
cp .env.example .env

Tuttavia, è fortemente raccomandato modificare i valori "secret" rispetto ai loro valori predefiniti per una maggiore sicurezza. I log di avvio dell'API ti avviseranno se non lo fai.

Per comodità, puoi eseguire questo comando per generare i tuoi valori:

https://www.librechat.ai/toolkit/creds_generator

nano .env

# FIND THESE VARIABLES AND REPLACE THEIR DEFAULT VALUES!

# Must be a 16-byte IV (32 characters in hex)

CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb

# Must be 32-byte keys (64 characters in hex)

CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418

Se desideri fornire delle credenziali che tutti gli utenti della tua istanza possano utilizzare, dovresti aggiungerle mentre stai ancora modificando questo file:

OPENAI_API_KEY=sk-yourKey

Come in precedenza, esci dall'editor con CTRL + X, poi Y per salvare e ENTER per confermare.

Ecco fatto!

Per una configurazione completa, tuttavia, dovresti modificare il tuo file .env come necessario, e leggere i commenti nel file e le risorse sottostanti.

# if editing the .env file
nano .env

Questa è una delle variabili d'ambiente a cui prestare attenzione. Questa disabilita le registrazioni esterne, nel caso in cui tu voglia impostarla dopo aver creato il tuo account.

ALLOW_REGISTRATION=false

Risorse:

• Token/API/ecc.
• Sistema Utente/Autenticazione

3. Avvia Docker

# should already be running, but just to be safe
sudo systemctl start docker

# confirm docker is running
docker info

Ora possiamo avviare il container dell'app. Per la prima volta, useremo il comando completo e in seguito potremo usare un comando abbreviato.

sudo docker compose -f ./deploy-compose.yml up -d

È sicuro chiudere il terminale se lo desideri: l'applicazione Docker continuerà a essere eseguita.

Nota: questo utilizza uno speciale file compose ottimizzato per questo ambiente di distribuzione. Se desideri ulteriori configurazioni qui, dovresti esaminare i file deploy-compose.yml e Dockerfile.multi per vedere come sono configurati. Non stiamo compilando l'immagine in questo ambiente poiché non c'è abbastanza RAM per farlo correttamente. Invece, effettuiamo il pull dell'ultima immagine dev-api di LibreChat, che viene compilata automaticamente dopo ogni push al branch main.

Se stai configurando un dominio da utilizzare con LibreChat, questo file compose utilizza il file nginx situato in client/nginx.conf. Istruzioni a riguardo sono disponibili di seguito nella parte V.

4. Una volta che l'app è in esecuzione, puoi accedervi all'indirizzo http://yourserverip

Torna alla pagina del droplet per ottenere l'IP del tuo server, copialo e incollalo nel tuo browser!

Registrati, accedi e goditi il tuo LibreChat ospitato privatamente da remoto :)

Parte III: Aggiornamento di LibreChat

Ho reso questo passaggio piuttosto semplice, a condizione che tutto quanto sopra sia stato installato correttamente e che tu non abbia modificato la cronologia di git.

Nota: Se stai lavorando su un branch modificato, con i tuoi commit, ad esempio con modifiche a client/nginx.conf, dovresti esaminare config/deployed-update.js per eseguire manualmente alcuni dei comandi come ritieni opportuno. Vedi la parte V per ulteriori informazioni a riguardo.

Esegui quanto segue per un aggiornamento automatico

npm run update:deployed

Arresto del container Docker

npm run stop:deployed

Questo esegue semplicemente docker compose -f ./deploy-compose.yml down

Avvio del container Docker

npm run start:deployed

Questo esegue semplicemente docker compose -f ./deploy-compose.yml up -d

Controlla i container Docker attivi

docker ps

Puoi aggiornare manualmente senza gli script se riscontri problemi.

docker compose -f ./deploy-compose.yml down

# Linux/Mac
docker images -a | grep "librechat" | awk '{print $3}' | xargs docker rmi

# Windows (PowerShell)
docker images -a --filter "reference=registry.librechat.ai/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }
docker images -a --filter "reference=ghcr.io/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }

git pull

docker compose -f ./deploy-compose.yml pull

docker compose -f ./deploy-compose.yml up

Parte IV: Modifica del file NGINX (per domini personalizzati e configurazioni avanzate)

Nel caso in cui desiderassi modificare il file NGINX per qualsiasi motivo, come puntare il tuo server a un dominio personalizzato, utilizza quanto segue:

npm run stop:deployed

nano client/nginx.conf

Non ti guiderò nella configurazione di un dominio personalizzato o in altre modifiche a NGINX; puoi consultare la guida di Cloudflare, la guida di Traefik o la guida di NGINX per iniziare con i domini personalizzati.

Tuttavia, ti mostrerò cosa modificare sul lato LibreChat per un dominio personalizzato con questa configurazione.

Poiché NGINX viene utilizzato come proxy pass per impostazione predefinita, modifico solo quanto segue:

# before
server_name localhost;

# after
server_name custom.domain.com;

Nota: questo funziona perché il file deploy-compose.yml utilizza NGINX per impostazione predefinita, a differenza del file docker-compose.yml principale. Come sempre, puoi configurare i file compose come preferisci.

Ora esegui il commit di queste modifiche su un branch separato:

# create a new branch
# example: git checkout -b edit
git checkout -b <branchname>

# stage all file changes
git add .

Per eseguire il commit delle modifiche su un branch git, dovrai identificarti su git. Questi possono essere valori fittizi, ma se desideri che si sincronizzino con GitHub, nel caso in cui tu esegua il push di questo branch su un repository forked di LibreChat, utilizza la tua email GitHub.

# these values will work if you don't care what they are
git config --global user.email "[email protected]"
git config --global user.name "Your Name"

# Now you can commit the change
git commit -m "edited nginx.conf"

L'aggiornamento su un branch modificato funzionerà in modo leggermente diverso ora

npm run rebase:deployed

Dovresti essere a posto!

Avviso Riscontrerai conflitti di merge se inizi a modificare significativamente il branch e questo non è raccomandato a meno che tu non sappia cosa stai facendo

Nota che qualsiasi modifica al codice in questo ambiente non verrà riflessa perché il file compose sta eseguendo il pull delle immagini Docker create automaticamente da GitHub.

Parte V: Utilizzare l'ultima versione stabile invece dell'ultimo branch main

Per impostazione predefinita, questa configurazione scaricherà gli ultimi aggiornamenti del branch main di LibreChat. Se preferisci utilizzare l'ultima release "stabile", definita dai latest tags, dovrai modificare deploy-compose.yml ed eseguire il commit delle tue modifiche esattamente come indicato sopra nella Parte V. Tieni presente che, in tal caso, non potrai beneficiare delle funzionalità più recenti non appena vengono rilasciate.

Modifichiamo deploy-compose.yml:

nano deploy-compose.yml

Cambia librechat-dev-api in librechat-api:

image: registry.librechat.ai/danny-avila/librechat-api:latest

Metti in stage e fai il commit come nella Parte V, e sei pronto!