Skip to content

The open alternative to Salesforce, designed for AI.

10.4 KB
Raw Blame
---
title: Docker Compose
description: Eseguire venti in produzione con Docker Compose.
---

import { PageBanner } from "/snippets/page-banner.mdx"

## Panoramica

<Warning>
I container Docker sono destinati all'hosting in produzione o al self-hosting. Per contribuire, consulta [Configurazione locale](/it/developers/contribute/capabilities/local-setup).
</Warning>

Questa guida fornisce istruzioni passo passo per installare e configurare l'applicazione Twenty usando Docker Compose. L'obiettivo è rendere il processo semplice ed evitare gli errori comuni che potrebbero compromettere il tuo setup.

**Importante:** Modifica solo le impostazioni esplicitamente menzionate in questa guida. Modificare altre configurazioni potrebbe portare a problemi.

Consulta [Configurazione delle variabili di ambiente](/it/developers/self-host/capabilities/setup) per configurazioni avanzate. Tutte le variabili di ambiente devono essere dichiarate nel file `docker-compose.yml` a livello di server e/o di worker, a seconda della variabile.

## Requisiti di Sistema

* RAM: Assicurati che il tuo ambiente abbia almeno 2GB di RAM. Memoria insufficiente può causare arresti anomali dei processi.
* Docker & Docker Compose: Assicurati che entrambi siano installati e aggiornati.

## Opzione 1: Script a riga singola

Installa l'ultima versione stabile di Twenty con un unico comando:

```bash
bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
```

Per installare una versione specifica:

```bash
VERSION=v2.38.1 bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
```

* `VERSION` deve essere un tag di release completo pubblicato su [Docker Hub](https://hub.docker.com/r/twentycrm/twenty/tags), ad esempio `v2.38.1`. Gli alias come `v2` o `latest` non sono accettati.
* Il file `docker-compose.yml` corrispondente viene recuperato dal tag git `twenty/<version>`, quindi le release precedenti a questi tag (v2.9.0 e precedenti) non possono essere installate con lo script.

Per recuperare invece i file di configurazione da un ramo, ad esempio per testare modifiche non ancora rilasciate:

```bash
BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
```

* Sostituisci branch-name con il branch da cui recuperare `docker-compose.yml` e `.env.example`. L'immagine continua a usare per impostazione predefinita l'ultima release, a meno che non sia impostato anche `VERSION`.

## Opzione 2: Passaggi manuali

Segui questi passaggi per un setup manuale.

### Passo 1: Configura il File di Ambiente

1. **Crea il File .env**

   Copia il file di ambiente di esempio in un nuovo file .env nella tua directory di lavoro:

   ```bash
   curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example
   ```

2. **Genera una chiave di cifratura**

   Esegui il seguente comando per generare una stringa casuale unica:

   ```bash
   openssl rand -base64 32
   ```

   **Importante:** Tieni questo valore segreto / non condividerlo. La perdita di `ENCRYPTION_KEY` significa perdere l'accesso a tutti i segreti archiviati nel database (token OAuth, variabili dell'applicazione, segreti TOTP, ecc.).

3. **Aggiorna il `.env`**

   Sostituisci il valore segnaposto nel tuo file .env con il token generato:

   ```ini
   ENCRYPTION_KEY=random_string
   ```

   Consulta la [Guida alla rotazione delle chiavi](/it/developers/self-host/capabilities/key-rotation) per le istruzioni su come ruotarla senza tempi di inattività.

4. **Imposta la Password di Postgres**

   Aggiorna il valore `PG_DATABASE_PASSWORD` nel file .env con una password forte senza caratteri speciali. La password viene inserita senza codifica nell'URL di connessione Postgres, pertanto caratteri quali `@`, `/`, `#` o `%` interrompono la stringa di connessione. Generane uno con:

   ```bash
   openssl rand -hex 32
   ```

   ```ini
   PG_DATABASE_PASSWORD=my_strong_password
   ```

<Note>
Le variabili che `docker-compose.yml` inoltra senza un valore predefinito `:-`, come `SERVER_URL` e le variabili `STORAGE_S3_*`, raggiungono il server come stringa vuota quando sono vuote o mancanti in `.env`, e il server considera una stringa vuota come un valore configurato anziché non impostato. Mantieni impostato `SERVER_URL` e, quando `STORAGE_TYPE=S_3`, imposta ogni variabile `STORAGE_S3_*` richiesta: un valore `STORAGE_S3_NAME` vuoto interrompe ogni caricamento. Le variabili con un valore predefinito in `docker-compose.yml`, come le parti `PG_DATABASE_*` e `REDIS_URL`, utilizzano tale valore predefinito quando sono vuote o mancanti.
</Note>

### Passo 2: Ottieni il File Docker Compose

