Skip to content

Build e distribuição do app desktop (Tauri) ​

O cliente desktop Clino é um shell Tauri 2 que embrulha o apps/web e entrega instaladores nativos por sistema operacional. Tauri não faz cross-compile: cada SO precisa do seu próprio runner no CI.


1. Pré-requisitos por SO ​

Linux / WSL (Debian, Ubuntu, WSL2) ​

bash
# 1 — Rust (espaço do usuário, sem sudo)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# 2 — Dependências de sistema (exige sudo)
sudo apt update && sudo apt install -y \
  libwebkit2gtk-4.1-dev \
  build-essential \
  curl wget file \
  libxdo-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  pkg-config

No WSL2, certifique-se de que está rodando uma distribuição Ubuntu 22.04+ ou Debian 12+. libwebkit2gtk-4.1-dev exige GTK 4; versões mais antigas do Ubuntu podem não ter o pacote na versão correta — atualize os repositórios antes de instalar.

macOS ​

bash
# 1 — Xcode Command Line Tools (necessário para o linker e libs do sistema)
xcode-select --install

# 2 — Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# 3 — Para o target universal (Intel + Apple Silicon):
rustup target add aarch64-apple-darwin x86_64-apple-darwin

O pnpm tauri build local produz apenas para a arquitetura do runner atual (ex. aarch64). O CI usa --target universal-apple-darwin para gerar um binário fat com ambas arquiteturas.

Windows ​

powershell
# 1 — Instale o rustup via winget (PowerShell como administrador)
winget install -e --id Rustlang.Rustup

# OU baixe o instalador em https://rustup.rs e execute-o (interface gráfica)

# 2 — MSVC Build Tools (necessário para compilar C/C++ linkado ao Rust)
#     Opção A — via Visual Studio Installer (recomendado):
#       Instale o Visual Studio 2022 Community (gratuito) e selecione o workload
#       "Desenvolvimento para desktop com C++"
#     Opção B — apenas Build Tools (sem IDE):
#       Baixe em https://visualstudio.microsoft.com/visual-cpp-build-tools/
#       Selecione: MSVC v143 + Windows 11 SDK

# 3 — Abra um novo terminal (PowerShell ou cmd) para o PATH do Rust ser detectado
rustc --version   # deve exibir rustc 1.XX.X
cargo --version

No Windows, o Tauri usa o WebView2 do sistema (incluso no Windows 10 20H2+ e Windows 11). Em versões mais antigas, o instalador cuida do WebView2 automaticamente via bootstrapper.


2. Build local ​

Com os pré-requisitos acima instalados:

bash
# A partir de apps/web (ambos os comandos iniciam pnpm install se necessário):

# Modo desenvolvimento — janela nativa + hot-reload do Vite
pnpm tauri dev

# Produção — gera instaladores para o SO atual em src-tauri/target/release/bundle/
pnpm tauri build

pnpm tauri build produz instaladores apenas para o SO da máquina atual. Não há cross-compile: para gerar .dmg macOS numa máquina Linux, use o CI.

Localização dos artefatos após pnpm tauri build:

SOLocalização
Linuxsrc-tauri/target/release/bundle/appimage/ e deb/
macOSsrc-tauri/target/release/bundle/dmg/
Windowssrc-tauri/target/release/bundle/nsis/ e msi/

3. Workaround do crate time ​

O crate time 0.3.48 (publicado em 2026-06-12) desencadeia o erro E0119 (implementações From conflitantes) quando compilado dentro do tauri-utils 2.9.x. Referência: tauri#12642.

Solução: o Cargo.lock está commitado com o time fixado em 0.3.47. O CI re-aplica o pin como segurança caso o lock driftar:

bash
# Dentro de apps/web/src-tauri:
cargo update -p time --precise 0.3.47

Commite o Cargo.lock atualizado. Remova este workaround quando tauri-utils for corrigido.


4. Pipeline de release CI ​

O workflow .github/workflows/release.yml constrói cada SO em seu próprio runner e publica os artefatos em um GitHub Release draft.

