Ospita Map Blueprint su un server cloud

Metti la tua istanza su un server sempre attivo, un computer che gira in un data center 24 ore su 24, così i compagni da remoto possono raggiungerlo da ovunque, con il tuo indirizzo web e HTTPS gratuito (il lucchetto che cripta la connessione). Questa guida usa il piano Always-Free di Oracle Cloud, che può eseguire Map Blueprint senza costi mensili, ma gli stessi passaggi funzionano su qualsiasi server cloud Ubuntu.

Cosa otterrai alla fine: un piccolo server Linux che esegue Map Blueprint senza sosta, raggiungibile a un indirizzo come https://maps.yourdomain.com, protetto dalla password del tuo team e che si riavvia automaticamente dopo i riavvii. Metti in conto circa 20–30 minuti. Ovunque vedi YOUR_… qui sotto, sostituiscilo con il tuo valore.

Preferisci eseguirlo semplicemente sul tuo portatile? Vedi la guida all'hosting locale.

Qualche parola che incontrerai: un server è un computer che gira sempre così che altri possano connettersi; SSH è un modo sicuro per digitare comandi su quel computer remoto dal tuo; un dominio è il tuo indirizzo web (come yourdomain.com); DNS è la rubrica di internet che punta un dominio a un server; HTTPS è la versione crittografata e con lucchetto di un indirizzo web; un reverse proxy e un tunnel sono due modi per mettere HTTPS davanti all'app. Niente paura, ogni passaggio qui sotto ti dice esattamente cosa fare.

Passo 1, Crea un server gratuito

Registrati su Oracle Cloud Free Tier e accedi alla console (il sito web di Oracle per gestire i tuoi server).
Vai su Compute → Instances → Create instance. Un'"instance" è semplicemente il termine di Oracle per indicare un server.
Scegli una shape idonea al piano Always-Free (la dimensione del server, "shape" è il termine di Oracle). Vanno bene entrambe: VM.Standard.E2.1.Micro o una shape Arm Ampere (che ha più memoria). Mantieni l'immagine predefinita Ubuntu, Ubuntu è la versione di Linux usata da questa guida.
Sotto Add SSH keys, scegli Generate a key pair for me e scarica la chiave privata, questo piccolo file è ciò che dimostra che sei tu quando accedi, quindi conservalo in un luogo sicuro. (Hai già una tua chiave? Incolla invece la sua metà pubblica.)
Clicca su Create. Quando il server è in esecuzione, copia il suo Public IP address (il numero del server su internet), questa guida lo chiama YOUR_SERVER_IP.

Passo 2, Apri il firewall

Un firewall blocca le connessioni di rete inattese. Oracle blocca il traffico web in entrata di default, quindi devi consentirlo sulle due porte web standard, 80 (web normale) e 443 (web sicuro):

Apri la tua instance → clicca sulla sua Virtual Cloud Network / subnet → Security Lists → la lista predefinita. (Questo è il firewall di Oracle.)
Aggiungi Ingress Rules ("ingress" significa semplicemente in entrata) che consentano TCP da 0.0.0.0/0 (cioè "da ovunque") alle porte 80 e 443.

Ubuntu su Oracle ha anche il proprio firewall locale. Dopo esserti connesso nel Passo 3, consenti le stesse due porte incollando queste tre righe (ogni riga è un comando; la terza salva la regola così che sopravviva ai riavvii):

sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 80 -j ACCEPT
sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 443 -j ACCEPT
sudo netfilter-persistent save

Se usi l'opzione Cloudflare Tunnel nel Passo 5, puoi evitare del tutto di aprire le porte 80/443.

Passo 3, Connettiti al server

Ora accederai al server e digiterai comandi su di esso dal tuo computer, usando SSH. Apri un terminale (su Windows, usa PowerShell, include già ssh) ed esegui questo, puntando -i al file della chiave privata che hai scaricato:

ssh -i /path/to/YOUR_PRIVATE_KEY ubuntu@YOUR_SERVER_IP

Su Mac o Linux, se ricevi un errore "permissions are too open" relativo alla chiave, esegui prima chmod 600 /path/to/YOUR_PRIVATE_KEY, questo restringe il file così che solo tu possa leggerlo, come richiede SSH.