Scarica il file `docker-compose.yml` nella tua directory di lavoro:

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml
```

### Passo 3: Avvia l'Applicazione

Avvia i container Docker:

```bash
docker compose up -d
```

### Passo 4: Accedi all'Applicazione

Se ospiti twentyCRM sul tuo computer, apri il browser e naviga a [http://localhost:3000](http://localhost:3000).

Se lo ospiti su un server, controlla che il server sia in esecuzione e che tutto sia ok con

```bash
curl http://localhost:3000
```

## Configurazione

### Esponi Twenty per Accesso Esterno

Per impostazione predefinita, Twenty gira su `localhost` alla porta `3000`. L'interfaccia utente risolve l'API dall'origine del browser, quindi viene caricata da qualsiasi hostname che raggiunga il container — ma imposta comunque `SERVER_URL` sul tuo URL pubblico: il server lo usa per i link generati (email, callback OAuth) e per rilevare l'HTTPS per i cookie sicuri.

#### Comprendere `SERVER_URL`

* **Protocollo:** Usa `http` o `https` a seconda della tua configurazione.
  * Usa `http` se non hai configurato SSL.
  * Usa `https` se hai configurato SSL.
* **Dominio/IP:** Questo è il nome del dominio o indirizzo IP dove la tua applicazione è accessibile.
* **Porta:** Includi il numero di porta se non stai usando le porte predefinite (`80` per `http`, `443` per `https`).

### Requisiti SSL

SSL (HTTPS) è necessario affinché alcune caratteristiche del browser funzionino correttamente. Mentre queste caratteristiche potrebbero funzionare durante lo sviluppo locale (poiché i browser trattano localhost in modo diverso), è necessario un setup SSL adeguato quando si ospita Twenty su un dominio regolare.

Ad esempio, l'API degli appunti potrebbe richiedere un contesto sicuro - alcune funzionalità come i pulsanti di copia in tutta l'applicazione potrebbero non funzionare senza HTTPS abilitato.

Raccomandiamo fortemente di configurare Twenty dietro un proxy inverso con terminazione SSL per una sicurezza e funzionalità ottimali.

<Tip>Prima di esporre Twenty a Internet, leggi [Protezione dell'istanza](/it/developers/self-host/capabilities/security). La maggior parte dei team può mantenere privata l'app e aprire solo alcuni percorsi.</Tip>

#### Configurare `SERVER_URL`

1. **Determina il tuo URL di Accesso**
   * **Senza Proxy Inverso (Accesso Diretto):**

     Se accedi all'applicazione direttamente senza un proxy inverso:

     ```ini
     SERVER_URL=http://your-domain-or-ip:3000
     ```

   * **Con Proxy Inverso (Porte Standard):**

     Se usi un proxy inverso come Nginx o Traefik e hai configurato SSL:

     ```ini
     SERVER_URL=https://your-domain-or-ip
     ```

   * **Con Proxy Inverso (Porte Personalizzate):**

     Se usi porte non standard:

     ```ini
     SERVER_URL=https://your-domain-or-ip:custom-port
     ```

2. **Aggiorna il File `.env`**

   Apri il tuo file `.env` e aggiorna il `SERVER_URL`:

   ```ini
   SERVER_URL=http(s)://your-domain-or-ip:your-port
   ```

   **Esempi:**

   * Accesso diretto senza SSL:
     ```ini
     SERVER_URL=http://123.45.67.89:3000
     ```
   * Accesso tramite dominio con SSL:
     ```ini
     SERVER_URL=https://mytwentyapp.com
     ```

3. **Riavvia l'Applicazione**

   Per rendere effettive le modifiche, riavvia i container Docker:

   ```bash
   docker compose down
   docker compose up -d
   ```

#### Considerazioni

* **Configurazione del Reverse Proxy:**

  Assicurati che il tuo reverse proxy inoltri le richieste alla porta interna corretta (`3000` per impostazione predefinita). Configura la terminazione SSL e tutte le intestazioni necessarie.

* **Impostazioni Firewall:**

  Apri le porte necessarie nel tuo firewall per consentire l'accesso esterno.

* **Coerenza:**

  Il `SERVER_URL` deve corrispondere a come gli utenti accedono alla tua applicazione nei loro browser.

#### Persistenza

* **Volumi di Dati:**

  La configurazione di Docker Compose utilizza volumi per mantenere i dati per il database e l'archiviazione del server.

* **Ambienti Senza Stato:**

  Se si distribuisce in un ambiente senza stato (ad esempio, alcuni servizi di cloud), configura l'archiviazione esterna per mantenere i dati.

## Backup e ripristino

I backup regolari proteggono i dati del tuo CRM dalla perdita.

### Crea un backup del database

```bash
docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql
```

### Automatizza i backup giornalieri

Aggiungi al tuo crontab (`crontab -e`):

```bash
0 2 * * * docker exec twenty-postgres pg_dump -U postgres twenty > /backups/twenty_$(date +\%Y\%m\%d).sql
```

### Ripristina dal backup

1. Arresta l'applicazione:

```bash
docker compose stop server worker
```

2. Ripristina il database:

```bash
docker exec -i twenty-postgres psql -U postgres twenty < backup_20240115.sql
```

3. Riavvia i servizi:

```bash
docker compose up -d
```

### Pratiche migliori per i backup

* **Esegui regolarmente test di ripristino** — verifica che i backup funzionino davvero
* **Conserva i backup off-site** — usa l'archiviazione cloud (S3, GCS, ecc.)
* **Crittografa i dati sensibili** — proteggi i backup con la crittografia
* **Mantieni più copie** — conserva backup giornalieri, settimanali e mensili

## Risoluzione dei problemi

Se riscontri problemi, controlla [Risoluzione dei problemi](/it/developers/self-host/capabilities/troubleshooting) per le soluzioni.

## Hosting gestito

<Tip>
  Preferisci non gestire e mantenere Twenty in autonomia? [Trova un partner Twenty certificato](https://twenty.com/partners/list?categories=HOSTING\&ref=docs-docker-compose) per distribuire, ospitare e gestire la tua istanza end-to-end. *(Oppure contatta il nostro team: [[email protected]](mailto:[email protected]).)*
</Tip>

<PageBanner illustration="dev-self-host" />