push de tag v*   →  prepare (calcula versão)
                     ├─ build/windows-latest  →  .exe (NSIS) + .msi (WiX) + .sig
                     ├─ build/macos-latest    →  .dmg (universal: Intel + Apple Silicon) + .sig
                     └─ build/ubuntu-22.04    →  .AppImage + .deb + .sig
                          ↓ (todos os builds precisam passar)
                     ├─ smoke-test/windows  →  instalação silenciosa + verifica .exe
                     ├─ smoke-test/macos    →  monta DMG + verifica .app bundle
                     └─ smoke-test/linux    →  AppImage headless sob Xvfb por 8 s
                          ↓ (todos os smoke-tests precisam passar)
                     publish  →  GitHub Release draft com todos os artefatos
                             └─ latest.json gerado a partir dos .sig e anexado ao Release

Os artefatos .sig (gerados quando TAURI_SIGNING_PRIVATE_KEY está presente) são os que alimentam o latest.json. Sem eles, o manifesto terá signature: "" e o auto-updater ignorará a atualização.

Secrets GitHub necessários ​

Configure em: Repositório → Settings → Secrets and variables → Actions → New repository secret.

SecretSOObrigatórioPropósito
TAURI_SIGNING_PRIVATE_KEYTodosSimChave privada para assinar artefatos do auto-updater
TAURI_SIGNING_PRIVATE_KEY_PASSWORDTodosSim (pode ser "")Senha da chave acima
WINDOWS_CERTIFICATEWindowsNão (gera não-assinado)Certificado EV/OV em base64 (.pfx)
WINDOWS_CERTIFICATE_PASSWORDWindowsSe WINDOWS_CERTIFICATE presenteSenha do .pfx
APPLE_CERTIFICATEmacOSNão (gera não-assinado)Certificado Developer ID em base64 (.p12)
APPLE_CERTIFICATE_PASSWORDmacOSSe APPLE_CERTIFICATE presenteSenha do .p12
APPLE_SIGNING_IDENTITYmacOSSe APPLE_CERTIFICATE presenteNome da identidade no Keychain
APPLE_IDmacOSSe APPLE_CERTIFICATE presenteE-mail da conta Apple Developer
APPLE_PASSWORDmacOSSe APPLE_CERTIFICATE presenteApp-specific password para notarização
APPLE_TEAM_IDmacOSSe APPLE_CERTIFICATE presenteTeam ID de 10 caracteres

Builds sem os secrets de assinatura produzem instaladores funcionais, porém não assinados — comportamento desejado para forks e PRs de contribuidores externos.

Gerando o keypair do auto-updater ​

bash
# Instale a CLI do Tauri globalmente (uma vez):
cargo install tauri-cli

# Gere o par de chaves (salve em local seguro fora do repositório):
tauri signer generate -w ~/.tauri/clino.key

# A saída exibe:
#   Private key: (conteúdo → TAURI_SIGNING_PRIVATE_KEY)
#   Public key:  (conteúdo → tauri.conf.json → plugins.updater.pubkey)

Adicione a chave privada ao secret TAURI_SIGNING_PRIVATE_KEY e insira a chave pública em apps/web/src-tauri/tauri.conf.json:

jsonc
{
  "plugins": {
    "updater": {
      "pubkey": "<cole a chave pública aqui>"
    }
  }
}

Disparando o workflow manualmente ​

  1. Acesse a aba Actions no repositório GitHub.
  2. Selecione o workflow "Release (desktop installers)".
  3. Clique em "Run workflow" → escolha o tipo de bump: release (padrão), hotfix ou major.
  4. Acompanhe os jobs na aba Actions; ao final, um GitHub Release draft é criado com os artefatos.

Alternativamente, push de uma tag explícita:

bash
git tag v1.2.0
git push origin v1.2.0

Os artefatos de cada runner também ficam disponíveis na própria execução do workflow (aba Artifacts) por 14 dias, mesmo sem publicar o Release draft.


5. Regenerar ícones ​

Os ícones em apps/web/src-tauri/icons/ derivam do SVG de marca apps/web/public/brand/clino-mark.svg. Para regenerá-los:

