Creare e Avviare un Progetto Koa.js con ServBay

ServBay è un ambiente di sviluppo Web locale progettato appositamente per macOS, che integra vari tool frequentemente utilizzati dagli sviluppatori, tra cui il runtime Node.js e diversi sistemi database. Questa guida ti illustrerà come sfruttare la praticità dell’ambiente ServBay per creare, avviare e gestire velocemente il tuo progetto Koa.js.

Cos'è Koa.js?

Koa.js è un framework web di nuova generazione basato su Node.js, sviluppato dal team di Express.js. È noto per la sua semplicità, espressività e potenti funzionalità, rivelandosi la scelta ideale per costruire applicazioni web e API. Koa.js sfrutta al massimo le moderne funzionalità di JavaScript, in particolare la sintassi async/await, semplificando notevolmente la scrittura di middleware e operazioni asincrone, rendendo il codice più chiaro e facile da mantenere.

Caratteristiche principali di Koa.js

• Basato su async/await: Il design ruota attorno a async/await, rendendo intuitivo il controllo dei flussi asincroni.
• Core leggero: La libreria core di Koa è estremamente snella e include solo funzionalità di base; le estensioni avvengono tramite middleware modulari.
• Middleware potente: Adotta una gestione dei middleware a cascata che rende il flusso delle richieste chiaro e flessibile.
• Focalizzato sul Web: Ottimizzato per applicazioni web e API, evita funzionalità extra e superflue.

Grazie a Koa.js, gli sviluppatori possono creare servizi web performanti e facili da mantenere, in modo più efficiente.

Configurare l’Ambiente di Sviluppo Koa.js con ServBay

ServBay fornisce agli sviluppatori Node.js un ambiente pronto all’uso, integrando il runtime Node.js e diversi servizi database. Combinando la funzione Website di ServBay, è possibile accedere facilmente ai progetti Koa.js locali tramite dominio personalizzato e certificato SSL.

Prerequisiti

Prima di iniziare, assicurati di aver completato quanto segue:

1. Installazione di ServBay: Visita il sito ufficiale di ServBay per scaricare e installare la versione più recente.
2. Installazione del pacchetto Node.js: Apri ServBay, accedi alla sezione Packages e assicurati di aver installato la versione di Node.js necessaria. Se non è presente, selezionala e avvia l’installazione.
3. Familiarità con le funzionalità di base di ServBay: Assicurati di saper avviare/arrestare i servizi e gestire i siti Web (Website) all’interno di ServBay.

Creare un Progetto Koa.js

Utilizzeremo la directory root consigliata da ServBay /Applications/ServBay/www per conservare i file del progetto.

1. Inizializzare la directory del progetto

   Apri l'applicazione Terminale e naviga nella root del sito ServBay. Crea una nuova cartella per il progetto (ad esempio servbay-koa-app), accedi alla cartella e inizializza il progetto Node.js:

   cd /Applications/ServBay/www
   mkdir servbay-koa-app
   cd servbay-koa-app
   npm init -y

   Il comando npm init -y genera rapidamente un file package.json di default.

2. Installare Koa.js

   All’interno della cartella del progetto servbay-koa-app, installa Koa.js e le relative tipizzazioni (se usi TypeScript):

   npm install koa
   # Se usi TypeScript, installa le tipizzazioni
   # npm install @types/koa --save-dev

3. Creare il file di ingresso dell'applicazione

   Nella directory servbay-koa-app, crea un file chiamato app.js ed inserisci il seguente codice base di un’app Koa.js:

   const Koa = require('koa');
   const app = new Koa();
   
   // Middleware: registra informazioni sulla richiesta
   app.use(async (ctx, next) => {
     const start = Date.now();
     await next();
     const ms = Date.now() - start;
     console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
   });
   
   // Middleware: gestisce la richiesta al percorso root
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // Definisce la porta, usa prima la variabile d'ambiente PORT
   const port = process.env.PORT || 3000;
   
   // Avvia il server HTTP
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   Questo codice crea una semplice app Koa con due middleware: uno per monitorare tempo di richiesta e percorso, l’altro per rispondere alle richieste sulla / con “Hello from ServBay Koa.js App!”. L’app ascolta sulla porta specificata dalla variabile d’ambiente PORT oppure sulla 3000 di default.

Modalità di Sviluppo

Durante lo sviluppo, normalmente si avvia un processo Node.js locale per l’app Koa.js, accedendovi tramite la funzione Website di ServBay.

