Creare e avviare un progetto Koa.js con ServBay

ServBay è un ambiente di sviluppo web locale disponibile per macOS e Windows, che integra vari pacchetti utili per gli sviluppatori, inclusi il runtime Node.js e diversi database. In questo articolo scoprirai come sfruttare l'ambiente integrato di 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. Si distingue per la sua sintassi essenziale, espressiva e dotata di potenti funzionalità, risultando la soluzione ideale per lo sviluppo di applicazioni web e API. Koa.js sfrutta al massimo le caratteristiche moderne di JavaScript, in particolare la sintassi async/await, semplificando notevolmente la gestione delle operazioni asincrone e la scrittura degli middleware. Il risultato è un codice più pulito e facilmente manutenibile.

Caratteristiche principali di Koa.js

• Basato su async/await: Progettato intorno all’uso di async/await, per un controllo dei flussi asincroni più intuitivo.
• Core leggero: La libreria di base di Koa è essenziale e include solo le funzioni fondamentali; le feature avanzate si aggiungono tramite middleware modulari.
• Middleware potenti: Gestione dei middleware a cascata, che rende il flusso di gestione delle richieste chiaro e flessibile.
• Focus sul web: Concentrato sullo sviluppo di web app e API, senza funzionalità aggiuntive superflue.

Con Koa.js, gli sviluppatori possono costruire servizi web performanti e manutenibili in modo più efficiente.

Configurare l'ambiente di sviluppo Koa.js con ServBay

ServBay offre agli sviluppatori Node.js un ambiente pronto all’uso, con runtime Node.js e servizi database comuni già integrati. Grazie alla funzione Website di ServBay, puoi facilmente accedere localmente al tuo progetto Koa.js usando un dominio personalizzato e certificati SSL.

Prerequisiti

Prima di iniziare, assicurati di aver completato questi passaggi:

1. Installare ServBay: Vai al sito ufficiale ServBay per scaricare e installare l’ultima versione.
2. Installare il pacchetto Node.js: Avvia ServBay e accedi alla sezione Packages; verifica di aver installato la versione di Node.js necessaria. In caso contrario, selezionala e procedi con l’installazione.
3. Familiarizzare con ServBay: Scopri come avviare/fermare servizi e gestire i Website tramite l’interfaccia di ServBay.

Creazione di un progetto Koa.js

Consigliamo di usare la directory root di ServBay /Applications/ServBay/www per memorizzare i file di progetto.

1. Inizializzare la directory del progetto

   Apri il Terminale, naviga nella directory root di ServBay, crea una nuova cartella per il progetto (es. servbay-koa-app), entra nella 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

   Dalla root del progetto servbay-koa-app, installa Koa.js (e, se usi TypeScript, le definizioni dei tipi):

   npm install koa
   # Se usi TypeScript, aggiungi anche le definizioni dei tipi
   # npm install @types/koa --save-dev

3. Creazione del file d’ingresso dell’app

   Crea un file app.js nella directory principale del progetto e aggiungi il seguente codice per una semplice 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 le richieste alla root
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // Definisci la porta, usa l’ambiente PORT se disponibile
   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 applicazione Koa con due middleware: uno per loggare tempo e percorso delle richieste, l’altro per gestire la rotta / rispondendo con "Hello from ServBay Koa.js App!". L’applicazione ascolta sulla porta definita dalla variabile d’ambiente PORT o, in mancanza, sulla 3000.

Modalità di sviluppo

Durante lo sviluppo, avvierai localmente un processo Node.js per la tua app Koa.js, e accederai tramite la funzione Website di ServBay.

1. Avviare il server di sviluppo Koa.js

   Apri il Terminale, vai nella directory del progetto servbay-koa-app e avvia app.js con node. Per evitare conflitti di porta e facilitare la configurazione ServBay, puoi scegliere una porta specifica come 8585:

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

   Il terminale mostrerà un messaggio simile a Koa.js server running on http://localhost:8585, confermando l’avvio del server sulla porta 8585. Mantieni la finestra del Terminale aperta per farlo funzionare in continuazione.

