Criando e executando projetos Koa.js com ServBay

O ServBay é um ambiente de desenvolvimento web local compatível com macOS e Windows, que integra diversos pacotes populares entre desenvolvedores, incluindo o runtime do Node.js e vários bancos de dados. Este guia mostrará como aproveitar o ambiente fácil e integrado do ServBay para criar, executar e gerenciar rapidamente seus projetos Koa.js.

O que é Koa.js?

O Koa.js é um framework web de próxima geração baseado em Node.js, desenvolvido pela equipe do Express.js. Ele é famoso por sua simplicidade, expressividade e poderoso conjunto de recursos, sendo ideal para criar aplicações web e APIs. O Koa.js faz uso completo de funcionalidades modernas do JavaScript, especialmente a sintaxe async/await, o que simplifica de forma significativa a escrita de operações assíncronas e middlewares, tornando o código mais claro e fácil de manter.

Principais recursos do Koa.js

• Baseado em async/await: O design central gira em torno de async/await, tornando o controle de fluxos assíncronos mais intuitivo.
• Núcleo leve: A biblioteca principal do Koa é pequena e inclui apenas funcionalidades básicas; recursos extras são adicionados via middlewares modulares.
• Middlewares poderosos: Utiliza o mecanismo de middlewares em cascata, proporcionando um processamento de requisições flexível e organizado.
• Foco em Web: Orientado para desenvolvimento de aplicações web e APIs, sem funcionalidades extras desnecessárias.

Com o Koa.js, desenvolvedores têm grande eficiência para construir serviços web de alta performance e fácil manutenção.

Preparando o ambiente Koa.js com ServBay

O ServBay fornece um ambiente pronto para uso para desenvolvedores Node.js, com integração ao runtime Node.js e serviços de bancos de dados comuns. Com o recurso de Website do ServBay, é fácil acessar seu projeto Koa.js local através de domínios personalizados e certificados SSL.

Pré-requisitos

Antes de começar, certifique-se de ter realizado as seguintes etapas:

1. Instalar o ServBay: Acesse o site oficial do ServBay para baixar e instalar a versão mais recente.
2. Instalar o pacote Node.js: Abra o ServBay, navegue até o menu de Packages e confira se já instalou a versão necessária do Node.js. Se não estiver instalada, selecione e clique em instalar.
3. Familiarizar-se com ServBay: Saiba como iniciar/parar serviços e gerenciar sites (Website) dentro do ServBay.

Criando o projeto Koa.js

Vamos usar o diretório raiz recomendado pelo ServBay: /Applications/ServBay/www para armazenar os arquivos do projeto.

1. Inicializando o diretório do projeto

   Abra o aplicativo Terminal, navegue até o diretório raiz dos sites do ServBay e crie uma nova pasta de projeto (por exemplo, servbay-koa-app). Em seguida, entre na pasta e inicialize um novo projeto Node.js:

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

   O comando npm init -y gera rapidamente um arquivo package.json padrão.

2. Instalando o Koa.js

   No diretório raiz do projeto servbay-koa-app, use o npm para instalar o Koa.js e, se estiver usando TypeScript, seus tipos:

   npm install koa
   # Se for usar TypeScript, instale as definições de tipo
   # npm install @types/koa --save-dev

3. Criando o arquivo principal da aplicação

   No diretório do projeto servbay-koa-app, crie um arquivo chamado app.js e adicione um código exemplo de aplicação Koa.js:

   const Koa = require('koa');
   const app = new Koa();
   
   // Middleware: registra informações da requisição
   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: trata requisições ao caminho raiz
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // Define a porta, priorizando a variável de ambiente PORT
   const port = process.env.PORT || 3000;
   
   // Inicializa o servidor HTTP
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   Este código cria uma aplicação Koa básica com dois middlewares: um para registrar tempo e rota da requisição, e outro que responde à rota / retornando "Hello from ServBay Koa.js App!". O aplicativo escuta na porta definida pela variável de ambiente PORT ou, por padrão, 3000.

Iniciando o modo de desenvolvimento

Durante o desenvolvimento, normalmente rodamos um processo Node.js local para executar o Koa.js e acessamos o projeto usando o recurso Website do ServBay.