bash
# Passo 1 — Rasterize o SVG para 1024×1024 PNG (necessário; tauri icon não aceita SVG)
# Opção A: sharp-cli
npx sharp -i apps/web/public/brand/clino-mark.svg \
           -o /tmp/clino-mark-1024.png \
           resize 1024 1024

# Opção B: Inkscape (se instalado)
inkscape apps/web/public/brand/clino-mark.svg \
  --export-filename=/tmp/clino-mark-1024.png \
  --export-width=1024 --export-height=1024

# Passo 2 — Gere todos os tamanhos com a CLI do Tauri
cd apps/web && pnpm tauri icon /tmp/clino-mark-1024.png

# Passo 3 — Remova os ícones iOS/Android (não usamos essas plataformas):
rm -rf apps/web/src-tauri/icons/AppIcon*.png \
       apps/web/src-tauri/icons/android/

Os ícones gerados (32x32.png, 128x128.png, 128x128@2x.png, icon.icns, icon.ico) são referenciados em tauri.conf.json → bundle.icon e devem ser commitados.


6. Deploy on-prem (instalação nas clínicas) ​

Cenário ​

O app desktop Clino roda na máquina do recepcionista/médico e aponta para um servidor NestJS local rodando na LAN da clínica (modo on-prem). O servidor local possui o banco Postgres e sincroniza com a nuvem quando há internet disponível.

Passos para o técnico ​

Requisitos de infraestrutura:

  • 1 máquina servidora na LAN (pode ser um mini-PC, NAS ou VM) rodando Ubuntu 22.04+ ou Windows Server.
  • Node 22 + PostgreSQL 15+ instalados no servidor.
  • O servidor e as estações clientes na mesma rede local (LAN/Wi-Fi).

1. No servidor da clínica — instalar e iniciar o backend:

bash
# Clone ou copie o pacote apps/api para o servidor
cd /opt/clino-api

# Configure as variáveis de ambiente:
cp .env.example .env
# Edite .env:
#   DATABASE_URL=postgresql://user:pass@localhost:5432/clino
#   APP_MODE=local
#   PLATFORM_URL=https://api.clino.com.br  # para sincronização com a nuvem
#   JWT_SECRET=<gere com: openssl rand -hex 32>
#   TENANT_SLUG=<slug-da-clinica>

# Instale dependências e rode as migrações:
pnpm install --frozen-lockfile
pnpm db:migrate

# Inicie em produção (ou configure como serviço systemd):
pnpm start:prod

O servidor NestJS ficará disponível em http://<ip-do-servidor>:3001/api. Verifique: curl http://<ip-do-servidor>:3001/api/health — deve retornar {"status":"ok"}.

2. Nas estações clientes — instalar o app desktop:

  • Baixe o instalador da versão mais recente na página Releases do GitHub:
    • Windows: Clino_x.y.z_x64-setup.exe (NSIS) ou Clino_x.y.z_x64_en-US.msi
    • macOS: Clino_x.y.z_universal.dmg
    • Linux: clino_x.y.z_amd64.deb ou Clino_x.y.z_amd64.AppImage
  • Execute o instalador com permissões de administrador local.

3. Configurar o modo de conexão no app:

Ao abrir o Clino pela primeira vez (ou via menu Configurações → Conexão):

  1. Selecione o modo "Local (on-prem)" ou "Híbrido":
    • Local: o app fala apenas com o servidor LAN. Funciona sem internet.
    • Híbrido: o app tenta o servidor LAN primeiro; se indisponível, cai para a nuvem.
  2. Preencha URL do servidor local: http://<ip-do-servidor>:3001
    • Exemplo: http://192.168.1.10:3001
  3. (Modo Híbrido) Preencha URL da nuvem: https://api.clino.com.br
  4. Clique em "Testar conexão" — deve exibir "Conectado".
  5. Salve e faça login com as credenciais da clínica.

Dica de rede: anote o IP fixo do servidor ou configure um nome DNS interno (ex. clino-server.local via mDNS/Avahi) para não precisar redigitar o IP em cada estação.

Verificação pós-instalação ​

bash
# No servidor — verificar que a API responde:
curl http://localhost:3001/api/health