2. Configurare il reverse proxy Website su ServBay

   Per accedere all’app Koa.js tramite un dominio personalizzato sulla porta 8585, configura un nuovo Website di tipo reverse proxy:

   • Avvia ServBay.
   • Vai sulla sezione Website.
   • Premi il pulsante + in basso a sinistra per aggiungere un nuovo sito.
   • Compila la configurazione:
     • Nome: ServBay Koa.js Dev Site
     • Dominio: servbay-koa-dev.servbay.demo (consigliato il suffisso .servbay.demo che permette la generazione automatica del certificato SSL)
     • Tipo: scegli Reverse Proxy
     • Indirizzo IP: 127.0.0.1 (punta al processo Node.js locale)
     • Porta: 8585 (la porta della tua app Koa.js)
     • Document Root: non fondamentale per il reverse proxy, può rimanere vuoto o indicare /Applications/ServBay/www/servbay-koa-app.
   • Salva la configurazione.
   • Se richiesto, applica le modifiche.

   Al termine, ServBay aggiornerà il file hosts locale, indirizzando servbay-koa-dev.servbay.demo verso 127.0.0.1 e, tramite i server interni Caddy o Nginx, proxyerà le richieste verso la porta 8585 locale. Grazie al dominio .servbay.demo, ServBay User CA genererà e installerà automaticamente il certificato SSL affinché tu possa accedere in modo sicuro tramite HTTPS.

   Per istruzioni dettagliate, consulta la documentazione ServBay sull’aggiunta di un sito Node.js di sviluppo (scegli la versione inglese).

3. Accedere al sito Koa.js di sviluppo

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

   Se tutto è configurato correttamente vedrai la pagina con "Hello from ServBay Koa.js App!". Significa che stai accedendo attivamente al server di sviluppo Koa.js locale tramite ServBay. Modifica app.js e riavvia Node.js per vedere eventuali cambiamenti dopo il refresh del browser.

Simulare la modalità produzione

In una simulazione di ambiente produzione potresti usare porte, variabili d’ambiente o opzioni di avvio diverse. La configurazione reverse proxy di ServBay è valida anche in questi casi.

1. Avviare il server Koa.js in modalità produzione (simulata)

   Apri un nuovo Terminale, ferma il server di sviluppo se ancora in esecuzione, quindi avvia l’app come simulazione produzione usando, ad esempio, la porta 8586 e l’ambiente NODE_ENV:

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

   L’app sarà ora accessibile sulla porta 8586, in una modalità che simula la produzione.