1. Avviare il server di sviluppo Koa.js

   Apri il terminale, accedi alla cartella del progetto servbay-koa-app e avvia app.js tramite node. Per evitare conflitti di porta o facilitare la configurazione ServBay, possiamo specificare una porta dedicata, ad esempio 8585:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8585 node app.js

   Il terminale mostrerà un messaggio come Koa.js server running on http://localhost:8585, indicando che il server è partito e in ascolto sulla porta 8585. Mantieni aperta questa finestra mentre il server è attivo.

2. Configurare il reverse proxy di ServBay Website

   Per accedere alla app Koa.js in esecuzione su localhost:8585 tramite dominio personalizzato, occorre configurare un nuovo Website in ServBay usando il reverse proxy.

   • Avvia ServBay.
   • Accedi alla sezione Website.
   • Clicca sul pulsante + in basso a sinistra per aggiungere un nuovo sito.
   • Inserisci la configurazione del sito:
     • Nome: ServBay Koa.js Dev Site
     • Dominio: servbay-koa-dev.servbay.demo (si consiglia di usare il suffisso .servbay.demo per attivare l’SSL automatico con ServBay)
     • Tipo: seleziona Reverse Proxy
     • Indirizzo IP: 127.0.0.1 (punta al processo Node.js locale)
     • Porta: 8585 (punta alla porta della app Koa.js)
     • Document Root: per il reverse proxy non è rilevante; puoi lasciarlo vuoto o inserire il percorso del progetto /Applications/ServBay/www/servbay-koa-app.
   • Salva la configurazione.
   • Se richiesto, clicca su applica per confermare le modifiche.

   ServBay aggiornerà automaticamente il file hosts del sistema puntando servbay-koa-dev.servbay.demo a 127.0.0.1 e tramite il suo server Caddy o Nginx inoltrerà le richieste verso localhost:8585. Usando un dominio .servbay.demo, ServBay User CA genererà e rilascerà automaticamente un certificato SSL attendibile, così potrai accedere in maniera sicura tramite HTTPS.

   Se desideri istruzioni dettagliate, consulta la documentazione ServBay sulla creazione di un sito Node.js di sviluppo (scegli la versione inglese).

3. Accedere al sito di sviluppo Koa.js

   Apri il browser e visita https://servbay-koa-dev.servbay.demo.

   Se la configurazione è corretta, vedrai la pagina che mostra “Hello from ServBay Koa.js App!”. In pratica, stai accedendo al server di sviluppo Koa.js tramite il reverse proxy gestito da ServBay. Modificando il file app.js e riavviando Node.js, basterà ricaricare la pagina per vedere i cambiamenti.

Simulazione Deploy di Produzione

Quando vuoi simulare un ambiente produttivo, puoi utilizzare una porta o variabili ambiente differenti. Il reverse proxy configurato da ServBay si presta perfettamente anche a questa modalità.

1. Avviare il server di produzione Koa.js (simulato)

   In un nuovo terminale, arresta il server di sviluppo se ancora attivo, quindi esegui l'app in modalità "produzione" su una porta diversa, ad esempio 8586, impostando la variabile NODE_ENV:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8586 NODE_ENV=production node app.js

   Ora la app Koa.js ascolterà sulla porta 8586, simulando una situazione di produzione.

