Criando e Executando Projetos Koa.js com o ServBay

O ServBay é um ambiente de desenvolvimento web local projetado especialmente para macOS, integrando vários pacotes populares entre desenvolvedores, como o runtime do Node.js e diferentes bancos de dados. Este guia mostrará como você pode utilizar o ambiente prático do ServBay para criar, executar e gerenciar rapidamente seu projeto Koa.js.

O que é Koa.js?

Koa.js é uma estrutura web de próxima geração baseada em Node.js, desenvolvida pela mesma equipe do Express.js. Conhecida por sua simplicidade, expressividade e conjunto robusto de funcionalidades, é uma ótima escolha para construir aplicações web e APIs. Koa.js aproveita ao máximo os recursos modernos do JavaScript, principalmente a sintaxe async/await, simplificando consideravelmente as operações assíncronas e a criação de middlewares, tornando o código mais claro e de fácil manutenção.

Principais características do Koa.js

• Baseado em async/await: O design central gira em torno do async/await, tornando o controle de fluxo assíncrono muito mais intuitivo.
• Core enxuto: A biblioteca principal do Koa é muito leve, contendo apenas funcionalidades básicas e sendo expandida através de middlewares modulares.
• Middlewares poderosos: Utiliza uma mecânica em cascata de middlewares, possibilitando um fluxo de tratamento de requisições claro e flexível.
• Foco na web: Focado no desenvolvimento de aplicações web e APIs, sem oferecer funcionalidades extras desnecessárias.

Com o Koa.js, desenvolvedores podem criar serviços web de alta performance e fácil manutenção de forma mais eficiente.

Configurando o Ambiente de Desenvolvimento Koa.js no ServBay

O ServBay oferece um ambiente pronto para uso para desenvolvedores Node.js, com runtime integrado e serviços de banco de dados prontos. Com a funcionalidade de Website do ServBay, você pode acessar facilmente seu projeto Koa.js localmente usando domínios personalizados e certificados SSL.

Pré-requisitos

Antes de começar, certifique-se de ter:

1. Instalado o ServBay: Baixe e instale a versão mais recente em ServBay - Site oficial.
2. Instalado o pacote Node.js: Abra o aplicativo ServBay, navegue até o menu Pacotes (Packages), e instale a versão do Node.js desejada se ainda não estiver disponível.
3. Familiarizado com operações básicas do ServBay: Entenda como iniciar/parar serviços e gerenciar websites no ServBay.

Criando um Projeto Koa.js

O diretório padrão recomendado pelo ServBay para projetos é /Applications/ServBay/www.

1. Inicialize o diretório do projeto

   Abra o Terminal, navegue até o diretório raiz dos websites do ServBay, crie uma nova pasta para o projeto (por exemplo, servbay-koa-app), acesse a 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. Instale o Koa.js

   No diretório do projeto servbay-koa-app, instale o Koa.js e suas definições de tipo (caso utilize TypeScript):

   npm install koa
   # Caso utilize TypeScript, instale também as definições de tipo
   # npm install @types/koa --save-dev

3. Crie o arquivo de entrada da aplicação

   No diretório do projeto, crie um arquivo chamado app.js e adicione o seguinte código de um app Koa.js simples:

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

   Este código cria um app Koa básico com dois middlewares: um para registrar o tempo e o caminho das requisições e outro respondendo à raiz / com "Hello from ServBay Koa.js App!". O app escuta na porta definida pela variável de ambiente PORT ou, por padrão, na 3000.

Entrando no Modo de Desenvolvimento

Durante o desenvolvimento, normalmente você executa o app Koa.js em um processo Node.js local e acessa-o via a funcionalidade de Website do ServBay.

1. Execute o servidor de desenvolvimento do Koa.js

   No Terminal, entre no diretório do projeto servbay-koa-app e use o comando node para rodar o arquivo app.js. Para evitar conflitos de porta ou para facilitar configuração no ServBay, utilize uma porta customizada, como 8585:

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

   O terminal deve exibir algo como Koa.js server running on http://localhost:8585, confirmando que o servidor está ativo na porta 8585. Mantenha esta janela aberta para que o servidor continue rodando.

