12. Implantação
Durante o desenvolvimento, a aplicação é executada sob o controle de [ng serve]: compilada em tempo real, com as verificações e mensagens do [Angular] para o desenvolvedor, e recarregada a cada alteração. Para implantá-la, nós a compilamos: [ng build] produz uma aplicação web otimizada, sem nenhuma ferramenta de desenvolvimento. É essa que implantamos em um servidor web, e é TAMBÉM essa que o [Capacitor] empacota no aplicativo [Android]: há um único build, para as duas plataformas.
12.1. A versão web
- Compile o cliente. Na pasta [rdvmedecins_ionic]:
O console exibe (a lista de arquivos foi truncada):
Sem nenhuma opção, [ng build] usa a configuração [production] de [angular.json]: o código é otimizado (os nomes são encurtados, os espaços e comentários são removidos e o código não utilizado é eliminado), e as verificações destinadas ao desenvolvimento são removidas. O compilador compilou a aplicação ([TypeScript], templates, [Angular], [Ionic]) em [JavaScript], na pasta [dist/rdvmedecins_ionic/browser/]:
- [index.html]: A página da aplicação, que carrega os arquivos [JavaScript] e a folha de estilos. Ao contrário do cliente [Flutter], a aplicação gera conteúdo HTML padrão, que o próprio navegador exibe;
- os "chunks" iniciais, carregados na inicialização: [Angular], [Ionic], o roteador, os serviços e o layout. 1,1 MB, ou aproximadamente 220 KB depois de comprimidos pelo servidor: é a estimativa da última coluna;
- segmentos "lazy": um por tela ([login], [my-account]...), graças a [loadComponent] nas rotas (veja [app.routes.ts]), e alguns outros para os componentes do [Ionic] carregados sob demanda. Cada um é baixado apenas na primeira visita à tela;
- o nome de cada arquivo contém um hash de seu conteúdo ([main-FA64HVK2.js]): o servidor pode instruir o navegador a mantê-los em cache indefinidamente, já que uma nova versão terá novos nomes;
- [i18n/] e [favicon.ico]: o conteúdo da pasta [public/], copiado sem alterações;
- [angular.json] define "limites" para a configuração [production]: um aviso se os chunks iniciais excederem 2 MB e um erro se excederem 5 MB. A aplicação está longe de atingir esses limites.
A opção [--define "SERVER='...'"] não é necessária aqui: servida pelo servidor JSON, a aplicação usa o caminho relativo de [config.ts] ([/api/...]).
-
Implante-a no servidor. O servidor JSON pode servir um cliente web compilado (o arquivo [src/web/client-spa.ts] do servidor): seus arquivos são procurados na pasta [client/], na raiz do servidor, ou na pasta especificada pela variável de ambiente [CLIENT_DIR] (arquivo do servidor [src/config/paths.ts]; ela pode ser escrita no arquivo [.env]). Duas opções:
-
copie o CONTEÚDO da pasta [dist/rdvmedecins_ionic/browser/] para uma pasta [client/] na raiz do servidor JSON ([rdvmedecins-nestjs-json/client/index.html], [rdvmedecins-nestjs-json/client/main-FA64HVK2.js]...);
- ou especifique diretamente a pasta gerada por [ng build]:
(um caminho relativo à raiz do servidor ou um caminho absoluto). Em seguida, reinicie o servidor. Ele exibe:
A aplicação completa agora está disponível em http://localhost:8080. O servidor serve os arquivos do cliente e retorna [index.html] para qualquer outro endereço fora de /api: recarregar a página /schedule?doctorId=1&day=2026-10-13 funciona (é o navegador do cliente que exibe a página para esse endereço). A página e a API vêm da mesma origem: sem CORS, e o cookie de token é transmitido.
Para testar isso sem parar o servidor de desenvolvimento, você pode iniciar uma instância do servidor JSON em outra porta, especificando as duas variáveis na linha de comando (aqui no [Linux] ou no [macOS]; no [Windows], com o [PowerShell], você primeiro as define como [$env:PORT=8090] e [$env:CLIENT_DIR='...']):
A aplicação fica então acessível em http://localhost:8090; as duas instâncias compartilham o mesmo banco de dados. Foi assim que a versão web deste cliente foi testada: login, calendário, recarga da página em um endereço como /schedule?... e o título traduzido da aba.
O cliente também pode ser implantado em qualquer servidor web ([nginx], [Apache]...), desde que ele encaminhe as requisições /api ao servidor JSON (um "proxy reverso") e redirecione para [index.html] nas URLs desconhecidas: é o que o [ng serve] faz durante o desenvolvimento.
12.2. A versão Android
Compilar o aplicativo [Android] requer o [Android Studio] e o SDK do [Android] (veja o capítulo "Configuração do ambiente de desenvolvimento"). [Capacitor] 8 requer o JDK 21 ou posterior: a versão incluída no [Android Studio] é adequada.
- Crie o projeto [Android] uma única vez:
O comando cria a pasta [android/]: um projeto [Android Studio] completo (um projeto [Gradle]), que contém uma activity [Android] que exibe um [WebView], e os plugins do [Capacitor] usados pela aplicação ([@capacitor/app], [@capacitor/preferences]). Essa pasta faz parte do projeto: mantenha-a (e salve-a com o código-fonte no [git]), pois é nela que você define o nome, o ícone e a assinatura do aplicativo.
Se o JDK for um [Java] 25 (o usado nas versões recentes do [Android Studio]), a versão do [Gradle] selecionada pelo [Capacitor] (8.14) não consegue funcionar com ele ([Unsupported class file major version 69]): mudamos para o [Gradle] 9.1 no arquivo [android/gradle/wrapper/gradle-wrapper.properties] (veja o exemplo 01):
- Compile a aplicação web e depois copie-a para o projeto [Android]:
- linha 1: a aplicação web, em [dist/rdvmedecins_ionic/browser/];
- Linha 2: [cap sync] copia essa pasta ([webDir] de [capacitor.config.ts]) para [android/app/src/main/assets/public/], junto com a configuração do [Capacitor] ([capacitor.config.json]), e atualiza os plugins. Com [server.cleartext] definido como [true], ele também adiciona o atributo [android:usesCleartextTraffic="true"] ao manifesto do plugin, que é mesclado ao manifesto da aplicação durante o build: as requisições [http://] (não criptografadas) ao servidor de desenvolvimento são permitidas.
Você deve executar novamente esses dois comandos após cada alteração no código da aplicação.
- Execute-a:
O comando lista os dispositivos disponíveis (emuladores criados no [Android Studio], telefones conectados por USB com a "depuração USB" ativada), compila a aplicação, instala-a no dispositivo selecionado e a inicia. Você também pode abrir o projeto no [Android Studio] ([npx cap open android]) e usar seu botão "Run".
No emulador, o aplicativo se conecta ao servidor no endereço [http://10.0.2.2:8080] (veja [config.ts]). Em um telefone real conectado à mesma rede Wi-Fi do computador, você deve fornecer a ele o endereço do computador nessa rede ([ipconfig] no [Windows]) usando a seguinte sintaxe:
O firewall do computador deve permitir conexões de entrada na porta 8080.
-
Teste-a. A aplicação é uma página web exibida pelo [WebView]: as ferramentas de desenvolvimento do [Chrome], no computador, podem inspecioná-la. Abra o endereço [chrome://inspect]: o aplicativo do emulador ou do telefone aparece ali; "Inspect" abre o console, o inspetor de elementos e a aba "Network" (como as requisições à API passam pelo [CapacitorHttp] — ou seja, pelo código nativo —, elas são menos visíveis ali do que na web: o console do [Logcat], dentro do [Android Studio], as exibe).
-
Um arquivo de instalação de depuração (APK). No [Android Studio]: "Build > Generate App Bundles" ou "APKs > Generate APKs". Ou, pela linha de comando, na pasta [android/]:
(no [Windows]: [gradlew assembleDebug]). O arquivo é gerado em [android/app/build/outputs/apk/debug/app-debug.apk]. Ele é assinado com a chave de depuração do [Android Studio]: isso é suficiente para testes. Instale-o em um telefone conectado por [adb install app-debug.apk], ou copiando o arquivo para o telefone e abrindo-o (o [Android] solicitará então que você permita a instalação de aplicativos "de fontes desconhecidas").
-
Uma versão de produção assinada. Um aplicativo publicado deve ser assinado com uma chave específica do desenvolvedor, que deve ser mantida em segurança (todas as atualizações devem ser assinadas com a mesma chave):
-
no [Android Studio]: o menu "Build > Generate Signed App Bundle or APK...", que também permite criar a chave (um arquivo "keystore", protegido por uma senha);
- ou pela linha de comando: crie a chave com a ferramenta [keytool] do JDK e depois compile a versão assinada:
- linha 1: cria a chave no arquivo [rdvmedecins.jks] (o comando solicita o nome do desenvolvedor, a organização etc.);
- linha 2: [cap build] inicia o build do [Gradle] da versão "release" ([assembleRelease]) e assina o arquivo resultante com essa chave (o caminho da chave é relativo à pasta [android/]). [--signing-type apksigner]: a assinatura é criada pela ferramenta [apksigner] do SDK, cuja pasta, [build-tools/<version>], deve estar no PATH; sem essa opção, o [Capacitor] usa o [jarsigner], cuja assinatura não é mais aceita pelas versões recentes do [Android] para um APK. [--androidreleasetype AAB] produziria um "Android App Bundle", o formato esperado pela [Google Play Store].
Você também pode descrever a assinatura no arquivo [android/app/build.gradle] (um bloco [signingConfigs]; veja a documentação do [Android] intitulada "Sign your app") e executar diretamente [./gradlew assembleRelease] (um APK, localizado em [android/app/build/outputs/apk/release/]) ou [./gradlew bundleRelease] (um App Bundle). A senha da chave não deve ser escrita em um arquivo armazenado com o código-fonte.
-
Para uma versão de lançamento real:
-
o nome da aplicação é definido em [capacitor.config.ts] ([appName]) e em [android/app/src/main/res/values/strings.xml]; seu ícone é definido nos arquivos [android/app/src/main/res/mipmap-*/] (a ferramenta [@capacitor/assets] gera todos eles a partir de uma única imagem);
- o servidor deve usar HTTPS (senhas trafegam): removemos [server.cleartext] de [capacitor.config.ts] e compilamos a aplicação com o endereço público do servidor ([--define "SERVER='https://rdvmedecins.example.com'"]).
12.3. O servidor de produção
Em produção real, não se esqueça do arquivo [.env] no servidor:
- um [JWT_SECRET]longo e aleatório;
- um [CAPTCHA_TEST]vazio;
- [COOKIE_SECURE=true] se o site for servido por HTTPS (e deve ser): o cookie é então transmitido apenas em conexões criptografadas;
- [TRUST_PROXY=true] se o servidor estiver atrás de um proxy ([nginx]...), para que o limite de tentativas veja o endereço IP real dos clientes.
O servidor não tem regras de CORS a declarar: na web, o cliente é servido pelo próprio servidor (mesma origem); no [Android], as requisições se originam do código nativo ([CapacitorHttp]), ao qual o CORS não se aplica.
Em seguida, iniciamos o servidor compilado: [npm run build], seguido de [npm run start:prod].