2. Configurare il reverse proxy di ServBay Website (per la produzione simulata)

   Come prima, configura un nuovo sito in ServBay per simulare l’ambiente di produzione:

   • Apri ServBay e accedi alla sezione Website.
   • Clicca sul pulsante + in basso a sinistra per aggiungere un sito.
   • Inserisci la configurazione:
     • Nome: ServBay Koa.js Prod Site
     • Dominio: servbay-koa-prod.servbay.demo (oppure un tuo dominio personale, richiedendo il certificato SSL gratuito tramite ACME/Let's Encrypt)
     • Tipo: seleziona Reverse Proxy
     • Indirizzo IP: 127.0.0.1
     • Porta: 8586 (porta della app Koa.js in produzione simulata)
     • Document Root: vuoto o percorso del progetto.
   • Salva e applica le modifiche.

   Il dominio .servbay.demo continuerà a utilizzare il certificato ServBay User CA. Se usi un dominio personalizzato pubblico, ServBay supporta la richiesta e la gestione automatica di certificati SSL/TLS gratuiti via ACME, ad esempio Let's Encrypt — per ulteriori dettagli consulta la documentazione ServBay sulla protezione SSL del sito.

3. Accedere al sito di produzione Koa.js (simulato)

   Avvia il browser e visita https://servbay-koa-prod.servbay.demo.

   Vedrai lo stesso output dell’ambiente di sviluppo, ma stavolta la richiesta passerà attraverso il reverse proxy verso il processo Node.js in ascolto sulla porta 8586.

Connessione ai Database

ServBay integra i principali database di uso comune, tra cui MongoDB, Redis, MariaDB (compatibile MySQL) e PostgreSQL. Collegarsi a questi database all’interno del progetto Koa.js è molto semplice, poiché sono in esecuzione localmente e, in configurazione predefinita, accessibili tramite localhost.

Segue una serie di esempi per collegarsi ai database integrati tramite driver Node.js. Assicurati che il relativo database sia installato ed in esecuzione su ServBay (nella sezione Packages).

1. Connessione a MongoDB

   Prima di tutto, installa il driver per Node.js (ad esempio mongoose o mongodb):

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # oppure npm install mongodb

   Poi, aggiungi il codice per connetterti al database nel file app.js o in un altro modulo:

   // Connetti a MongoDB usando Mongoose
   const mongoose = require('mongoose');
   
   // Per impostazione predefinita, MongoDB ServBay non richiede autenticazione; il nome DB è personalizzabile
   mongoose.connect('mongodb://localhost:27017/servbay-koa-app', {
     useNewUrlParser: true,
     useUnifiedTopology: true
   })
   .then(() => console.log('Connected to MongoDB'))
   .catch(err => console.error('MongoDB connection error:', err));
   
   // Nota: nella pratica, la connessione al DB va gestita prima di avviare il server applicativo
   // e solo a connessione avvenuta inizia l'ascolto delle richieste.

   Il servizio MongoDB installato con ServBay ascolta di default sulla porta 27017 e normalmente non richiede username/password.

2. Connessione a Redis

   Installa la libreria client per Redis:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install redis

   Esempio di connessione a Redis:

   // Connessione a Redis tramite il client redis
   const redis = require('redis');
   
   // Crea il client, di default su localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // Porta predefinita Redis in ServBay
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Avvia la connessione
   client.connect();
   
   // Nota: attendi la conferma della connessione prima di eseguire operazioni Redis
   // Es: usa async/await insieme a client.connect()

   Redis di default in ServBay ascolta sulla porta 6379 e non richiede password.

3. Connessione a MariaDB (o MySQL)

   MariaDB è una derivazione di MySQL e mantiene piena compatibilità con l’API. ServBay integra MariaDB come pacchetto e puoi usarlo come un comune database MySQL.

   Installa il driver Node.js per MariaDB:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # oppure npm install mysql2 (più raccomandato)

   Collegamento tramite mariadb:

   // Connessione a MariaDB via client mariadb
   const mariadb = require('mariadb');
   
   // Password root predefinita in ServBay: 'password'
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Crea la base dati o modifica questo nome se necessario
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB");
       conn.release(); // Rilascia la connessione al pool
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // Nota: l'acquisizione della connessione dal pool è asincrona

   Collegamento tramite mysql2 (consigliato):

   // Connessione a MariaDB/MySQL tramite mysql2 (versione promise)
   const mysql = require('mysql2/promise'); // Usa la versione promessa
   
   // Password root predefinita in ServBay: 'password'
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Assicurati che il database sia stato creato
     waitForConnections: true,
     connectionLimit: 10,
     queueLimit: 0
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB/MySQL using mysql2");
       conn.release();
     })
     .catch(err => {
       console.error("MariaDB/MySQL connection error:", err);
     });
   
   // Nota: la password root di default si trova nelle impostazioni di ServBay GUI.
   // Sconsigliata la codifica in chiaro delle password: usa variabili d'ambiente!

   In ServBay, MariaDB ascolta sulla porta 3306. Username e password di default si trovano nella GUI; crea il database servbay_koa_app tramite ServBay o strumenti come TablePlus, DBeaver ecc.

4. Connessione a PostgreSQL

   Installa il driver node per PostgreSQL:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install pg

   Collegamento a PostgreSQL:

   // Connessione a PostgreSQL tramite client pg
   const { Pool } = require('pg');
   
   // Utente predefinito ServBay: 'user' con password 'password'
   const pool = new Pool({
     user: 'user', // Utente preimpostato
     host: 'localhost',
     database: 'servbay_koa_app', // Assicurati che il db sia stato creato
     password: 'password', // Password preimpostata
     port: 5432, // Porta predefinita PostgreSQL ServBay
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release();
   });
   
   // Nota: username/password di default sono visibili nell’interfaccia database di ServBay.
   // Per la sicurezza, evita la password in chiaro e usa variabili d’ambiente dove possibile.

   PostgreSQL di default ascolta sulla 5432. Tale database o utente possono essere gestiti via GUI oppure client grafici; crea la base dati servbay_koa_app se necessario.