2. Configure o proxy reverso Website no ServBay

   Para acessar o app Koa.js rodando em localhost:8585 via domínio personalizado, configure um Website do tipo proxy reverso no ServBay:

   • Abra o aplicativo ServBay.
   • Vá até a seção Website.
   • Clique no botão + no canto inferior esquerdo para adicionar um novo site.
   • Preencha os campos:
     • Nome (Name): ServBay Koa.js Dev Site
     • Domínio (Domain): servbay-koa-dev.servbay.demo (sugestão: sempre que possível use o final .servbay.demo, pois o ServBay criará o certificado SSL automaticamente)
     • Tipo (Type): selecione Proxy Reverso (Reverse Proxy)
     • Endereço IP (IP Address): 127.0.0.1 (apontando para o processo Node.js local)
     • Porta (Port): 8585 (porta do Koa.js definida anteriormente)
     • Diretório raiz (Document Root): para proxy reverso, pode ficar em branco ou indicar o caminho /Applications/ServBay/www/servbay-koa-app
   • Clique em salvar.
   • Caso solicitado, clique em Aplicar para que as mudanças tenham efeito.

   Após a configuração, o ServBay atualizará automaticamente o arquivo hosts do seu sistema para apontar servbay-koa-dev.servbay.demo para 127.0.0.1. O proxy reverso do Caddy ou Nginx embutido irá rotear as requisições para a porta 8585. Com o uso de .servbay.demo, o ServBay User CA irá assinar e confiar automaticamente no certificado SSL, permitindo acesso HTTPS local.

   Para instruções mais detalhadas, confira a seção sobre adicionar website Node.js de desenvolvimento na documentação do ServBay (lembre-se de selecionar o idioma inglês).

3. Acesse o site Koa.js de desenvolvimento

   Abra seu navegador e acesse https://servbay-koa-dev.servbay.demo.

   Se todas as configurações estiverem corretas, você verá a mensagem "Hello from ServBay Koa.js App!" na tela. Isso indica que você está acessando seu servidor Koa.js de desenvolvimento local através do website configurado no ServBay. Modificações feitas no arquivo app.js e reinicialização do processo Node.js permitirão visualizar alterações após atualizar o navegador.

Simulando o Deploy de Produção

Na simulação de um ambiente de produção, pode ser necessário usar outra porta, variáveis de ambiente diferentes ou outra forma de inicializar o app. A configuração do proxy reverso no ServBay continua válida nesse cenário.

1. Execute o servidor Koa.js em modo simulação de produção

   Em outra janela do Terminal, pare o servidor de desenvolvimento anterior (caso ainda esteja rodando) e inicie o app com, por exemplo, porta 8586 e variável NODE_ENV como produção:

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

   Assim, inicia-se uma instância do Koa.js na porta 8586, simulando o ambiente de produção.