# No servidor — verificar que o banco de dados está acessível:
pnpm db:check   # (se disponível) ou conecte via psql e verifique as tabelas

Auto-update ​

O app desktop verifica atualizações automaticamente em cada inicialização usando tauri-plugin-updater. O endpoint de update está configurado em tauri.conf.json:

https://github.com/Clino-sistema-medico/application/releases/latest/download/latest.json

As atualizações são assinadas com a chave privada do TAURI_SIGNING_PRIVATE_KEY e verificadas no cliente com a chave pública em tauri.conf.json → plugins.updater.pubkey. O modo de instalação Windows é passive (barra de progresso, sem interação do usuário).


Assinatura de código Windows ​

Instaladores não assinados acionam o Windows SmartScreen e podem ser bloqueados por políticas de TI corporativa. A assinatura requer um certificado EV ou OV emitido por uma CA reconhecida pela Microsoft (ex. DigiCert, Sectigo, GlobalSign).

Obtendo o certificado ​

  1. Adquira um certificado EV Code Signing (EV = Extended Validation — elimina o aviso SmartScreen mais rapidamente que OV) de uma CA confiável (ex. DigiCert ou Sectigo).
  2. Complete a validação de identidade exigida pela CA.
  3. Exporte o certificado + chave privada como arquivo .pfx (PKCS#12):
    • DigiCert: painel → Certificate Central → Export → PFX
    • Guarde a senha escolhida neste momento.

Adicionando os secrets ao repositório GitHub ​

Repositório → Settings → Secrets and variables → Actions → New repository secret:

SecretValor
WINDOWS_CERTIFICATEConteúdo do .pfx codificado em base64
WINDOWS_CERTIFICATE_PASSWORDSenha usada ao exportar o .pfx

Para gerar o base64 do .pfx:

bash
# Linux/macOS
base64 -i certificate.pfx | tr -d '\n'

# PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("certificate.pfx"))

Como funciona no CI ​

O step "Import Windows code signing certificate" (somente no runner windows-latest) executa quando WINDOWS_CERTIFICATE está presente. Ele:

  1. Decodifica o base64 → arquivo .pfx temporário em $RUNNER_TEMP
  2. Importa o certificado no Windows Certificate Store do usuário corrente
  3. Extrai o thumbprint SHA-256
  4. Apaga o .pfx do disco
  5. Exporta TAURI_WINDOWS_CERTIFICATE_THUMBPRINT via $GITHUB_ENV

O Tauri usa o thumbprint para assinar os artefatos com signtool.exe. O campo bundle.windows.timestampUrl em tauri.conf.json garante que a assinatura inclua um timestamp de servidor confiável (obrigatório para EV e necessário para que o instalador continue válido após a expiração do certificado).

Verificação manual ​

Após baixar o instalador de um release assinado:

powershell
# Verificar assinatura no PowerShell
Get-AuthenticodeSignature .\Clino_x.y.z_x64-setup.exe | Select-Object Status, SignerCertificate
# Status deve ser "Valid"

Notarização macOS ​

Instaladores não assinados e não notarizados são bloqueados pelo Gatekeeper no macOS 13+ e exibem o aviso "app não pode ser aberto porque não é de um desenvolvedor identificado". A notarização exige uma conta Apple Developer ativa (US$ 99/ano).

Obtendo os artefatos Apple ​

  1. Acesse developer.apple.com → Account → Certificates, Identifiers & Profiles.
  2. Crie um certificado Developer ID Application (categoria "Software"):
    • Em macOS local: Keychain Access → Certificate Assistant → Request a Certificate From a Certificate Authority
    • Faça o upload do .certSigningRequest no portal Apple e baixe o .cer gerado.
    • Importe o .cer no Keychain e exporte como .p12 (inclui a chave privada).
  3. Anote o Team ID no canto superior direito do portal Apple Developer.
  4. Gere uma App-specific password em appleid.apple.com → Sign-In & Security → App-Specific Passwords (para xcrun notarytool).

Adicionando os secrets ao repositório GitHub ​

SecretValor
APPLE_CERTIFICATEConteúdo do .p12 (cert + chave privada) em base64
APPLE_CERTIFICATE_PASSWORDSenha usada ao exportar o .p12
APPLE_SIGNING_IDENTITYNome exato do cert no Keychain, ex. Developer ID Application: Clino Saúde (ABCD1234EF)
APPLE_IDE-mail da conta Apple Developer, ex. devops@clino.com.br
APPLE_PASSWORDApp-specific password gerada acima (formato xxxx-xxxx-xxxx-xxxx)
APPLE_TEAM_IDTeam ID de 10 caracteres, ex. ABCD1234EF

Para obter o base64 do .p12:

bash
base64 -i Developer_ID_Application.p12 | tr -d '\n'

Para confirmar o nome exato da signing identity no macOS local:

bash
security find-identity -v -p codesigning | grep "Developer ID Application"

Como funciona no CI ​

O tauri-action detecta automaticamente quando APPLE_CERTIFICATE está presente e realiza:

  1. Importação do .p12 num Keychain temporário do runner
  2. codesign --deep nos binários e no bundle .app
  3. Criação de um arquivo ZIP ou .pkg e envio para o serviço de notarização Apple via xcrun notarytool submit
  4. Espera pela aprovação (normalmente < 2 minutos)
  5. xcrun stapler staple para gravar o ticket de notarização no .dmg

Verificação manual ​

bash
# Verificar assinatura
codesign --verify --verbose=4 /Applications/Clino.app

# Verificar notarização
spctl --assess --verbose=4 /Applications/Clino.app
# Deve exibir: source=Notarized Developer ID

Resumo de todos os secrets necessários ​

SecretSOPropósito
TAURI_SIGNING_PRIVATE_KEYTodosAssina artefatos do auto-updater (tauri-plugin-updater)
TAURI_SIGNING_PRIVATE_KEY_PASSWORDTodosSenha da chave acima
WINDOWS_CERTIFICATEWindowsCertificado EV/OV em base64 (.pfx)
WINDOWS_CERTIFICATE_PASSWORDWindowsSenha do .pfx
APPLE_CERTIFICATEmacOSCertificado Developer ID em base64 (.p12)
APPLE_CERTIFICATE_PASSWORDmacOSSenha do .p12
APPLE_SIGNING_IDENTITYmacOSNome da identidade de assinatura no Keychain
APPLE_IDmacOSE-mail da conta Apple Developer
APPLE_PASSWORDmacOSApp-specific password para notarização
APPLE_TEAM_IDmacOSTeam ID de 10 caracteres

Nunca commite certificados, chaves privadas ou .pfx/.p12 no repositório. Gerencie-os exclusivamente via GitHub Secrets ou um vault externo (ex. AWS Secrets Manager).


7. Referência rápida — Tauri CLI ​

Todos os comandos abaixo rodam a partir de apps/web/:

bash
# Desenvolvimento
pnpm tauri dev                          # janela nativa + hot-reload do Vite

# Build de produção (SO atual apenas)
pnpm tauri build                        # gera instaladores em src-tauri/target/release/bundle/
pnpm tauri build --debug                # build de produção sem otimizações (mais rápido, para testes)

# Ícones
pnpm tauri icon <caminho/para/icon.png> # gera todos os tamanhos a partir de um PNG 1024×1024

# Signing / updater
tauri signer generate -w ~/.tauri/clino.key  # gera keypair para o auto-updater
tauri signer sign -k ~/.tauri/clino.key <arquivo.tar.gz>  # assina manualmente um artefato

# Dependências do sistema (verifica o que falta)
tauri info                              # exibe versões do Rust, Node, dependências de sistema

# Atualizar a CLI do Tauri
cargo install tauri-cli                 # instala/atualiza a CLI globalmente via cargo

Versioning no CI ​

O bump de versão é calculado automaticamente a partir da última tag v* no histórico git:

TipoExemplo (de v1.2.3)Uso
releasev1.3.0Releases normais / diárias
hotfixv1.2.4Correções urgentes
majorv2.0.0Grandes releases com breaking changes

Dispare via Actions → Run workflow e selecione o tipo, ou push de tag explícita:

bash
git tag v1.3.0 && git push origin v1.3.0