Gestione Database in ServBay

Oltre che via codice, puoi amministrare i database integrati in ServBay tramite client grafici. I database sono configurati per rispondere su 127.0.0.1 o localhost usando le porte, username e password indicate da ServBay.

• Visualizzare/modificare password predefinite: All’interno di ServBay, accedi al pacchetto database, clicca sull’icona delle impostazioni per vedere/modificare username e password di default (come root per MariaDB o user per PostgreSQL).
• Creare database/utenti: Usa client come TablePlus, DBeaver, pgAdmin, MongoDB Compass, e collegati ai servizi database forniti da ServBay per creare database, utenti e tabelle tramite SQL o l’interfaccia grafica.

Avvertenze

• Conflitti di porte: Scegli porte (es. 8585, 8586) che non siano già occupate da altri processi del sistema.
• Stato ServBay: Assicurati che siano attivi sia l’applicazione ServBay sia i vari pacchetti Node.js o database necessari.
• File hosts: ServBay aggiorna automaticamente /etc/hosts. In caso di problemi con la risoluzione DNS, verifica la presenza dei domini nel file hosts.
• Firewall: Controlla che il firewall di macOS o software di terze parti non blocchino ServBay o Node.js sulle porte si cui necessiti comunicare.
• Log di sistema: In caso di malfunzionamenti, consulta i log di ServBay (nella rispettiva interfaccia) e quelli degli output Node.js dal terminale, utili per risalire alle cause.

FAQ (Domande Frequenti)

• Domanda: Perché dovrei usare il reverse proxy di ServBay per accedere al mio progetto Koa.js?

  Risposta: Il reverse proxy tramite la funzione Website di ServBay offre molti vantaggi:

  1. Simulazione ambiente produttivo: Usare un dominio personalizzato (come .servbay.demo o il tuo) è più simile all’ambiente reale rispetto a localhost:PORT.
  2. Supporto SSL automatico: ServBay può configurare automaticamente il certificato SSL (via User CA o Let's Encrypt) per il tuo sito locale, quindi hai HTTPS anche in sviluppo.
  3. Gestione centralizzata: Puoi gestire facilmente tutti i progetti web locali da un unico pannello.
  4. Mascheramento delle porte: Il browser (o utenti esterni, se configurato) si connette sulle porte standard 80/443, ma internamente il proxy inoltra alle porte alte usate da Node.js.

• Domanda: Posso accedere direttamente al server Koa.js tramite localhost:PORT senza il reverse proxy?

  Risposta: Sì. Se la tua app Koa.js ascolta direttamente su una porta (es. 3000 o qualsiasi altra), puoi accedere localmente tramite http://localhost:PORT per test e sviluppo. Tuttavia, perderai le comodità offerte da ServBay (dominio personalizzato, SSL automatico, gestione log avanzata…) e il test non rifletterà un vero ambiente production. Per uno sviluppo più fedele e integrato, si consiglia l’uso del reverse proxy di ServBay.

• Domanda: Qual è la password predefinita dei database ServBay? Come posso modificarla?

  Risposta: Le password standard dei database integrati sono visibili nella sezione Database di ServBay: basta cliccare sul pacchetto (ad esempio MariaDB o PostgreSQL) e poi l’icona impostazioni. Normalmente vedrai i dati d’accesso e potrai modificarli direttamente. Per la sicurezza, è consigliato cambiare la password predefinita.

Conclusione

Seguendo questa guida, hai imparato come creare un ambiente Koa.js su macOS utilizzando ServBay. Hai configurato una semplice app Koa.js, impostato il reverse proxy tramite la funzione Website di ServBay per l’accesso tramite dominio personalizzato e HTTPS, sia in sviluppo che in ambiente di produzione simulato. Inoltre, hai scoperto come collegare la tua app ai principali database integrati in ServBay.

ServBay offre agli sviluppatori Node.js un ambiente integrato e semplice da gestire, permettendoti di concentrarti sul codice senza doverti disperdere nelle configurazioni. Sfruttando al massimo le potenzialità di ServBay potrai aumentare notevolmente la produttività ed efficienza nello sviluppo.