Una volta connesso (il prompt dei comandi ora mostra il server), installa gli ultimi aggiornamenti di sistema:

sudo apt update && sudo apt upgrade -y

sudo significa "esegui questo come amministratore"; apt è l'installatore di app integrato di Ubuntu.

Passo 4, Carica e avvia Map Blueprint

Non c'è nulla da installare sul server, niente Docker, niente Node, nessun .env. È un unico programma autonomo. Dal tuo computer (una nuova finestra di terminale, non la sessione SSH), esegui questo dalla cartella in cui hai decompresso il download per copiare il programma Linux sul server. scp sta per "secure copy", invia un file sulla stessa connessione SSH sicura:

scp -i /path/to/YOUR_PRIVATE_KEY ./map-blueprint-linux ubuntu@YOUR_SERVER_IP:~/

Tornato nella sessione SSH, rendi il programma eseguibile e avvialo. HOST=0.0.0.0 gli dice di accettare connessioni dall'esterno, così il passo HTTPS successivo può raggiungerlo:

chmod +x ~/map-blueprint-linux
HOST=0.0.0.0 ~/map-blueprint-linux

Ora è in ascolto sulla porta 8080. Imposterai la password del tuo team dal browser una volta predisposto l'HTTPS (passo successivo). Per ora, premi Ctrl-C per arrestarlo, il Passo 6 lo trasforma in un servizio che gira 24 ore su 24.

config.json e le tue mappe in data/ vengono creati proprio accanto al programma nella tua home folder (~/). Tutte le impostazioni si trovano nella pagina Impostazioni dell'app, non c'è alcun file da modificare.

Passo 5, Aggiungi il tuo dominio e l'HTTPS gratuito

L'app parla HTTP normale ed è progettata per stare dietro qualcosa che aggiunge l'HTTPS (il lucchetto crittografato). Scegli uno di questi due approcci, l'Opzione A è la più facile da mettere in sicurezza.

Opzione A, Cloudflare Tunnel (nessuna porta aperta, la più facile da mettere in sicurezza)

Un tunnel connette il tuo server verso Cloudflare, così i visitatori raggiungono l'app attraverso Cloudflare senza che alcuna porta sia aperta sul tuo server.

Aggiungi il tuo dominio a un account Cloudflare gratuito.

Sul server, installa cloudflared (lo strumento di tunnel di Cloudflare) e accedi:

curl -fsSL https://pkg.cloudflare.com/install.sh | sudo bash
sudo apt install -y cloudflared
cloudflared tunnel login

Crea un tunnel e punta l'indirizzo web che hai scelto alla porta locale dell'app:

cloudflared tunnel create mapblueprint
cloudflared tunnel route dns mapblueprint maps.YOURDOMAIN.com

Indica al tunnel di inviare il traffico a http://localhost:8080 nella sua configurazione, poi installalo come servizio in background così che giri sempre:
```
sudo cloudflared service install
```

Cloudflare crea e rinnova automaticamente il certificato HTTPS per te, e nulla sul tuo server è esposto direttamente, puoi lasciare chiuse le porte 80/443.

Opzione B, Reverse proxy Caddy (certificato automatico)

Caddy è un piccolo web server che si mette davanti all'app, aggiunge l'HTTPS e inoltra i visitatori a essa, è ciò che fa un reverse proxy.

