Building and Signing a Desktop Application for macOS

Building and Signing a Desktop Application for macOS

Situation: the app is built, but on modern macOS versions (14+) Gatekeeper blocks it from launching. Users report: "cannot be opened because Apple cannot check it for malicious software." The root cause is the lack of code signing and notarization. Without them, Gatekeeper blocks the launch, and bypassing it through "System Settings" requires non-standard actions that most users won't perform.

It can be fixed in 3–4 days if the chain is set up correctly: Developer ID certificate → entitlements → code signing → notarization → stapling. We do this turnkey for Electron, Qt, SwiftUI, and other frameworks. With over 5 years of experience, we've delivered more than 50 releases for macOS — not one was blocked. Apple Notarization Guide

Entry cost: you need an Apple Developer Program subscription ($99/year) to obtain a Developer ID Application certificate. Notarization itself is free for developers.

Why Code Signing Is Critical

Code signing is a digital signature that guarantees the application's integrity. macOS checks it on every launch. Without it, Gatekeeper blocks the app, forcing the user to manually authorize it via "System Settings" or Terminal. For enterprise environments this is unacceptable: MDM policies prohibit running unsigned apps. Notarization adds Apple's verification for malicious code. Both are mandatory for distribution outside the Mac App Store.

How We Sign and Notarize macOS Apps

The process includes 2 mandatory stages: Code Signing and Notarization. First, obtain a Developer ID Application certificate (requires Apple Developer Account). Then configure the build with the correct entitlements. Below is a minimal config for Electron.

// electron-builder.yml
mac:
  target:
    - target: dmg
    - target: zip
  icon:      build/icon.icns
  category:  public.app-category.productivity
  hardenedRuntime:   true
  gatekeeperAssess:  false
  entitlements:          build/entitlements.mac.plist
  entitlementsInherit:   build/entitlements.mac.plist
  identity: "Developer ID Application: Company Name (TEAM_ID)"

<!-- build/entitlements.mac.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>com.apple.security.cs.allow-jit</key><true/>
  <key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/>
  <key>com.apple.security.cs.allow-dyld-environment-variables</key><true/>
  <key>com.apple.security.network.client</key><true/>
</dict>
</plist>

What Entitlements Are Needed for Electron Apps?

Electron requires 4 keys: allow-jit (for V8), allow-unsigned-executable-memory (for JIT compilation), allow-dyld-environment-variables (for Node.js), and network.client (for HTTP requests). Without them the app will crash on start or fail to make network requests. Compare this with entitlements for native SwiftUI apps: there you typically only need com.apple.security.app-sandbox and com.apple.security.files.user-selected.read-write.

Notarization and Stapling

After code signing we submit the .dmg for notarization via notarytool. Apple scans the binaries for viruses and malicious code. The result is a notarization ticket, which is attached to the file using the stapler command.

# Using notarytool (Xcode 13+)
xcrun notarytool submit AppName.dmg \
  --apple-id     "[email protected]" \
  --password     "@keychain:AC_PASSWORD" \
  --team-id      "TEAM_ID" \
  --wait

# Stapling (embedding the notarization ticket into the file)
xcrun stapler staple AppName.dmg

Notarytool works 3x faster than the old altool and has better support since it's actively developed by Apple.

Step-by-Step Code Signing Configuration in CI/CD

1. Obtain a Developer ID Application certificate from the Apple Developer Portal (type Developer ID Application, not Development).
2. Export the certificate as .p12 and store it in CI secrets (e.g., GitHub Secrets).
3. Configure electron-builder or equivalent with the required entitlements (see above).
4. Add a step to import the certificate into the CI pipeline.
5. Set up a notarization stage with notarytool and stapling.
6. Test the build both locally and in CI.

GitHub Actions for macOS

- uses: actions/checkout@v3
- name: Import Certificate
  run: |
    echo "$MACOS_CERTIFICATE" | base64 --decode > certificate.p12
    security import certificate.p12 -P "$MACOS_CERTIFICATE_PWD" \
      -A -t cert -f pkcs12 -k ~/Library/Keychains/login.keychain