2. Configurare reverse proxy Website per la simulazione produzione

   Allo stesso modo, su ServBay crea un nuovo Website:

   • Avvia ServBay, vai su Website.
   • Premi + per aggiungere un sito nuovo.
   • Compila la configurazione:
     • Nome: ServBay Koa.js Prod Site
     • Dominio: servbay-koa-prod.servbay.demo (oppure usa il tuo dominio, con ServBay puoi richiedere SSL gratuito da Let's Encrypt)
     • Tipo: Reverse Proxy
     • IP: 127.0.0.1
     • Porta: 8586 (la porta della simulazione produzione)
     • Document Root: lascia vuoto o indica il percorso progetto.
   • Salva e applica.

   Usando il dominio .servbay.demo si applicherà automaticamente il certificato ServBay User CA. Se usi un dominio pubblico, ServBay supporta la generazione e gestione SSL/TLS gratuiti tramite ACME (Let's Encrypt), avvicinando ancora di più la simulazione alla produzione reale. Consulta la documentazione ServBay relativa alla protezione SSL dei siti.

3. Accedere al sito Koa.js in produzione simulata

   Dal browser, visita https://servbay-koa-prod.servbay.demo.

   Vedrai la stessa pagina della modalità sviluppo, ma ora le richieste sono proxyate dalla porta 8586 tramite ServBay.

Collegamento ai database

ServBay integra i principali sistemi database: MongoDB, Redis, MariaDB (compatibile MySQL) e PostgreSQL. Dentro il tuo progetto Koa.js puoi accedere facilmente a questi database che girano localmente e prevedono accesso via localhost di default.

Ecco alcuni esempi di codice con driver Node.js per la connessione ai database di ServBay. Assicurati che i pacchetti database ServBay siano installati e attivi tramite la sezione Packages.

1. Collegarsi a MongoDB

   Nella cartella del tuo progetto Koa.js, installa il driver Node.js per MongoDB (mongoose o mongodb):

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

   Nel file app.js (o moduli separati) aggiungi il seguente codice:

   // Connessione a MongoDB tramite Mongoose
   const mongoose = require('mongoose');
   
   // MongoDB di default su ServBay non richiede autenticazione
   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: Nelle applicazioni reali la connessione andrebbe gestita nella fase di avvio
   // e il server avviato solo dopo una connessione positiva.

   MongoDB su ServBay ascolta di default sulla porta 27017, senza necessità di user/password. Specifica semplicemente il nome database (verrà creato se non esiste).

2. Collegarsi a Redis

   Installa il client Redis per Node.js:

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

   Collegati al server Redis:

   // Connessione a Redis tramite 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 ServBay
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Connessione al server Redis
   client.connect();
   
   // Nota: Nelle applicazioni reali, utilizzare async/await per gestire la connessione
   // prima di eseguire operazioni su Redis

   Redis su ServBay utilizza la porta 6379 senza password di default.

3. Collegarsi a MariaDB (MySQL)

   MariaDB è un fork di MySQL, pienamente compatibile. ServBay include il pacchetto MariaDB, che puoi usare come MySQL standard.

   Installa il driver MariaDB per Node.js:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # oppure npm install mysql2 (consigliato per maggiore compatibilità)

   Connessione tramite mariadb:

   // Connessione a MariaDB tramite client mariadb
   const mariadb = require('mariadb');
   
   // Password root predefinita: 'password'
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Il database deve essere creato in precedenza
     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’ottenimento della connessione dal pool è asincrono

   Connessione tramite mysql2 (consigliato):

   // Connessione a MariaDB/MySQL tramite client mysql2 (Promise-based)
   const mysql = require('mysql2/promise');
   
   // Password root predefinita: 'password'
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Database da creare anticipatamente
     waitForConnections: true,
     connectionLimit: 10,
     queueLimit: 0
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB/MySQL using mysql2");
       conn.release(); // Rilascia la connessione al pool
     })
     .catch(err => {
       console.error("MariaDB/MySQL connection error:", err);
     });
   
   // Nota: La password root può essere visualizzata e modificata nel pannello database di ServBay.
   // Per sicurezza, preferisci gestire le password tramite variabili d’ambiente.

   MariaDB su ServBay ascolta sulla porta 3306. La password di default per l’utente root è disponibile nel pannello di gestione database. Potresti dover creare manualmente il database servbay_koa_app tramite ServBay o client desktop come TablePlus, DBeaver ecc.

4. Collegarsi a PostgreSQL

   Installa il driver Node.js per PostgreSQL:

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

   Connessione al server PostgreSQL:

   // Connessione a PostgreSQL tramite client pg
   const { Pool } = require('pg');
   
   // Utente 'user' e password 'password' di default
   const pool = new Pool({
     user: 'user', // Utente predefinito ServBay
     host: 'localhost',
     database: 'servbay_koa_app', // Assicurati che il database esista
     password: 'password', // Password predefinita ServBay
     port: 5432, // Porta PostgreSQL predefinita
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release(); // Rilascia la connessione al pool
   });
   
   // Nota: La password e l’utente sono visibili e modificabili dal pannello database ServBay.
   // Meglio non codificare le password direttamente nel codice.

   PostgreSQL su ServBay gira sulla porta 5432. Le credenziali di default sono modificabili nel pannello database ServBay e il database va creato manualmente se non esiste.