2. Configure o proxy reverso Website (simulação de produção)

   Da mesma forma, crie um novo website no ServBay para o ambiente de produção simulado:

   • Abra o ServBay e vá para a seção Website.
   • Clique no botão + para adicionar um novo site.
   • Preencha:
     • Nome (Name): ServBay Koa.js Prod Site
     • Domínio (Domain): servbay-koa-prod.servbay.demo (ou, caso você tenha um domínio próprio, utilize e configure SSL pelo Let's Encrypt/ACME)
     • Tipo (Type): Proxy Reverso (Reverse Proxy)
     • IP Address: 127.0.0.1
     • Porta (Port): 8586 (apontando para porta do app em “produção”)
     • Diretório raiz: opcional, pode deixar em branco ou indicar o caminho do projeto.
   • Clique em Salvar e Aplicar para efetivar as alterações.

   Utilizando domínio .servbay.demo, manterá o uso do certificado ServBay User CA. Para domínios públicos, use a integração com ACME/Let's Encrypt do ServBay para SSL gratuito. Veja detalhes na documentação de uso de SSL.

3. Acesse o site de produção (simulação)

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

   A página exibida deverá ser a mesma do ambiente de desenvolvimento, mas a requisição será roteada ao processo Node.js na porta 8586 pelo proxy reverso do ServBay.

Conectando a Bancos de Dados

O ServBay inclui integrações com bancos de dados populares como MongoDB, Redis, MariaDB (compatível com MySQL) e PostgreSQL. Em seus projetos Koa.js, a conexão é simples, pois eles rodam localmente e, por padrão, podem ser acessados via localhost.

Veja exemplos de conexão usando drivers Node.js (lembre-se de instalar e garantir que os bancos estão ativos via o menu Pacotes (Packages) do ServBay):

1. Conectando ao MongoDB

   Primeiro, instale o driver Node.js do MongoDB (mongoose ou mongodb):

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

   Em app.js ou outro módulo, adicione:

   // Usando Mongoose para conectar ao MongoDB
   const mongoose = require('mongoose');
   
   // O MongoDB do ServBay normalmente não pede autenticação e o nome do banco pode ser 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: na prática, a conexão geralmente é feita no início da aplicação
   // e só após a conexão bem-sucedida a aplicação começa a escutar requisições.

   O MongoDB do ServBay, por padrão, escuta na porta 27017 e não requer usuário/senha. Basta especificar o nome do banco; ele será criado automaticamente se não existir.

2. Conectando ao Redis

   Instale o cliente Node.js para Redis:

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

   Conectando-se ao servidor Redis:

   // Usando o cliente redis para conectar ao Redis
   const redis = require('redis');
   
   // Cria cliente Redis, padrão em localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // Porta padrão do Redis ServBay
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // Conectar-se ao Redis
   client.connect();
   
   // Nota: ideal aguardar a conexão antes de executar comandos Redis,
   // por exemplo, usando async/await junto ao client.connect()

   O Redis do ServBay escuta a porta 6379 e, por padrão, não exige senha.

3. Conectando ao MariaDB (ou MySQL)

   MariaDB é um fork do MySQL, e ambas compartilham a maior parte da API. O ServBay oferece MariaDB como padrão, mas pode ser usado do mesmo modo que o MySQL.

   Instale o driver Node.js para MariaDB:

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

   Conectando com o driver mariadb:

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

   Conectando com o driver mysql2 (recomendado):

   // Usando mysql2 para conectar ao MariaDB/MySQL
   const mysql = require('mysql2/promise'); // Versão baseada em promises
   
   // Usuário root padrão do ServBay tem senha 'password'
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // Certifique-se de criar o banco
     waitForConnections: true,
     connectionLimit: 10,
     queueLimit: 0
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB/MySQL using mysql2");
       conn.release(); // Liberar conexão de volta ao pool
     })
     .catch(err => {
       console.error("MariaDB/MySQL connection error:", err);
     });
   
   // Nota: a senha padrão do usuário root pode ser vista e modificada
   // no menu do banco MariaDB no ServBay. Recomendado usar variáveis de ambiente para produção.

   O MariaDB do ServBay escuta a porta 3306 por padrão. Usuário root e senha padrão são exibidos no painel de banco de dados do ServBay. Você pode precisar criar o banco servbay_koa_app no ServBay ou em ferramentas gráficas como TablePlus ou DBeaver.

4. Conectando ao PostgreSQL

   Instale o driver Node.js para PostgreSQL:

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

   Conectando ao servidor PostgreSQL:

   // Usando o cliente pg para conectar ao PostgreSQL
   const { Pool } = require('pg');
   
   // Usuário padrão do ServBay é 'user' e senha 'password'
   const pool = new Pool({
     user: 'user', // usuário padrão do ServBay
     host: 'localhost',
     database: 'servbay_koa_app', // Certifique-se de criar o banco
     password: 'password', // senha padrão do ServBay
     port: 5432, // porta padrão do PostgreSQL do ServBay
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release(); // Liberar conexão de volta ao pool
   });
   
   // Nota: as credenciais padrão ("user"/"password") podem ser vistas e alteradas no painel do ServBay.
   // Não é recomendado hardcodear senhas em produção.

   O PostgreSQL do ServBay escuta, por padrão, na porta 5432. Usuário e senha padrão estão disponíveis no menu de bancos de dados do ServBay. Crie manualmente o banco servbay_koa_app se necessário.