- name: Build and Sign
  run: npm run build:mac
  env:
    APPLE_ID:          ${{ secrets.APPLE_ID }}
    APPLE_ID_PASS:     ${{ secrets.APPLE_ID_PASS }}
    APPLE_TEAM_ID:     ${{ secrets.APPLE_TEAM_ID }}
    CSC_LINK:          ${{ secrets.MACOS_CERTIFICATE }}
    CSC_KEY_PASSWORD:  ${{ secrets.MACOS_CERTIFICATE_PWD }}

Universal Binary (Intel + Apple Silicon)

A universal binary is a build containing both architectures (x86_64 and arm64). It runs natively on M1/M2/M3 without Rosetta 2. This is mandatory for the App Store and many enterprise environments. Performance savings: without a universal binary you lose up to 30% on Apple Silicon.

# electron-builder automatically creates a universal binary
npx electron-builder --mac --universal

What's Included in Our Turnkey Configuration

Additionally: setting up auto-update (Sparkle, Electron auto-updater), white-label signing, Apple Developer Enterprise Program support.

Typical Pitfalls

• Using an Apple Development certificate instead of Developer ID — only works for debugging.
• Missing hardenedRuntime: true — notarization will fail.
• Wrong entitlements for Electron — crash on launch.
• Skipping stapling — users see a warning if offline.
• Forgetting the universal binary — performance loss on Apple Silicon.
• Developer ID Application certificate is invalid if you chose the wrong type (must be Developer ID, not Development).
• Notarization fails if hardenedRuntime is not enabled.
• App crashes on start — check entitlements: for Electron, allow-jit and allow-unsigned-executable-memory are mandatory.
• Stapling fails if the file is corrupted — run stapler immediately after notarytool.

Based on our experience, we recommend testing notarization on every release. Even an Electron version upgrade can break entitlements.

Timelines and Guarantee

Basic setup takes 3–4 working days. We guarantee that the app will pass notarization and run on macOS 10.14 and later. Contact us to configure signing in 3–4 days and avoid Gatekeeper blocks. Get a consultation for your project — we'll help you avoid typical mistakes and save time.

We regularly encounter a situation: "The site is not opening" at 3 a.m. — and it turns out that the VPS disk is full because nginx logs haven't been rotated for six months. Or the server went down under load on the day of an advertising campaign launch because the shared hosting had a limit of 50 concurrent connections. Setting up hosting and deployment is not about "where it's cheaper" but about what happens when something goes wrong. Our team helps avoid such incidents by designing infrastructure that accounts for real load patterns.

When to choose Vercel and Netlify?

Vercel is built for Next.js — deploy in one push, preview deployments for every PR, automatic CDN, Edge Functions, ISR without configuration. For frontend projects and JAMstack, it's the optimal choice: no operational overhead, time-to-deploy measured in minutes.

Real limitations: Vercel Serverless Functions run in us-east-1 by default (latency for Europe +80–100ms), Function timeout 300 seconds on Pro, Bandwidth 1TB/month on Pro. For heavy backend, you need workers or a separate server.

Netlify is closer to static sites and Edge Functions based on Deno Deploy. Build minutes are the main limitation on the free tier.

Why is Docker the foundation of predictable deployment?

"It works on my machine" — classic. Docker solves this through environment containerization. But a bad Dockerfile creates new problems.

A typical mistake: copying everything into the image without .dockerignore, resulting in an 800MB image instead of 80MB. node_modules inside the image weighs as much. Correct approach: multi-stage build.

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
EXPOSE 3000
CMD ["npm", "start"]

Final image: 180MB instead of 1.2GB. CI build time is reduced due to layer caching — if package.json hasn't changed, the layer with npm ci is taken from cache.

Docker Compose for local development and simple production scenarios: application + PostgreSQL + Redis in one configuration. For production on a single server, it's a perfectly viable option if there's no requirement for horizontal scaling.

More about containerization — Wikipedia: Docker.

How to set up Nginx as a reverse proxy?

