Crea un'app iOS da Linux con Capacitor e Capgo Build

Linux è l'ambiente ideale per scrivere app Capacitor, e per Android non ci sono compromessi. iOS è l'eccezione: Xcode e gli strumenti di firma Apple girano solo su macOS. La soluzione non è un Mac mini sotto la scrivania, ma generare il progetto iOS localmente e compilarlo su macOS nel cloud.

Questa guida è la versione Linux di Crea un'app iOS da Windows con Capacitor e Capgo Build. Copre le parti che differiscono su Linux: certificati OpenSSL, shell Linux e CI tramite runner Linux.

La divisione dei compiti

Un'app Capacitor ha due build:

• Build web: l'output del tuo framework in dist/. Eseguita su Linux.
• Native Build: archivio Xcode, signing e upload. Gestito da Build con Capgo su macchine Apple Silicon con le versioni correnti di macOS e Xcode.

Il CLI effettua l'upload del ios/ progetto dalla tua macchina. Non serve un host Git e nessuna credenziale di registry privato esce dalla tua macchina, perché l'installazione delle dipendenze cap sync avviene localmente prima dell'upload.

Prerequisiti

• Un'app Capacitor che builda localmente (qualsiasi framework).
• Node 20+ o Bun su Linux.
• Un abbonamento all'Apple Developer Program.
• OpenSSL (installato di default su quasi tutte le distro).
• Un account Capgo e l'app registrata su bunx @capgo/cli@latest app add.

1) Genera il progetto iOS su Linux

bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add ios

Vedrai qualcosa di simile a Skipping pod install because CocoaPods is not installed. Previsto. La ios/ cartella esiste e va committata; contiene bundle ID, Info.plist, icone e impostazioni native.

2) Sincronizza gli asset web prima di ogni build

bun run build
bunx cap sync ios

cap sync copia dist/ in ios/App/App/public e aggiorna i riferimenti ai plugin. Capgo compila il contenuto di ios/, quindi un progetto non sincronizzato caricherà la vecchia UI.

3) Creare i certificati di firma senza un Mac

Ti servono tre cose: un certificato Apple Distribution come .p12, un provisioning profile per l'App Store e una chiave API di App Store Connect. Nessuno richiede l'accesso al Keychain.

Certificato di distribuzione con OpenSSL

openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Your Name/C=US"

Upload ios_distribution.csr in Certificates, Identifiers & Profiles, scegli Apple Distribution e scarica distribution.cer. Converti e crea il bundle:

openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
  -out ios_distribution.p12 -legacy

L'oggetto -legacy il flag è importante con OpenSSL 3. Senza di esso, gli strumenti Apple rifiutano il .p12 con un errore di password non valida anche se la password è corretta. Se preferisci non toccare OpenSSL, il generatore di certificati iOS fa la stessa cosa nel browser.

Profilo di provisioning e chiave API

Nel portale Apple Developer, crea un profilo App Store per il tuo bundle ID usando il nuovo certificato e scarica il .mobileprovision. In App Store Connect, crea una chiave API con ruolo App Manager e scarica il .p8; annota il Key ID e l'Issuer ID. Il Guida alla build iOS mostra ogni schermata.

Vuoi ispezionare un profilo su Linux? openssl smime -inform der -verify -noverify -in profile.mobileprovision stampa il plist incorporato.

4) Salva le credenziali in Capgo

bunx @capgo/cli@latest login
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id "TEAMID" \
  --apple-key ./AuthKey_KEYID.p8 \
  --apple-key-id "KEYID" \
  --apple-issuer-id "issuer-uuid" \
  --certificate ./ios_distribution.p12 \
  --ios-provisioning-profile ./App_Store.mobileprovision

Oppure esegui bunx @capgo/cli@latest build init --platform ios per la versione guidata. Su Linux, il passaggio della chiave App Store Connect è manuale; tutto il resto viene gestito tramite prompt.

Se Apple rifiuta la chiave con un errore di autenticazione, sincronizza l'orologio. Il JWT è firmato con l'ora locale e Apple rifiuta i token con un drift eccessivo:

timedatectl status
sudo timedatectl set-ntp true

5) Richiedi la build

bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

Il preparato ios/ progetto viene caricato, Capgo esegue pod install, archivia con Xcode, firma con il tuo certificato e invia i log al terminale. Con la chiave API configurata, la build viene inviata a TestFlight al termine. Installa l'app TestFlight su un iPhone per testarla.

Le build fallite possono essere diagnosticate automaticamente aggiungendo --ai-analytics; la diagnosi AI della build legge il log di Xcode e spiega come risolvere.

6) Build ad hoc per tester senza TestFlight

Per un dispositivo QA registrato tramite UDID, usa un profilo Ad Hoc e conserva l'IPA come artifact:

bunx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

Il CLI genera un link di download temporaneo. Aggiungi --output-record build.json per salvare il link e un QR code per un tester.

7) Automazione da un runner CI Linux

Gli stessi comandi funzionano su qualsiasi CI Linux. Ecco un esempio GitHub Actions:

name: iOS build
on:
  workflow_dispatch:
jobs:
  ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun run build
      - run: bunx cap sync ios
      - run: bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Le credenziali salvate al punto 4 sono memorizzate in Capgo, quindi al runner serve solo il token. In alternativa, esporta una CI .env con bunx @capgo/cli@latest build credentials manage e passa i valori come secrets; vedi la gestione delle credenziali.

8) Iterazione quotidiana senza Native Build

Una volta creato il build per TestFlight, la maggior parte delle modifiche riguarda il web. Pushale con Live Updates di Capgo:

bun run build
bunx @capgo/cli@latest bundle upload --channel production

Riserva build request per l'aggiunta di plugin, modifiche ai permessi, icone e upgrade di Capacitor.

Criticità su Linux

• Dimenticato cap sync ios: l'IPA mostra la vecchia UI. Fai il sync prima di ogni richiesta.
• ios/ le .gitignore: CLI carica dal disco quindi il build passa, ma i colleghi e la CI non avranno il progetto nativo. Fai il commit.
• .p12 password rifiutata: rigenera con -legacy.
• Autenticazione Apple fallita: clock drift. Abilita NTP.
• Plugin aggiunto, dimenticato il rebuild nativo: l'aggiunta di un plugin Capacitor modifica il binario nativo. Esegui un nuovo cloud build e l'invio agli store prima di rilasciare modifiche web che lo utilizzano.

Riassunto

Linux non può eseguire Xcode, ma non ne ha bisogno. Genera ios/ con Capacitor, crea i certificati con OpenSSL e lascia che Capgo Build compili, firmi e invii a TestFlight. Grazie a Live Updates per il layer web, un team che lavora solo su Linux può rilasciare iOS con la stessa routine di Android. Per la configurazione completa dell'ambiente, leggi lo sviluppo Capacitor su Linux.