1. Executando o servidor de desenvolvimento Koa.js

   Abra o Terminal, vá até o diretório do projeto servbay-koa-app e utilize o comando node para rodar o arquivo app.js. Para evitar conflitos de porta e facilitar a configuração do ServBay, você pode definir uma porta específica, como 8585:

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

   No Terminal, você verá uma mensagem como Koa.js server running on http://localhost:8585, indicando que o servidor está rodando na porta 8585. Mantenha essa janela aberta para o servidor continuar rodando.

2. Configurando Proxy Reverso de Website no ServBay

   Para acessar o Koa.js rodando em localhost:8585 com um domínio personalizado, configure um Website no ServBay usando proxy reverso:

   • Abra o aplicativo ServBay.
   • Vá para o menu Website.
   • Clique no botão + no canto inferior esquerdo para adicionar um novo site.
   • Preencha as configurações:
     • Nome (Name): ServBay Koa.js Dev Site
     • Domínio (Domain): servbay-koa-dev.servbay.demo (recomenda-se terminar o domínio com .servbay.demo, pois ServBay gera certificados SSL automaticamente)
     • Tipo (Type): selecione Reverse Proxy
     • Endereço IP (IP Address): 127.0.0.1 (aponta para o processo Node.js local)
     • Porta (Port): 8585 (porta do Koa.js)
     • Root (Document Root): Não é relevante para proxy reverso; pode deixar em branco ou informar o caminho /Applications/ServBay/www/servbay-koa-app.
   • Clique em salvar.
   • Se solicitado, aplique as alterações.

   Após a configuração, o ServBay atualiza seu arquivo hosts local automaticamente, associando servbay-koa-dev.servbay.demo a 127.0.0.1, e direciona as requisições desse domínio para a porta 8585 via proxy reverso com Caddy ou Nginx embutido. Além disso, domínios .servbay.demo recebem certificados SSL confiáveis via ServBay User CA, permitindo acesso seguro por HTTPS.

   Para detalhes dos passos, acesse a seção Adicionando site Node.js de desenvolvimento na documentação oficial ServBay (selecionar versão em inglês).

3. Acessando o site de desenvolvimento Koa.js

   Abra o navegador e visite https://servbay-koa-dev.servbay.demo.

   Se tudo estiver configurado corretamente, a página exibirá "Hello from ServBay Koa.js App!", indicando que o servidor Koa.js local está acessível via Website do ServBay. Ao modificar o arquivo app.js e reiniciar o processo Node.js, basta atualizar o navegador para ver as alterações.

Simulando ambiente de produção

Para simular um ambiente de produção, você pode usar portas e variáveis diferentes, ou outra forma de inicialização. A configuração de proxy reverso no ServBay é igualmente eficiente neste cenário.

1. Executando o servidor de produção Koa.js (simulado)

   Em outra janela do Terminal, pare o servidor de desenvolvimento (se estiver rodando) e inicie o aplicativo em modo produção, especificando uma porta diferente, como 8586, e a variável NODE_ENV=production:

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

   Isso inicia uma instância Koa.js ouvindo na porta 8586, como simulação do ambiente de produção.

