Distribuzione

Come eseguire NexoSaaS: stack Docker, reverse proxy host, dominio di base e TLS.

Cosa stai distribuendo

I siti NexoPOS dei clienti non sono servizi Compose separati. L’agente scrive i file in HOST_AGENT_HOME_BASE e nginx include i suoi vhost.

1. Installazione di Docker

Prerequisiti

• Docker Engine + Docker Compose v2
• Porte libere (predefinite): 8080 (HTTP), 3307 (host MySQL), 6380 (host Redis)

Passaggi

# From the repository root
cp deploy/.env.docker.example .env

# Optional: set a stable public URL early (production example)
# APP_URL=https://app.yourdomain.com
# APP_ENV=production
# APP_DEBUG=false

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

Gli entrypoint di solito generano APP_KEY e avviano le migrazioni quando configurati. Popola il catalogo + l’amministratore predefinito una volta:

docker compose -f deploy/docker-compose.yml exec app php artisan db:seed --force

Account predefiniti con seed (solo per sviluppo):

Apri il control plane: http://localhost:8080 (oppure la tua APP_URL).

Prontezza:

docker compose -f deploy/docker-compose.yml exec app php artisan platform:launch-check

Variabili d’ambiente importanti

I segreti del prodotto (Stripe, SMTP, GitHub PAT, S3, policy del dominio) sono in **Admin → Impostazioni**, non nelle variabili d’ambiente di runtime.

Modalità dell’agente host

Compose non è di per sé una storia completa di isolamento in produzione multi-tenant. Usa uno script su un VPS quando ti serve una separazione dei tenant di livello production.

2. Metti Nginx davanti allo stack

Forma di produzione consigliata:

Internet
   │
   ▼
Host Nginx / Caddy  (TLS termination, :443)
   │  proxy_pass → 127.0.0.1:8080
   ▼
Compose nginx       (control plane + tenant includes)
   │
   ▼
Compose app (PHP-FPM) + tenant docroots on volume

Esempio host Nginx (piano di controllo)

Sostituisci i nomi host e la porta upstream con i tuoi.

# /etc/nginx/sites-available/nexosaas-control.conf
server {
    listen 80;
    server_name app.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name app.yourdomain.com;

    # ssl_certificate     /etc/letsencrypt/live/app.yourdomain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/app.yourdomain.com/privkey.pem;

    client_max_body_size 64M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}

Imposta:

APP_URL=https://app.yourdomain.com

Laravel si fida degli header inoltrati quando è configurato per la tua configurazione proxy; assicurati che l’app veda correttamente HTTPS, così gli URL firmati e i cookie restano sicuri.

Segnaposto per screenshot: Browser aperto sulla schermata di accesso del control plane al tuo URL HTTPS pubblico

Nomi host del tenant

• Docker / local agent: le configurazioni nginx del tenant sono scritte in {HOST_AGENT_HOME_BASE}/.platform/nginx-enabled/*.conf e incluse da nginx di Compose (deploy/docker/nginx/default.conf).
• Browser locale : http://{install-subdomain}.localhost:8080 spesso funziona senza /etc/hosts.
• Produzione: DNS per *.base_domain (e domini personalizzati) deve raggiungere lo stesso edge che può instradare verso il nginx della piattaforma (oppure il nginx del VPS gestito dall’agent dello script).

Se il reverse proxy dell’host inoltra solo app.yourdomain.com, i sottodomini dei tenant devono avere una delle seguenti opzioni:

• lo stesso proxy con un server_name con carattere jolly / oppure con blocchi server separati, o
• esposizione diretta della piattaforma nginx / vhost gestiti dall’agente.

Pianifica DNS e TLS per i tenant insieme al dominio di base (sezione successiva).

3. Dominio di base

Le installazioni ottengono un nome host della piattaforma gratuito:

{slug}.{base_domain}

Esempio: dominio di base saas.example.com → acme-store.saas.example.com.

Configura in Admin

1. Accedi come amministratore della piattaforma (2FA fuori sede).
2. Apri Amministrazione → Impostazioni → Dominio.
3. Imposta:

DNS

Il valore PLATFORM_BASE_DOMAIN in .env imposta solo il valore Admin nelle impostazioni vuote; in runtime usa Admin → Dominio.

4. SSL / Let’s Encrypt

Piano di controllo (reverse proxy host)

Utilizzando Certbot (esempio):

# After DNS for app.yourdomain.com points at the VPS
sudo certbot --nginx -d app.yourdomain.com
# or: certbot certonly --webroot ... then point ssl_certificate paths

Usare Caddy spesso è più semplice (HTTPS automatico); reverse_proxy su 127.0.0.1:8080.

Certificati del conduttore

Per la verifica di provisioning e del dominio personalizzato, l’agente host è responsabile della TLS per i nomi host del tenant (flusso in stile Let’s Encrypt sul percorso VPS/agent).

Gli operatori dovrebbero:

1. Assicurati che il VPS possa completare la HTTP-01 (o la sfida scelta dall’agente) per i nomi host di installazione.
2. Imposta in modo ragionevole le modifiche del dominio verificate al giorno (impostazione predefinita: 3) per evitare che i clienti esauriscano i limiti di velocità di LE.
3. Mantieni accurato l’IPv4 pubblico affinché le istruzioni DNS che i clienti vedono siano corrette.

Nota: Docker locale con *.localhost non richiede LE pubbliche per i test UI quotidiani.

Webhook dei pagamenti

I gateway di produzione devono raggiungere endpoint HTTPS, ad esempio:

• https://app.yourdomain.com/webhooks/stripe
• https://app.yourdomain.com/webhooks/paddle
• https://app.yourdomain.com/webhooks/mollie

Configura i segreti di firma in Admin → Impostazioni → Impostazioni di fatturazione.

5. Checklist post-deploy

Comandi operativi utili

# Shell into app
docker compose -f deploy/docker-compose.yml exec app bash

# Logs
docker compose -f deploy/docker-compose.yml logs -f app horizon nginx

# Rebuild frontend assets
docker compose -f deploy/docker-compose.yml run --rm -e DOCKER_FORCE_BUILD_ASSETS=true assets

# Wipe evaluation installs (keeps users/catalog/settings)
docker compose -f deploy/docker-compose.yml exec app \
  php artisan platform:reset-evaluation --force