Punta un record A DNS per maps.YOURDOMAIN.com a YOUR_SERVER_IP. (Un "record A" è la voce DNS che associa un nome all'IP di un server, impostalo presso il tuo registrar di domini o provider DNS.)
Installa Caddy sul server.
Inserisci questo nel file /etc/caddy/Caddyfile (dice a Caddy: servi questo indirizzo e inoltra i visitatori all'app sulla porta 8080):
```
maps.YOURDOMAIN.com {
    reverse_proxy localhost:8080
}
```
Ricarica Caddy così che recepisca la modifica:
```
sudo systemctl reload caddy
```

Caddy ottiene e rinnova automaticamente un certificato Let's Encrypt gratuito per te. Questa opzione richiede le porte 80 e 443 aperte (Passo 2).

Map Blueprint contrassegna automaticamente il suo cookie di login come Secure una volta che le richieste arrivano via HTTPS (legge l'header X-Forwarded-Proto che entrambe le opzioni qui sopra impostano), così i login sono protetti senza alcuna configurazione aggiuntiva.

Visita https://maps.YOURDOMAIN.com, dovresti vedere la pagina di login. Accedi e condividi quel link con il tuo team.

Facoltativo, blindalo con Cloudflare Zero Trust

Vuoi un secondo lucchetto, più robusto? L'"Access" di Cloudflare Zero Trust mette una schermata di login davanti alla tua app, così gli estranei non raggiungono nemmeno Map Blueprint, Cloudflare verifica prima chi sei. Funziona al meglio con l'Opzione A (il Cloudflare Tunnel) qui sopra, e ti permette di concedere l'accesso persona per persona tramite email invece di condividere un'unica password. È gratuito per piccoli team.

Nella dashboard di Cloudflare, apri Zero Trust (configura il piano gratuito se è la prima volta).
Vai su Access → Applications → Add an application → Self-hosted.
Imposta il dominio dell'applicazione sullo stesso indirizzo web servito dal tunnel (maps.YOURDOMAIN.com).
Aggiungi una Access policy che consenta solo gli indirizzi email dei tuoi compagni (o un intero dominio email come @yourstudio.com), poi salva.
Ora visitando il sito compare un login di Cloudflare che invia via email un codice PIN monouso (oppure usa l'accesso Google / GitHub). Solo le persone approvate arrivano all'app.

Questo è lo stesso tipo di controllo d'identità che i creatori di Map Blueprint usano sulla loro mappa interna. Anche se qualcuno scopre il tuo URL, non può caricare l'app senza superare il controllo d'identità, ideale per una mappa privata di studio.

Passo 6, Mantienilo in esecuzione dopo i riavvii

Infine, trasforma l'app in un servizio così che si avvii all'accensione e si riavvii da solo se mai si arrestasse. (Un "servizio" è un programma di cui Linux si prende cura in background.) Salva il testo qui sotto come il file /etc/systemd/system/map-blueprint.service:

[Unit]
Description=Map Blueprint
After=network.target

[Service]
WorkingDirectory=/home/ubuntu
Environment=HOST=0.0.0.0
ExecStart=/home/ubuntu/map-blueprint-linux
Restart=always
User=ubuntu

[Install]
WantedBy=multi-user.target

Poi attivalo, ricarica la lista dei servizi, abilitalo e avvialo, e verifica che sia in esecuzione:

sudo systemctl daemon-reload
sudo systemctl enable --now map-blueprint.service
sudo systemctl status map-blueprint.service

WorkingDirectory=/home/ubuntu mantiene config.json e le tue mappe in data/ nella home folder, accanto al programma. Ora apri https://maps.YOURDOMAIN.com, completa la schermata di Setup del primo avvio e imposta subito la password del tuo team. (Preferisci impostarla in anticipo? Aggiungi Environment=APP_PASSWORD=YOUR_PASSWORD al file del servizio.)

Checklist di sicurezza

Imposta una password robusta e univoca nella schermata di Setup del primo avvio, è la cosa principale che protegge l'accesso alle tue mappe. (I login restano validi automaticamente attraverso i riavvii.)
Raggiungi sempre l'app via HTTPS (Passo 5), mai in http://YOUR_SERVER_IP:8080 nell'uso reale.
Per una protezione extra, aggiungi Cloudflare Zero Trust (qui sopra) così che solo le persone approvate possano anche solo caricare l'app.
Mantieni il server aggiornato: esegui sudo apt update && sudo apt upgrade -y di tanto in tanto.
Proteggi la tua chiave privata SSH e non condividerla mai. Valuta di limitare l'SSH (porta 22) al tuo IP nella security list.
Fai il backup della cartella data/ (e di config.json) regolarmente, è lì che vivono le tue mappe e le tue impostazioni.

Aggiornare a una nuova versione

Quando ottieni un programma aggiornato, arresta il servizio, sostituisci il file del programma e riavvialo, il tuo config.json e le mappe in data/ restano intatti. Carica il nuovo map-blueprint-linux dal tuo computer (con scp, come nel Passo 4), poi sul server esegui:

sudo systemctl stop map-blueprint.service
chmod +x ~/map-blueprint-linux
sudo systemctl start map-blueprint.service