Gestire i database in ServBay

Oltre alla connessione tramite codice, puoi usare client grafici per collegarti ai database ServBay. Tutti i servizi database sono locali (127.0.0.1 / localhost), user/password e porta sono visibili nel pannello GUI di ServBay.

• Visualizzare/modificare la password di default: Clicca sull’icona impostazioni accanto al database desiderato nel pannello ServBay per vedere o modificare le credenziali.
• Creare database/utenti: Usa strumenti come TablePlus, DBeaver, pgAdmin, MongoDB Compass per collegarti e gestire database, utenti e tabelle via SQL o interfaccia grafica.

Attenzione

• Conflitti di porta: Assicurati che la porta scelta per Koa.js (es. 8585, 8586) non sia già usata da altri programmi.
• Stato di ServBay: Verifica che ServBay e tutti i pacchetti Node.js/database siano attivi.
• File hosts: ServBay gestisce automaticamente il file hosts, ma se ci sono problemi di risoluzione dominio, controlla /etc/hosts per la presenza delle entry corrette.
• Firewall: Verifica che firewall macOS o di terze parti non blocchino ServBay o Node.js.
• Log: In caso di problematiche, consulta i log di ServBay (scheda apposita nella GUI) e le uscite del Terminale Node.js per diagnosticare.

Domande Frequenti (FAQ)

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

  Risposta: L’utilizzo del reverse proxy tramite la funzione Website di ServBay offre diversi vantaggi:

  1. Simulazione ambiente produzione: Accedi al sito tramite un dominio personalizzato (es. .servbay.demo o dominio personale) invece di localhost:PORT, simulando meglio l’accesso reale.
  2. Supporto SSL: ServBay configura automaticamente certificati SSL (User CA o Let's Encrypt) per i tuoi siti locali, permettendo test HTTPS anche in sviluppo.
  3. Gestione centralizzata: Puoi amministrare tutti i tuoi siti di sviluppo da un’unica interfaccia comoda.
  4. Port hiding: L’accesso avviene su porte standard 80/443, mentre il reverse proxy inoltra internamente alle porte Node.js dedicate.

• Domanda: Posso evitare il reverse proxy e accedere direttamente via localhost:PORT?

  Risposta: Sì. Puoi accedere al tuo Koa.js localmente tramite http://localhost:PORT per sviluppo e test. Tuttavia, in questo modo perdi il supporto di ServBay per i domini personalizzati, l’SSL automatico e la gestione avanzata dei log. Per simulare meglio la produzione è consigliato utilizzare il reverse proxy di ServBay.

• Domanda: Qual è la password predefinita dei database di ServBay? Come la cambio?

  Risposta: Trovi le password predefinite nel pannello Database di ServBay. Basta cliccare sull’icona impostazioni accanto al database desiderato per vedere username e password correnti, e modificarle all’occorrenza. Per sicurezza, consigliamo sempre di cambiarla.

Conclusioni

Dopo questa guida, dovresti essere in grado di installare e configurare un ambiente di sviluppo Koa.js su macOS usando ServBay, creare una semplice applicazione Koa.js e configurarla tramite funzione Website per abilitare reverse proxy, dominio personalizzato e HTTPS. Inoltre, hai imparato a collegare il tuo progetto ai principali database locali forniti da ServBay.

ServBay fornisce agli sviluppatori Node.js un ambiente integrato e facile da gestire, consentendo di concentrarsi sulla scrittura del codice invece che sulle configurazioni tecniche. Sfrutta le sue capacità e scoprirai come il tuo lavoro può diventare più veloce ed efficace!