Skip to content

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

  1. Compile o cliente. Na pasta [rdvmedecins_ionic]:
npx ng build

O console exibe (a lista de arquivos foi truncada):

Initial chunk files | Names          |  Raw size | Estimated transfer size
chunk-D1Fy7lNv.js   | -              | 949.39 kB |               177.56 kB
styles-EA54KZY4.css | styles         |  41.82 kB |                 5.04 kB
chunk-Dy0_VL94.js   | -              |  37.92 kB |                13.16 kB
main-FA64HVK2.js    | main           |  35.96 kB |                11.14 kB
...
                    | Initial total  |   1.10 MB |               222.11 kB

Lazy chunk files    | Names          |  Raw size | Estimated transfer size
chunk-CQUKBzMH.js   | my-account     |   6.02 kB |                 1.90 kB
chunk-SZ_YMAdj.js   | login          |   5.43 kB |                 2.04 kB
chunk-keRC2_fg.js   | patient-area   |   4.31 kB |                 1.68 kB
chunk-BcO9UgKs.js   | person-form    |   4.30 kB |                 1.66 kB
chunk-Bs2orSJL.js   | persons        |   3.92 kB |                 1.63 kB
chunk-D3F55gZB.js   | register       |   3.53 kB |                 1.29 kB
chunk-zsTSOYLr.js   | error-page     |   1.15 kB |               647 bytes
...and 11 more lazy chunks files. Use "--verbose" to show all the files.

Application bundle generation complete. [12.778 seconds]

Output location: .../rdvmedecins_ionic/dist/rdvmedecins_ionic

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/...]).

  1. 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:

  2. 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]...);

  3. ou especifique diretamente a pasta gerada por [ng build]:
CLIENT_DIR=../rdvmedecins_ionic/dist/rdvmedecins_ionic/browser

(um caminho relativo à raiz do servidor ou um caminho absoluto). Em seguida, reinicie o servidor. Ele exibe:

[Nest] LOG [RdvMedecins] web client served from .../rdvmedecins_ionic/dist/rdvmedecins_ionic/browser
[Nest] LOG [RdvMedecins] JSON server started: http://localhost:8080/api

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='...']):

cd rdvmedecins-nestjs-json
PORT=8090 CLIENT_DIR=../rdvmedecins_ionic/dist/rdvmedecins_ionic/browser npm run start:prod

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.

  1. Crie o projeto [Android] uma única vez:
npx cap add android

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):

distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-all.zip
  1. Compile a aplicação web e depois copie-a para o projeto [Android]:
npx ng build
npx cap sync 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.

  1. Execute-a:
npx cap run android

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:

1
2
3
npx ng build --define "SERVER='http://192.168.1.20:8080'"
npx cap sync android
npx cap run android

O firewall do computador deve permitir conexões de entrada na porta 8080.

  1. 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).

  2. 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/]:

cd android
./gradlew assembleDebug

(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").

  1. 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):

  2. 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);

  3. ou pela linha de comando: crie a chave com a ferramenta [keytool] do JDK e depois compile a versão assinada:
keytool -genkey -v -keystore rdvmedecins.jks -keyalg RSA -keysize 2048 -validity 10000 -alias rdvmedecins
npx cap build android --keystorepath ../rdvmedecins.jks --keystorepass password --keystorealias rdvmedecins --keystorealiaspass password --androidreleasetype APK --signing-type apksigner
  • 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.

  1. Para uma versão de lançamento real:

  2. 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);

  3. 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].