Nginx in front of the application is standard for VPS and dedicated servers. Main functions: SSL termination, gzip, static files, rate limiting, upstream load balancing.

A configuration often done incorrectly: worker_processes auto — number of processes equals CPU count. worker_connections 1024 — that's 1024 per worker process. With 4 CPUs and 1024 connections = 4096 concurrent connections. For a high-traffic site, you need worker_connections 4096 and set keepalive_timeout 65.

For static assets with hash in the filename:

location ~* \.(js|css|woff2|png|webp)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

immutable tells the browser: don't revalidate this file even on hard refresh. This only works correctly with content-hashed filenames (which Vite/webpack do by default). Documentation — Wikipedia: Nginx.

AWS: flexibility and complexity

EC2 + Auto Scaling Group — classic for horizontal scaling. AMI with pre-installed application, Launch Template, ASG with min/desired/max instances, Application Load Balancer. When CPU > 70% for 3 minutes — scale out, when CPU < 30% for 15 minutes — scale in. Health check via ALB removes unhealthy instances from rotation.

ECS Fargate — containers without managing EC2. Deploy a Docker image, specify CPU/memory (512 CPU units = 0.5 vCPU, from 512MB memory), Fargate launches it. More expensive than Lambda, but no cold start and no timeout limitations. Suitable for long-running processes, WebSocket servers, heavy workers.

RDS for PostgreSQL with Multi-AZ: automatic failover in 1–2 minutes when primary fails. Read Replicas for scaling reads. RDS Proxy for connection pooling — Lambda functions cannot hold long-term connections, the proxy buffers this.

Kubernetes: when it is justified

K8s adds significant operational complexity. Justified when: multiple teams deploy independent services, fine-grained resource allocation per service is needed, canary deployments and blue/green without downtime are required.

AWS EKS, GKE, or managed k8s from Hetzner (cheaper). Helm charts for standard services. Horizontal Pod Autoscaler based on CPU and custom metrics (RPS via Prometheus).

For most startups and medium-sized projects, Kubernetes is overkill. ECS or Fly.io provide 80% of the capabilities with 20% of the operational complexity.

Monitoring and alerting

A server without monitoring is waiting for an incident. Minimal stack: Prometheus + Grafana (or Grafana Cloud for managed), alerting on disk > 80%, memory > 85%, CPU > 90% over 5 minutes, error rate > 1%. Uptime via Better Uptime or Upptime (self-hosted).

Logs: Loki + Grafana or CloudWatch Logs Insights. Structured JSON logs (winston, pino) are mandatory — otherwise, log searching becomes a pain.

What is included in hosting setup

• Audit of current infrastructure and load profiling
• Selection of target architecture (VPS, AWS, serverless, Kubernetes)
• Setting up CI/CD pipeline (GitHub Actions, GitLab CI) with automatic deployment
• IaC via Terraform or Pulumi (infrastructure as code)
• Configuration of Nginx, SSL certificates, HTTP/2, brotli
• Monitoring and alerting (Prometheus + Grafana, PagerDuty)
• Documentation of runbooks and team training

Additionally, contact us if you need migration from current hosting or integration with external services.

Work process

1. Audit of current infrastructure (2–5 days)
2. Selection of target architecture with load and budget justification (1–3 days)
3. Setting up CI/CD pipeline (GitHub Actions, GitLab CI) (2–5 days)
4. IaC via Terraform or Pulumi (3–10 days)
5. Setting up monitoring and alerting (2–5 days)
6. Documentation of runbooks and team training (1–3 days)

Our experience — 7 years on the market, over 50 projects, guarantee of operability after deployment.

Timeline

• Basic deployment on VPS with Docker + Nginx + CI/CD: 1–2 weeks.
• Setting up AWS infrastructure with Auto Scaling, RDS, CDN: 3–6 weeks.
• Migration to EKS from scratch: 6–12 weeks.
• Setting up Vercel/Netlify for JAMstack: 3–5 days.

The cost is calculated individually depending on complexity and scope of work. Get a consultation — we'll evaluate your architecture in one day.