Gerenciando Bancos de Dados pelo ServBay

Além de conectar via código, você pode usar GUIs para gerenciar os bancos do ServBay, que normalmente estão em 127.0.0.1 ou localhost, e acessíveis com o usuário, senha e porta padrão exibidos no app ServBay.

• Ver/modificar senha padrão: No ServBay, acesse o pacote do banco desejado e clique no ícone de configurações para ver e alterar usuário root (MariaDB) ou user (PostgreSQL) e suas senhas.
• Criar bancos/usuários: Com ferramentas como TablePlus, DBeaver, pgAdmin ou MongoDB Compass, conecte-se ao banco local do ServBay e crie bancos, usuários e tabelas conforme necessário por interface gráfica ou comandos SQL.

Dicas e Observações

• Conflito de portas: Certifique-se de que as portas escolhidas (como 8585, 8586) não estejam em uso por outros processos do sistema.
• Status do ServBay: O aplicativo ServBay, bem como os serviços do Node.js e dos bancos, precisam estar rodando para funcionar corretamente.
• Arquivo hosts: O ServBay gerencia seu /etc/hosts automaticamente, mas em caso de problemas de resolução de domínio, confira se as entradas estão presentes.
• Firewall: Verifique se o firewall do macOS (ou de terceiros) não está bloqueando conexões do ServBay ou dos processos Node.js.
• Logs: Em caso de problemas, confira os logs do ServBay (na aba de logs) e o output do Node.js no terminal para te ajudar no diagnóstico.

Perguntas Frequentes (FAQ)

• Por que devo usar o proxy reverso do ServBay para acessar meus projetos Koa.js?

  Resposta: Usar proxy reverso (através da função Website do ServBay) oferece várias vantagens:

  1. Simulação realista de produção: Usar domínios personalizados (como .servbay.demo ou seu próprio domínio) em vez de localhost:PORT se aproxima mais da experiência de acesso a um site real.
  2. Suporte SSL: O ServBay pode provisionar automaticamente certificados SSL (via User CA ou Let's Encrypt) mesmo localmente, permitindo testar HTTPS já na fase de desenvolvimento.
  3. Gerenciamento centralizado: O ServBay consolida todos os seus websites de desenvolvimento para fácil administração.
  4. Portas padronizadas para o navegador: Acessos externos e pelo browser serão sempre pelas portas 80/443, enquanto o proxy interno direcionará para as portas usadas pelo Node.js.

• Posso acessar diretamente via localhost:PORT sem proxy reverso?

  Resposta: Sim. Você pode acessar seu app Koa.js diretamente pelo endereço http://localhost:PORT. No entanto, assim não terá vantagens como domínios personalizados, SSL automático, gerenciamento centralizado de logs etc. No desenvolvimento moderno, simular o ambiente de produção é melhor utilizando o proxy reverso do ServBay.

• Qual a senha padrão dos bancos do ServBay e como alterá-la?

  Resposta: As senhas padrão estão visíveis no painel de bancos do app ServBay. Clique na engrenagem ao lado do banco desejado (MariaDB ou PostgreSQL) para ver ou alterar usuário e senha. Por segurança, recomenda-se trocar a senha padrão.

Conclusão

Com este tutorial, você aprendeu a montar rapidamente um ambiente de desenvolvimento Koa.js no macOS usando o ServBay: criamos um app básico, configuramos um website com proxy reverso para acesso via domínio personalizado com HTTPS, e vimos como conectar rapidamente a bancos de dados locais integrados.

O ServBay oferece ao desenvolvedor Node.js um ambiente local integrado e fácil de administrar, permitindo que você foque no código sem se perder na configuração de infraestrutura. Aproveite todos os recursos do ServBay para aumentar sua produtividade!