Tema
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-configNo WSL2, certifique-se de que está rodando uma distribuição Ubuntu 22.04+ ou Debian 12+.
libwebkit2gtk-4.1-devexige 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-darwinO
pnpm tauri buildlocal produz apenas para a arquitetura do runner atual (ex.aarch64). O CI usa--target universal-apple-darwinpara 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 --versionNo 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 buildproduz instaladores apenas para o SO da máquina atual. Não há cross-compile: para gerar.dmgmacOS numa máquina Linux, use o CI.
Localização dos artefatos após pnpm tauri build:
| SO | Localização |
|---|---|
| Linux | src-tauri/target/release/bundle/appimage/ e deb/ |
| macOS | src-tauri/target/release/bundle/dmg/ |
| Windows | src-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.47Commite 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 ReleaseOs 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.
| Secret | SO | Obrigatório | Propósito |
|---|---|---|---|
TAURI_SIGNING_PRIVATE_KEY | Todos | Sim | Chave privada para assinar artefatos do auto-updater |
TAURI_SIGNING_PRIVATE_KEY_PASSWORD | Todos | Sim (pode ser "") | Senha da chave acima |
WINDOWS_CERTIFICATE | Windows | Não (gera não-assinado) | Certificado EV/OV em base64 (.pfx) |
WINDOWS_CERTIFICATE_PASSWORD | Windows | Se WINDOWS_CERTIFICATE presente | Senha do .pfx |
APPLE_CERTIFICATE | macOS | Não (gera não-assinado) | Certificado Developer ID em base64 (.p12) |
APPLE_CERTIFICATE_PASSWORD | macOS | Se APPLE_CERTIFICATE presente | Senha do .p12 |
APPLE_SIGNING_IDENTITY | macOS | Se APPLE_CERTIFICATE presente | Nome da identidade no Keychain |
APPLE_ID | macOS | Se APPLE_CERTIFICATE presente | E-mail da conta Apple Developer |
APPLE_PASSWORD | macOS | Se APPLE_CERTIFICATE presente | App-specific password para notarização |
APPLE_TEAM_ID | macOS | Se APPLE_CERTIFICATE presente | Team 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
- Acesse a aba Actions no repositório GitHub.
- Selecione o workflow "Release (desktop installers)".
- Clique em "Run workflow" → escolha o tipo de bump:
release(padrão),hotfixoumajor. - 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.0Os 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:prodO 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) ouClino_x.y.z_x64_en-US.msi - macOS:
Clino_x.y.z_universal.dmg - Linux:
clino_x.y.z_amd64.debouClino_x.y.z_amd64.AppImage
- Windows:
- 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):
- 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.
- Preencha URL do servidor local:
http://<ip-do-servidor>:3001- Exemplo:
http://192.168.1.10:3001
- Exemplo:
- (Modo Híbrido) Preencha URL da nuvem:
https://api.clino.com.br - Clique em "Testar conexão" — deve exibir "Conectado".
- 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.localvia 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 tabelasAuto-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.jsonAs 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
- 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).
- Complete a validação de identidade exigida pela CA.
- 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:
| Secret | Valor |
|---|---|
WINDOWS_CERTIFICATE | Conteúdo do .pfx codificado em base64 |
WINDOWS_CERTIFICATE_PASSWORD | Senha 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:
- Decodifica o base64 → arquivo
.pfxtemporário em$RUNNER_TEMP - Importa o certificado no Windows Certificate Store do usuário corrente
- Extrai o thumbprint SHA-256
- Apaga o
.pfxdo disco - Exporta
TAURI_WINDOWS_CERTIFICATE_THUMBPRINTvia$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
- Acesse developer.apple.com → Account → Certificates, Identifiers & Profiles.
- 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
.certSigningRequestno portal Apple e baixe o.cergerado. - Importe o
.cerno Keychain e exporte como.p12(inclui a chave privada).
- Anote o Team ID no canto superior direito do portal Apple Developer.
- 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
| Secret | Valor |
|---|---|
APPLE_CERTIFICATE | Conteúdo do .p12 (cert + chave privada) em base64 |
APPLE_CERTIFICATE_PASSWORD | Senha usada ao exportar o .p12 |
APPLE_SIGNING_IDENTITY | Nome exato do cert no Keychain, ex. Developer ID Application: Clino Saúde (ABCD1234EF) |
APPLE_ID | E-mail da conta Apple Developer, ex. devops@clino.com.br |
APPLE_PASSWORD | App-specific password gerada acima (formato xxxx-xxxx-xxxx-xxxx) |
APPLE_TEAM_ID | Team 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:
- Importação do
.p12num Keychain temporário do runner codesign --deepnos binários e no bundle.app- Criação de um arquivo ZIP ou
.pkge envio para o serviço de notarização Apple viaxcrun notarytool submit - Espera pela aprovação (normalmente < 2 minutos)
xcrun stapler staplepara 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 IDResumo de todos os secrets necessários
| Secret | SO | Propósito |
|---|---|---|
TAURI_SIGNING_PRIVATE_KEY | Todos | Assina artefatos do auto-updater (tauri-plugin-updater) |
TAURI_SIGNING_PRIVATE_KEY_PASSWORD | Todos | Senha da chave acima |
WINDOWS_CERTIFICATE | Windows | Certificado EV/OV em base64 (.pfx) |
WINDOWS_CERTIFICATE_PASSWORD | Windows | Senha do .pfx |
APPLE_CERTIFICATE | macOS | Certificado Developer ID em base64 (.p12) |
APPLE_CERTIFICATE_PASSWORD | macOS | Senha do .p12 |
APPLE_SIGNING_IDENTITY | macOS | Nome da identidade de assinatura no Keychain |
APPLE_ID | macOS | E-mail da conta Apple Developer |
APPLE_PASSWORD | macOS | App-specific password para notarização |
APPLE_TEAM_ID | macOS | Team ID de 10 caracteres |
Nunca commite certificados, chaves privadas ou
.pfx/.p12no 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 cargoVersioning no CI
O bump de versão é calculado automaticamente a partir da última tag v* no histórico git:
| Tipo | Exemplo (de v1.2.3) | Uso |
|---|---|---|
release | v1.3.0 | Releases normais / diárias |
hotfix | v1.2.4 | Correções urgentes |
major | v2.0.0 | Grandes 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