2. Configurando Proxy Reverso de Website para produção no ServBay

   Semelhante ao ambiente de desenvolvimento, configure um novo Website para produção simulada:

   • Abra o ServBay e acesse Website.
   • Clique no botão + para adicionar novo site.
   • Preencha:
     • Nome (Name): ServBay Koa.js Prod Site
     • Domínio (Domain): servbay-koa-prod.servbay.demo (ou seu próprio domínio, utilizando os recursos de SSL gratuitos Let's Encrypt do ServBay)
     • Tipo (Type): Reverse Proxy
     • Endereço IP (IP Address): 127.0.0.1
     • Porta (Port): 8586 (porta da aplicação em produção)
     • Root (Document Root): pode deixar em branco ou adicionar caminho do projeto.
   • Salve e aplique as alterações.

   Usando o domínio .servbay.demo, o ServBay User CA continua oferecendo certificado SSL. Se usar domínio público próprio, o ServBay suporta emissão e gestão gratuita de certificados SSL/TLS por ACME/Let's Encrypt. Veja detalhes em Protegendo sites com SSL.

3. Acessando o site de produção Koa.js (simulado)

   No navegador, acesse https://servbay-koa-prod.servbay.demo.

   O mesmo resultado do ambiente de desenvolvimento será exibido, mas agora através do proxy reverso do ServBay conectado à porta 8586 do Node.js.

Conexão com bancos de dados

O ServBay integra diversos bancos de dados amplamente usados: MongoDB, Redis, MariaDB (compatível com MySQL) e PostgreSQL. No seu projeto Koa.js, conectar a esses bancos é fácil, pois rodam localmente e, por padrão, podem ser acessados via localhost.

Veja abaixo exemplos de conexão usando drivers Node.js para alguns bancos de dados fornecidos pelo ServBay. Primeiro, confirme que o banco está instalado e ativo pelo menu Packages do ServBay.

1. Conectando ao MongoDB

   Primeiro, instale o driver Node.js do MongoDB (por exemplo, mongoose ou mongodb) no diretório do projeto:

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

   Depois, adicione o código de conexão ao seu app.js ou outro módulo:

   // Utilizando Mongoose para conectar ao MongoDB
   const mongoose = require('mongoose');
   
   // O MongoDB padrão do ServBay não requer autenticação; o nome do banco é personalizado
   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: Em aplicações reais, a conexão é feita na inicialização,
   // e o servidor só é iniciado após conexão bem-sucedida.

   O MongoDB instalado pelo ServBay normalmente escuta na porta 27017 e não exige usuário ou senha por padrão. O nome do banco pode ser escolhido livremente (se não existir, será criado automaticamente).

2. Conectando ao Redis

   Instale o cliente Redis para Node.js:

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

   Realize a conexão:

   // Utilizando cliente redis para conectar ao Redis
   const redis = require('redis');
   
   // Cria cliente Redis, conectando ao localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // Porta padrão no ServBay é 6379
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Inicia a conexão ao servidor Redis
   client.connect();
   
   // Nota: Em produção, aguarde a conexão antes de manipular Redis
   // usando async/await com client.connect()

   O Redis do ServBay usa a porta 6379 e normalmente não necessita senha na configuração padrão.

3. Conectando ao MariaDB (ou MySQL)

   O MariaDB é derivado do MySQL e tem APIs altamente compatíveis. O ServBay oferece o MariaDB, que pode ser usado como MySQL.

   Instale o driver MariaDB para Node.js:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # ou npm install mysql2 (melhor compatibilidade, recomendado)

   Usando o driver mariadb:

   // Utilizando cliente mariadb para conectar ao MariaDB
   const mariadb = require('mariadb');
   
   // Usuário root padrão do MariaDB: senha 'password' no ServBay
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Certifique-se de que o banco existe, ou ajuste conforme necessário
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB");
       conn.release(); // Libera conexão para o pool
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // Nota: Aquisição de conexão via pool é assíncrona

   Usando o driver mysql2 (recomendado):

   // Utilizando cliente mysql2 (versão promise) para conectar ao MariaDB/MySQL
   const mysql = require('mysql2/promise');
   
   // Usuário root padrão do MariaDB: senha 'password' no ServBay
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Certifique-se de que o banco existe
     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: A senha padrão do root pode ser vista/modificada na GUI ServBay.
   // Em projetos reais, nunca codifique a senha; use variáveis de ambiente.

   O MariaDB do ServBay escuta na porta 3306 por padrão. A senha padrão do usuário root pode ser obtida na interface de gerenciamento do ServBay e deve ser alterada para segurança. Você pode criar bancos de dados manualmente usando ServBay ou ferramentas como TablePlus, DBeaver etc.

4. Conectando ao PostgreSQL

   Instale o driver PostgreSQL para Node.js:

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

   Faça a conexão ao servidor PostgreSQL:

   // Utilizando cliente pg para conectar ao PostgreSQL
   const { Pool } = require('pg');
   
   // Usuário padrão ServBay: 'user', senha 'password'
   const pool = new Pool({
     user: 'user', // Usuário padrão no ServBay
     host: 'localhost',
     database: 'servbay_koa_app', // Certifique-se de que o banco existe
     password: 'password', // Senha padrão no ServBay
     port: 5432, // Porta padrão do PostgreSQL no ServBay
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release();
   });
   
   // Nota: O usuário/senha padrão pode ser visto/modificado na GUI ServBay.
   // Não codifique a senha em projetos reais.

   O PostgreSQL do ServBay escuta na porta 5432 e a senha padrão pode ser visualizada ou alterada no painel ServBay. É possível que você precise criar o banco de dados servbay_koa_app manualmente.

Gerenciando bancos de dados no ServBay

Além do acesso via código, ferramentas gráficas podem se conectar aos bancos do ServBay para gestão. Por padrão, os bancos de dados aceitam conexões de 127.0.0.1 ou localhost, utilizando porta e credenciais exibidas na GUI ServBay.

• Visualizar/alterar senha padrão: Na GUI ServBay, abra o painel do banco, clique no ícone de configurações, e consulte ou troque a senha dos usuários padrão (root para MariaDB, user para PostgreSQL).
• Criar bancos de dados/usuários: Use clientes SQL gráficos como TablePlus, DBeaver, pgAdmin, MongoDB Compass, conectando com as informações do ServBay, e execute comandos ou utilize ferramentas para criar bancos de dados, usuários e tabelas.

Observações importantes

• Conflito de portas: Certifique-se que as portas usadas pelo Koa.js (ex: 8585, 8586) não estejam ocupadas por outros aplicativos.
• Status do ServBay: O ServBay, o pacote Node.js e os bancos devem estar rodando.
• Arquivo hosts: O ServBay gerencia o arquivo hosts, mas caso haja problemas de resolução, confira se as entradas estão presentes em /etc/hosts.
• Firewall: Verifique se o firewall do macOS ou de terceiros não bloqueia ServBay ou Node.js.
• Visualização de logs: Consulte os logs do ServBay (no painel de logs) e do Node.js para diagnóstico em caso de problemas.

Perguntas frequentes (FAQ)

• Pergunta: Por que usar o proxy reverso do ServBay para acessar meu projeto Koa.js?

  Resposta: O proxy reverso via Website do ServBay oferece vários benefícios:

  1. Simulação realista: Domínio personalizado (.servbay.demo ou próprio) simula o acesso real ao site, diferente de localhost:PORT.
  2. Suporte SSL: SSL é configurado automaticamente (ServBay User CA ou Let's Encrypt), permitindo testar HTTPS em desenvolvimento.
  3. Gestão centralizada: Todos os sites de desenvolvimento podem ser gerenciados no ServBay de forma simples.
  4. Ocultação de portas: O navegador acessa as portas padrão 80/443, enquanto as requisições internas vão para portas elevadas do Node.js.

• Pergunta: Posso acessar diretamente por localhost:PORT sem proxy reverso?

  Resposta: Sim. O Koa.js pode ser acessado via http://localhost:PORT para desenvolvimento e testes. Contudo, com isso você perde os benefícios do ServBay (domínio personalizado, SSL automático, gestão centralizada etc.). Para desenvolvimento mais próximo do real, prefira o proxy reverso do ServBay.

• Pergunta: Qual a senha padrão dos bancos de dados do ServBay? Como altero?

  Resposta: As senhas padrão estão disponíveis no painel de Database do ServBay. Clique nas configurações do banco (MariaDB, PostgreSQL etc.) e veja os dados de acesso. Você pode alterá-los ali. Por segurança, é recomendado modificar a senha padrão.

Resumo

Após seguir este tutorial, você deve estar apto a criar e configurar um ambiente Koa.js no macOS usando o ServBay. Aprendemos a criar uma aplicação básica Koa.js, configurá-la por meio do recurso Website (proxy reverso), acessar com domínio personalizado e HTTPS, além de conectar e gerenciar bancos de dados populares integrados ao ServBay.

O ServBay oferece aos desenvolvedores Node.js um ambiente integrado e fácil de administrar, permitindo que você foque mais na codificação e menos na configuração. Aproveite ao máximo os recursos do ServBay para acelerar seu desenvolvimento!