In this tutorial, you’ll build a distributed rate limiter. This is the kind of system you need when your application is deployed across multiple servers or virtual machines, and you need to enforce a global limit on all incoming requests.

You’ll build a simple URL shortener application and then implement a robust rate limiter for it using a powerful and efficient combination of tools:

• Python and Flask for your web application.

• Redis as your high-speed, centralized data store for tracking requests.

• Terraform and Proxmox to define and provision your virtual machine infrastructure.

• Docker to containerize your application for easy deployment.

• Nginx as a load balancer to distribute traffic across your app servers.

• k6 to load-test your system and prove that your rate limiter actually works.

This is intended for new developers learning about various system design concepts or for experts who just want a refresher.

By the end of this guide, you'll understand not just the code, but the complete system architecture required to deploy a scalable, resilient application.

Let's get started!

Prerequisites

While not absolutely required to follow along, I’d recommend setting up a Proxmox server on an old laptop to implement the topics you learn and code along with the article. I recommend this YouTube playlist for getting started. Please note that I am in no way affiliated with this channel. I just found it helpful for me.

However, If you do not have a local Proxmox server, you can skip that part and just follow along to understand how a rate limiter is built and how it is set up to properly work with multiple servers.

Table of Contents

• Prerequisites

• The Big Picture: Our System Architecture

• Step 1: How to Define the Infrastructure with Terraform

• Step 2: How to Implement the Rate Limiter Logic in Python

• Step 3: Containerizing and Testing

• Conclusion

The Big Picture: Our System Architecture

Before we dive into the code, let's look at the architecture we're building. I will be using Proxmox Virtual Environment to setup a server cluster just like you would have in a datacenter.

How to Set Up Proxmox

Proxmox Virtual Environment is an open source platform for virtualization. It lets you manage multiple VMs, ccontainers and other clusters with ease. For instance, I turned my old gaming computer into a Proxmox server which lets me run more than 20 virtual machines on it at the same time, making it similar to my very own datacenter. This lets me experiment with distributed applications by simulating datacenter environments.

To setup your own cluster, all you need is an old computer. You can download the ISO image from here and boot from the USB drive. Once you install it, you can configure the host machine via a web browser on any other computer on the same network.

For example, my proxmox server is located at 10.0.0.108 and I can access it via the browser on my laptop.

We define all our virtual machines in our main.tf file. And run a simple command terraform apply to spin these servers up. For more reading on how to use Terraform with Proxmox, I recommend this blog post

Back to our use case, we’ll have a few virtual machines that will serve as different kinds of servers:

1. A Load balancer

2. A Rate Limiter ( A Redis Cache )

3. Two Web Servers

4. A Postgres database

5. One Virtual Machine that will test the load by simulating hundreds of calls per minute.

If all of this seems daunting, don’t worry too much about it. You don’t need to set all this up to follow along.

Centralized Rate Limiter

Since our application will run on multiple servers (or "nodes"), we can't store request counts in memory on each individual server. Why? Because each server would have its own separate count, and we wouldn't have a global rate limit.

The solution is to use a centralized data store that all our application nodes can access. This is where Redis comes in.

Here’s a diagram of our setup:

1. User requests first hit our Nginx load balancer.

2. The load balancer distributes the traffic evenly between our two web server VMs. The configuration is simple, using an upstream block to define the servers.

3. Each web server runs our Python Flask application inside a Docker container.

4. Before processing any request, the Flask app communicates with the central Redis rate limiter VM to check if the user has exceeded the rate limit.

5. If the user is within the limit, the app processes the request and interacts with the PostgreSQL Database. If they're over the limit, it sends back a “429 Too Many Requests” error.

This architecture ensures that no matter which web server handles the request, the rate limit is checked against the same, shared data source.

Step 1: How to Define the Infrastructure with Terraform

Manually setting up multiple virtual machines can be tedious and prone to errors. That's why we use Terraform, an Infrastructure as Code (IaC) tool. It lets us define our entire infrastructure in configuration files.

Note: You can skip this section if you just want to see the rate limiter in action and how it’s used.

Our main.tf file defines all the components of our system. Let's look at a key piece: the Redis VM.

# --- Redis Cache for Rate Limiter ---
resource "proxmox_vm_qemu" "redis_cache" {

    vmid        = 130
    name        = "redis-cache-rate-limiter"
    target_node = "pve"
    agent       = 1
    cores       = 1
    memory      = 1024
    # ... cloud-init config ...
    ipconfig0  = "ip=10.0.0.130/24,gw=10.0.0.1"
    # ... disk and network config ...

    # 1. Install Docker
    provisioner "remote-exec" {
        inline = [
            "sleep 30; sudo apt-get update -y",
            "sudo apt-get install -y docker.io docker-compose",
            "sudo mkdir -p /opt/redis"
        ]
    }

    # 2. Upload docker-compose file
    provisioner "file" {
         source      = "files/redis-docker-compose.yml"
         destination = "/home/${var.ssh_user}/docker-compose.yml"
    }

    # 3. Move file and run docker-compose
    provisioner "remote-exec" {
        inline = [
            "sudo mv /home/${var.ssh_user}/docker-compose.yml /opt/redis/docker-compose.yml",
            "cd /opt/redis && sudo docker-compose up -d"
        ]
    }
}

This block tells Terraform to create a Proxmox QEMU virtual machine with a specific IP address (10.0.0.130). After the VM is created, it uses provisioners to connect via SSH and run commands. Here, it installs Docker, uploads our redis-docker-compose.yml file, and starts the Redis container.

The redis-docker-compose.yml itself is very straightforward:

version: '3.8'
services:
  redis:
    image: redis:latest
    container_name: redis_cache
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data

volumes:
  redisdata:

This ensures we have a persistent, containerized Redis instance ready to serve our application. The Terraform configuration similarly defines our web servers, load balancer, and databases.

Step 2: How to Implement the Rate Limiter Logic in Python

Now, for the heart of our system: the Python code that implements the rate limiting logic. We're using a sophisticated and memory-efficient algorithm called the Sliding Window Log.

The idea is simple: for each user, we keep a log of the timestamps of their recent requests. We store this log in a Redis Sorted Set.

Let's break down the code from app.py.

The Flask @app.before_request Hook

Flask allows us to run code before any request is handled by its intended view function. This is the perfect place to put our rate limiter.

import psycopg2
import string
import random
import redis
import time
from flask import Flask, request, redirect, jsonify

app = Flask(__name__)

# --- Database Connection Details ---
DB_HOST = "10.0.0.200" 
DB_NAME = "urldb"
DB_USER = "myuser"
DB_PASS = "mypassword"

REDIS_HOST = "10.0.0.130" # IP of your redis-cache-lxc

# --- Rate Limiter Settings ---
RATE_LIMIT_COUNT = 10  # 10 requests
RATE_LIMIT_WINDOW = 60 # per 60 seconds

# Establish a reusable Redis connection
redis_client = redis.Redis(host=REDIS_HOST, port=6379, decode_responses=True)

@app.before_request
def rate_limiter():
    # Use the user's IP address as the key
    # In a real app, you'd handle proxies via request.environ.get('HTTP_X_FORWARDED_FOR', request.remote_addr)
    key = f"rate_limit:{request.remote_addr}"
    now = time.time()

    # Use a Redis pipeline for atomic operations
    pipe = redis_client.pipeline()
    # 1. Add current request timestamp. The score and member are the same.
    pipe.zadd(key, {str(now): now})
    # 2. Remove all timestamps older than our window
    pipe.zremrangebyscore(key, 0, now - RATE_LIMIT_WINDOW)
    # 3. Get the count of remaining timestamps
    pipe.zcard(key)
    # 4. Set an expiration on the key so it cleans itself up
    pipe.expire(key, RATE_LIMIT_WINDOW)

    # Execute the pipeline and get the results
    results = pipe.execute()
    request_count = results[2] # The result of the zcard command

    if request_count > RATE_LIMIT_COUNT:
        # Return a 429 Too Many Requests error
        return jsonify(error="Rate limit exceeded"), 429

def get_db_connection():
    conn = psycopg2.connect(host=DB_HOST, dbname=DB_NAME, user=DB_USER, password=DB_PASS)
    return conn

def init_db():
    conn = get_db_connection()
    cur = conn.cursor()
    cur.execute('''
        CREATE TABLE IF NOT EXISTS urls (
            id SERIAL PRIMARY KEY,
            short_code VARCHAR(6) UNIQUE NOT NULL,
            original_url TEXT NOT NULL
        );
    ''')
    # Check if the index exists before creating it
    cur.execute('''
        SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
        WHERE c.relname = 'idx_original_url' AND n.nspname = 'public';
    ''')
    if cur.fetchone() is None:
        cur.execute('CREATE INDEX idx_original_url ON urls (original_url);')
    conn.commit()
    cur.close()
    conn.close()

def generate_short_code(length=6):
    chars = string.ascii_letters + string.digits
    return ''.join(random.choice(chars) for _ in range(length))

@app.route("/", methods=['GET'])
def index():
    return "URL Shortener is running!\n", 200

@app.route('/shorten', methods=['POST'])
def shorten_url():
    original_url = request.form['url']
    conn = get_db_connection()
    cur = conn.cursor()

    cur.execute("SELECT short_code FROM urls WHERE original_url = %s", (original_url,))
    existing_url = cur.fetchone()

    if existing_url:
        short_code = existing_url[0]
    else:
        short_code = generate_short_code()
        cur.execute("INSERT INTO urls (short_code, original_url) VALUES (%s, %s)", (short_code, original_url))
        conn.commit()

    cur.close()
    conn.close()

    return jsonify(short_url=f"/{short_code}")

@app.route('/<short_code>')
def redirect_to_url(short_code):
    conn = get_db_connection()
    cur = conn.cursor()
    cur.execute("SELECT original_url FROM urls WHERE short_code = %s", (short_code,))
    url_record = cur.fetchone()
    cur.close()
    conn.close()

    if url_record:
        return redirect(url_record[0])
    else:
        return "URL not found", 404

if __name__ == '__main__':
    init_db() 
    app.run(host='0.0.0.0', port=5000)

How It Works, Step-by-Step

1. Identify the User: We create a unique Redis key for each user based on their IP address: rate_limit:1.2.3.4.

2. Use a Pipeline: Network latency can be a bottleneck. A Redis pipeline bundles multiple commands into a single request-response cycle. This is much more efficient than sending them one by one. It also ensures the sequence of commands runs without being interrupted by commands from other clients.

3. Log the Current Request (ZADD): We add the current timestamp (as a Unix epoch) to a sorted set. We use the timestamp for both the "member" and the "score," which allows us to easily filter by time.

4. Clean Up Old Requests (ZREMRANGEBYSCORE): This is the "sliding window" part. We remove any timestamps from the set that are older than our RATE_LIMIT_WINDOW (60 seconds). This efficiently discards requests that are no longer relevant to the current rate limit period.

5. Count the Recent Requests (ZCARD): We get the cardinality (the number of items) in the set. After the previous step, this number is our count of requests within the last 60 seconds.

6. Mark the current record to expire (EXPIRE): We set an expiration on the key itself. If a user stops making requests, Redis will automatically delete their rate limit data after 60 seconds, preventing memory from filling up with old keys.

7. Execute and Check: The pipe.execute() command sends all our bundled commands to Redis. We then check the result of our ZCARD command. If the count exceeds our RATE_LIMIT_COUNT, we immediately return a 429 error.

This approach is incredibly fast and efficient. All the heavy lifting is done inside Redis, which is optimized for these kinds of operations.

Step 3: Containerizing and Testing

To deploy our application consistently across multiple VMs, we use Docker. Our Dockerfile is standard for a Python application: it starts from a Python image, installs dependencies from requirements.txt, copies the application code, and defines the command to run the app.

But how do we know it works? We test it!

We use k6, a modern load testing tool, to simulate heavy traffic. Our test script, rate-test.js, is designed specifically to verify the rate limiter.

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    // Ramp up to 20 users. This is more than the 10 req/min limit
    // and should trigger the rate limiter.
    { duration: '30s', target: 20 },
    { duration: '1m', target: 20 },
    { duration: '10s', target: 0 },
  ],
};

export default function () {
  const url = 'http://10.0.0.100/shorten'; // The Load Balancer IP
  const payload = { url: `https://www.test-ratelimit-${Math.random()}.com` };

  const res = http.post(url, payload);

  // Check if the request was successful OR if it was correctly rate-limited
  check(res, {
    'status is 200 (OK)': (r) => r.status === 200,
    'status is 429 (Too Many Requests)': (r) => r.status === 429,
  });

  sleep(1);
}

The stages array configures the test to gradually increase the number of virtual users to 20. Since our rate limit is 10 requests per minute, this load is guaranteed to trigger the limiter.

The check function is the crucial part. It verifies that the server's response code is either 200 (meaning the request was successful) or 429 (meaning our rate limiter correctly blocked the request).

We should see about 10 of our requests go through of the around 1600 requests per minute that we send from the same IP address.

We can also check the logs on our webserver to see all the requests that were sent to it.

And if we look at the Redis cache/database itself, we’ll see all the keys and the TTL at which they expire.

This is how we rate limit applications using a Redis Cache Server.

Here are the complete files used in the project.

    terraform {
    required_providers {
        proxmox = {
        source  = "telmate/proxmox"
        version = "3.0.2-rc04"
        }
    }
    }

    provider "proxmox" {
    pm_api_url          = var.proxmox_api_url
    pm_api_token_id     = var.proxmox_api_token_id
    pm_api_token_secret = var.proxmox_api_token_secret
    pm_tls_insecure     = true
    }

    # --- Shared Provisioner Connection Settings ---
    locals {
        connection_settings = {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
        }
    }

    # --- Database LXC Containers ---
    resource "proxmox_lxc" "postgres_db" {
    hostname     = "postgres-db-lxc"
    target_node  = var.target_node
    ostemplate   = var.lxc_template

    rootfs {
        storage = "local-lvm"
        size = "8G"
    }

    password     = "admin"
    unprivileged = true
    start        = true

    features {
        nesting = true
        # keyctl = true
    }

    network {
        name   = "eth0"
        bridge = "vmbr0"
        ip     = "10.0.0.200/24"
        gw     = "10.0.0.1"
    }

    provisioner "remote-exec" {
        connection {
        type        = "ssh"
        user        = var.ssh_user
        private_key = file(var.ssh_private_key_path)
        host        = split("/", self.network[0].ip)[0]
        }
        inline = [
        "sudo apt-get update",
        "sudo apt-get install -y docker.io docker-compose python3-setuptools",
        "sudo usermod -aG docker ${var.ssh_user}",
        "sudo mkdir -p /opt/postgres",
        "sudo chown ${var.ssh_user}:${var.ssh_user} /opt/postgres"
        ]
    }

    provisioner "file" {
        connection {
        type        = "ssh"
        user        = var.ssh_user
        private_key = file(var.ssh_private_key_path)
        host        = split("/", self.network[0].ip)[0]
        }
        source      = "../databases/pg-docker-compose.yml"
        destination = "/opt/postgres/docker-compose.yml"
    }

    provisioner "remote-exec" {
        inline     = ["cd /opt/postgres && sudo docker-compose up -d"]

        connection {
        type        = "ssh"
        user        = var.ssh_user
        private_key = file(var.ssh_private_key_path)
        host        = split("/", self.network[0].ip)[0]
        }
    }
    }

    resource "proxmox_lxc" "mongo_db" {
        hostname    = "mongo-db-lxc"
        target_node = var.target_node
        ostemplate  = var.lxc_template

        rootfs {
            storage = "local-lvm"
            size = "8G"
        }

        password    = "admin"
        unprivileged = true
        start       = true

        features {
            nesting = true
        # keyctl = true # Somehow this is blocking the apply command
        }

        network {
            name   = "eth0"
            bridge = "vmbr0"
            ip     = "10.0.0.210/24"
            gw     = "10.0.0.1"
        }

        # Provisioners similar to postgres_db
        provisioner "remote-exec" {
            connection {
                type        = "ssh"
                user        = var.ssh_user
                private_key = file(var.ssh_private_key_path)
                host        = split("/", self.network[0].ip)[0]
            }
            inline = [
            "sudo apt-get update",
            "sudo apt-get install -y docker.io docker-compose python3-setuptools",
            "sudo usermod -aG docker ${var.ssh_user}",
            "sudo mkdir -p /opt/mongo",
            "sudo chown ${var.ssh_user}:${var.ssh_user} /opt/mongo"
            ]
        }

        provisioner "file" {
            connection {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
            host        = split("/", self.network[0].ip)[0]
            }
            source      = "../databases/mongo-docker-compose.yml"
            destination = "/opt/mongo/docker-compose.yml"
        }

        provisioner "remote-exec" {
            connection {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
            host        = split("/", self.network[0].ip)[0]
            }
            inline     = ["cd /opt/mongo && docker-compose up -d"]
        }
    }

    # --- Redis Cache for Rate Limiter ---
    resource "proxmox_vm_qemu" "redis_cache" {

        vmid        = 130
        name        = "redis-cache-rate-limiter"
        target_node = "pve"
        agent       = 1
        cpu {
            cores       = 1
        }

        memory      = 1024
        boot        = "order=scsi0" # has to be the same as the OS disk of the template
        clone       = "debian12-cloudinit" # The name of the template
        scsihw      = "virtio-scsi-single"
        vm_state    = "running"
        automatic_reboot = true

        # Cloud-Init configuration
        cicustom   = "vendor=local:snippets/qemu-guest-agent.yml" # /var/lib/vz/snippets/qemu-guest-agent.yml
        ciupgrade  = true
        nameserver = "1.1.1.1 8.8.8.8"
        ipconfig0  = "ip=10.0.0.130/24,gw=10.0.0.1"
        skip_ipv6  = true
        ciuser     = var.ssh_user
        cipassword = var.ssh_password
        sshkeys    = var.ssh_key

        # Most cloud-init images require a serial device for their display
        serial {
            id = 0
        }

        disks {
            scsi {
            scsi0 {
                # We have to specify the disk from our template, else Terraform will think it's not supposed to be there
                disk {
                storage = "local-lvm"
                # The size of the disk should be at least as big as the disk in the template. If it's smaller, the disk will be recreated
                size    = "5G" 
                }
            }
            }
            ide {
            # Some images require a cloud-init disk on the IDE controller, others on the SCSI or SATA controller
            ide1 {
                cloudinit {
                storage = "local-lvm"
                }
            }
            }
        }

        network {
            id = 0
            bridge = "vmbr0"
            model  = "virtio"
        }

        connection {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
            host        = "10.0.0.130"
        }

        # 1. Install Docker and create the final app directory
        provisioner "remote-exec" {
            inline = [
                # Wait for cloud-init to finish before doing anything else
                "echo 'Waiting for cloud-init to finish...'",
                "while [ ! -f /var/lib/cloud/instance/boot-finished ]; do echo 'Still waiting...' && sleep 1; done",
                "echo 'Cloud-init finished.'",

                # Now, safely install packages
                "sudo apt-get update -y",
                "sudo apt-get install -y docker.io docker-compose",
                "sudo mkdir -p /opt/redis",
            ]
        }

        provisioner "file" {
            source      = "../caching/redis-docker-compose.yml"
            destination = "/home/${var.ssh_user}/docker-compose.yml"
        }

        provisioner "remote-exec" {
            inline = [ "sudo mv /home/${var.ssh_user}/docker-compose.yml /opt/redis/docker-compose.yml" ]
        }

        provisioner "remote-exec" {
            inline = [ "cd /opt/redis && sudo docker-compose up -d" ]
        }
    }

    resource "proxmox_vm_qemu" "web-servers" {

        count = 2

        vmid        = count.index + 150
        name        = "web-server-tf-${count.index + 1}"
        target_node = "pve"
        agent       = 1
        cpu {
            cores       = 1
        }
        memory      = 1024
        boot        = "order=scsi0" # has to be the same as the OS disk of the template
        clone       = "debian12-cloudinit" # The name of the template
        scsihw      = "virtio-scsi-single"
        vm_state    = "running"
        automatic_reboot = true

        # Cloud-Init configuration
        cicustom   = "vendor=local:snippets/qemu-guest-agent.yml" # /var/lib/vz/snippets/qemu-guest-agent.yml
        ciupgrade  = true
        nameserver = "1.1.1.1 8.8.8.8"
        ipconfig0  = "ip=10.0.0.${111 + count.index}/24,gw=10.0.0.1"
        skip_ipv6  = true
        ciuser     = var.ssh_user
        cipassword = var.ssh_password
        sshkeys    = var.ssh_key

        # Most cloud-init images require a serial device for their display
        serial {
            id = 0
        }

        disks {
            scsi {
            scsi0 {
                # We have to specify the disk from our template, else Terraform will think it's not supposed to be there
                disk {
                storage = "local-lvm"
                # The size of the disk should be at least as big as the disk in the template. If it's smaller, the disk will be recreated
                size    = "5G" 
                }
            }
            }
            ide {
            # Some images require a cloud-init disk on the IDE controller, others on the SCSI or SATA controller
            ide1 {
                cloudinit {
                storage = "local-lvm"
                }
            }
            }
        }

        network {
            id = 0
            bridge = "vmbr0"
            model  = "virtio"
        }

        connection {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
            host        = "10.0.0.${111 + count.index}"
        }

        # 1. Install Docker and create the final app directory
        provisioner "remote-exec" {
            inline = [
                # Wait for cloud-init to finish before doing anything else
                "echo 'Waiting for cloud-init to finish...'",
                "while [ ! -f /var/lib/cloud/instance/boot-finished ]; do echo 'Still waiting...' && sleep 1; done",
                "echo 'Cloud-init finished.'",

                # Now, safely install packages
                "sudo apt-get update -y",
                "sudo apt-get install -y docker.io",
                "sudo mkdir -p /opt/app",
            ]
        }

        # 2. Upload ONLY the necessary files to the user's home directory
        provisioner "file" {
            source      = "../web-servers/app.py"
            destination = "/home/${var.ssh_user}/app.py"
        }
        provisioner "file" {
            source      = "../web-servers/Dockerfile"
            destination = "/home/${var.ssh_user}/Dockerfile"
        }
        provisioner "file" {
            source      = "../web-servers/requirements.txt"
            destination = "/home/${var.ssh_user}/requirements.txt"
        }

        # 4. Move files from the home directory, build the image, and run the container
        provisioner "remote-exec" {
            inline = [
                # Move each file individually to be compatible with all shells
                "sudo mv /home/${var.ssh_user}/app.py /opt/app/",
                "sudo mv /home/${var.ssh_user}/Dockerfile /opt/app/",
                "sudo mv /home/${var.ssh_user}/requirements.txt /opt/app/",

                # Build the Docker image
                "sudo docker build -t my-python-app /opt/app",

                # Stop and remove any old containers to prevent conflicts
                "sudo docker stop $(sudo docker ps -q --filter ancestor=my-python-app) 2>/dev/null || true",
                "sudo docker rm $(sudo docker ps -aq --filter ancestor=my-python-app) 2>/dev/null || true",

                # Run the new container
                "sudo docker run -d --restart always -p 80:5000 my-python-app"
            ]
        }

        # In your proxmox_vm_qemu "web_servers" resource
        depends_on = [
            proxmox_lxc.postgres_db,
            proxmox_vm_qemu.redis_cache
        ]
    }

    # --- Load Balancer VM ---
    resource "proxmox_vm_qemu" "load_balancer" {
        name        = "lb-1"
        target_node = var.target_node
        clone       = var.vm_template
        agent       = 1
        cpu {
            cores       = 1
        }
        memory      = 512
        boot        = "order=scsi0" # has to be the same as the OS disk of the template
        scsihw      = "virtio-scsi-single"
        vm_state    = "running"
        automatic_reboot = true

        # --- Add these lines for Cloud Init Drive ---
                # --- Add these lines for Cloud Init Drive ---
        cicustom   = "vendor=local:snippets/qemu-guest-agent.yml" # /var/lib/vz/snippets/qemu-guest-agent.yml
        ciupgrade  = true
        nameserver = "1.1.1.1 8.8.8.8"
        ipconfig0  = "ip=10.0.0.100/24,gw=10.0.0.1"
        skip_ipv6  = true
        ciuser     = var.ssh_user
        cipassword = var.ssh_password
        sshkeys    = var.ssh_key

        # Most cloud-init images require a serial device for their display
        serial {
            id = 0
        }

        disks {
            scsi {
            scsi0 {
                # We have to specify the disk from our template, else Terraform will think it's not supposed to be there
                disk {
                storage = "local-lvm"
                # The size of the disk should be at least as big as the disk in the template. If it's smaller, the disk will be recreated
                size    = "5G" 
                }
            }
            }
            ide {
            # Some images require a cloud-init disk on the IDE controller, others on the SCSI or SATA controller
            ide1 {
                cloudinit {
                storage = "local-lvm"
                }
            }
            }
        }

        network {
            id = 0
            bridge = "vmbr0"
            model  = "virtio"
        }

        connection {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
            host        = "10.0.0.100"
        }

        # Step 1: Install Nginx
        provisioner "remote-exec" {
            inline = [
                # Wait for cloud-init to finish before doing anything else
                "echo 'Waiting for cloud-init to finish...'",
                "while [ ! -f /var/lib/cloud/instance/boot-finished ]; do echo 'Still waiting...' && sleep 1; done",
                "echo 'Cloud-init finished.'",

                # Now, safely install packages
                "sudo apt-get update -y",
                "sudo apt-get install -y nginx"
            ]
        }

        # Step 2: Upload config to a temporary location
        provisioner "file" {
            source      = "../web-servers/nginx.conf"
            destination = "/tmp/nginx.conf" # Use /tmp instead
        }

        # Step 3: Use sudo to move the file to its final destination and reload nginx
        provisioner "remote-exec" {
            inline = [
                "sudo mv /tmp/nginx.conf /etc/nginx/sites-available/default",
                "sudo systemctl reload nginx"
            ]
        }
    }


    # --- Load Tester VM ---
    resource "proxmox_vm_qemu" "load_tester" {
        name        = "load-tester-vm"
        target_node = var.target_node
        clone       = var.vm_template
        agent       = 1
        cpu {
            cores       = 1
        }
        memory      = 1024
        boot        = "order=scsi0" # has to be the same as the OS disk of the template
        scsihw      = "virtio-scsi-single"
        vm_state    = "running"
        automatic_reboot = true

        # --- Add these lines for Cloud Init Drive ---
        cicustom   = "vendor=local:snippets/qemu-guest-agent.yml" # /var/lib/vz/snippets/qemu-guest-agent.yml
        ciupgrade  = true
        nameserver = "1.1.1.1 8.8.8.8"
        ipconfig0  = "ip=10.0.0.160/24,gw=10.0.0.1"
        skip_ipv6  = true
        ciuser     = var.ssh_user
        cipassword = var.ssh_password
        sshkeys    = var.ssh_key

        # Most cloud-init images require a serial device for their display
        serial {
            id = 0
        }

        disks {
            scsi {
                scsi0 {
                    # We have to specify the disk from our template, else Terraform will think it's not supposed to be there
                    disk {
                    storage = "local-lvm"
                    # The size of the disk should be at least as big as the disk in the template. If it's smaller, the disk will be recreated
                    size    = "5G" 
                    }
                }
            }

            ide {
            # Some images require a cloud-init disk on the IDE controller, others on the SCSI or SATA controller
                ide1 {
                    cloudinit {
                    storage = "local-lvm"
                    }
                }
            }
        }

        network {
            id = 0
            bridge = "vmbr0"
            model  = "virtio"
        }

        provisioner "remote-exec" {
            connection {
                type        = "ssh"
                user        = var.ssh_user
                private_key = file(var.ssh_private_key_path)
                host        = "10.0.0.160"
            }
            inline = [
                # Wait for cloud-init to finish
                "echo 'Waiting for cloud-init to finish...'",
                "while [ ! -f /var/lib/cloud/instance/boot-finished ]; do echo 'Still waiting...' && sleep 1; done",
                "echo 'Cloud-init finished.'",

                # Install prerequisites
                "sudo apt-get update -y",
                "sudo apt-get install -y gnupg curl",

                # Add the k6 repository and key
                "curl -sL https://dl.k6.io/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/k6-archive-keyring.gpg",
                "echo 'deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main' | sudo tee /etc/apt/sources.list.d/k6.list",

                # Install k6
                "sudo apt-get update",
                "sudo apt-get install -y k6"
            ]
        }

        provisioner "file" {
            connection {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
            host        = "10.0.0.160"
            }
            source      = "../load-testing/script.js"
            destination = "/home/${var.ssh_user}/script.js"
        }

        provisioner "file" {
            connection {
            type        = "ssh"
            user        = var.ssh_user
            private_key = file(var.ssh_private_key_path)
            host        = "10.0.0.160"
            }
            source      = "../load-testing/rate-test.js"
            destination = "/home/${var.ssh_user}/rate-test.js"
        }

    }

Conclusion

You've now seen how to build a complete, scalable, and resilient system that includes a crucial component for modern web applications: a distributed rate limiter.

We've covered the entire stack:

• Infrastructure as Code with Terraform to define our virtual machines. (check out my repo here for all the code and any updates I make).

• A centralized, high-speed cache with Redis to store our rate limiting data.

• An efficient Sliding Window Log algorithm implemented in Python with Flask.

• Containerization with Docker for consistent deployment.

• Load balancing with Nginx to distribute traffic.

• Load testing with k6 to validate our implementation.

If you’d like to learn more of the concepts that are used when building large scale systems please follow me at Sravan Karuturi.

For many app developers, including me, writing the networking layer of an application is a familiar and tedious process. You write and test your first call and after that, it involves a repetitive cycle of tasks.

This is how it would look in the case of Swift:

1. You create a URLSession Instance.

2. You create a URLRequest Object.

3. You create the @Codable models to match the expected input and output from the server.

You do the above steps for each API endpoint you have on your backend that your app uses. Not only is this process time-consuming and not challenging for developers, it’s also error prone.

In the above case, if there was a minor change in the backend API – perhaps a renamed field or a new property – this would lead to the app potentially breaking. But you wouldn’t know this until you shipped it to QA or in a worse case, your consumer. This is where the OpenAPI Specification emerges as a modern, robust solution.

In this tutorial, you’ll learn what OpenAPI is and how it can help make your development process better. After that, we’ll implement OpenAPI by creating a small SwiftUI app and using OpenAPI methodologies to interface with the JSONPlaceholder API. Let’s get started.

Who is This Guide For?

This guide is intended both for new developers looking for best practices and for experienced developers looking to implement or learn more about the OpenAPI Specification. Let’s get into it.

Table of Contents

• What is OpenAPI and Why Should You Care?

  • Benefits for Swift (iOS) Developers

• A Practical Guide to Implementing This Solution

  • Step 1: Create a good openapi.yaml file (the specification)

  • Step 2: Set up your project

  • Step 3: Write a wrapper

  • Step 4: Call the wrapper and display the data

• Potential Pitfalls

  • Verbose or ugly generated code

  • Large Specs and Performance Issues

  • Unsupported Spec Features

• Conclusion: Embrace Spec-Driven Development

What is OpenAPI and Why Should You Care?

At its core, the OpenAPI Specification provides a standard, language-agnostic interface for describing RESTful APIs. This specification, once populated, allows both humans and computers to discover and understand the capabilities of a service without needing to access the source code or the network requests.

The power of OpenAPI is that it acts as a formal contract between different parts of the system. This contract helps both frontend and backend programmers by removing ambiguity during design process. This also has added benefit of using code generators to generate boiler-plate code both on backend and on the client ( which we will also discuss today ).

Traditionally when you want to create a new API in a team, either the PM, the frontend engineer, or the backend engineer takes it upon themselves to request it. Then the backend team builds it and documents it. This in turn is used by the front end team to use the API.

Some Requester → Backend Team → Documentation → Frontend Team

If you’re using OpenAPI, when someone makes a request for a new API, it is formalized into a specification after deliberations with both the frontend and the backend team. This then serves as the source of truth and is used to generate the backend and the frontend code without as much interdependence.

Some Requester → All Teams → Specification → All Teams.

This not only streamlines the process of adding new APIs, but provides a definitive source of truth for each endpoint. This also makes it so that frontend engineers and backend engineers are not misaligned about a provided parameter in the result being an Int or a String and so on. It’s all in the Spec.

Benefits for Swift (iOS) Developers

Adopting OpenAPI and swift-openapi-generator brings a host of tangible benefits to the Swift/App development process. It transforms how applications interact with web services in a few key ways.

Reduced Development Time and Cost

The most immediate improvement you will see is the significant reduction in boilerplate code you have to write. The generator automates the creation of what is called boilerplate code or ceremonial code. This is the repetitive logic for network requests, response handling, and data model definitions.

By delegating this work, developers can work on the core features of the application which leads to faster and more interesting development cycles.

Compile Time Type Safety

This has been a major improvement for me personally. Instead of relying on the “strongly” typed keys for JSON parsing, we now work with strongly typed models. The generator creates native Swift struct and enum types directly from the schemas defined in the OpenAPI document. This brings the power of a strongly-typed system to the networking and parsing layer.

For example, if the return value of an API is made optional, instead of crashing at runtime, we will fail to compile at build time. This forces us to address this issue right away.

Improved Collaboration and Interoperability

This makes sure that all the developers are on the same page with regard to a given endpoint. And since this specification is language agnostic, it will serve as a universal language for all teams involved in the project – mobile, web and backend.

Other Tooling

Once you have a specification, you can use that to power a wide variety of tools. You can generate interactive documentation, create mock servers for frontend development, and run automated tests.

Alright hopefully you’re sold – so now how do you implement this into your project?

A Practical Guide to Implementing This Solution

We’ll now take a look at a practical example so you can understand how you can implement this in a project. This involves:

• Creating an openapi.yaml file to describe the API specification.

• Configuring and integrating swift-openapi-generator into a SwiftUI application.

• Prototyping an app that fetches and displays a list of posts from the https://jsonplaceholder.typicode.com/

To follow along, you will need Xcode installed and a basic understanding of Swift programming and SwiftUI for App development.

Step 1: Create a good openapi.yaml file (the specification)

The quality of a specification is really important because it directly determines the quality of the code produced by swift-openapi-generator. If you don’t have a good specification, you might run into several issues that developers often complain about, like confusing and long method names.

For example, it might generate something like get_all_my_meal_recipes_hyphen_detailed. This might happen because the generator is forced to create a new name based on the API path if the identifier is not provided in the spec. So, instead of dealing with these issues one after the other, we will create a good clear specification to start with.

Since we’re using the jsonplaceholder as our backend server, we are limited by what tweaks we can make – but it is a fantastic project that lets us mimic a backend server.

In general, an OpenAPI.yaml file contains:

1. OpenAPI Info and servers – This will provide the metadata about the API like the OpenAPI version, which server to point to for calls, and so on.

2. Paths – This will provide the available endpoints. In our case, it can contain /posts as one of them. We also will have to mention the kind of endpoint (get, post, put, and so on)

3. OperationID – This field instructs the generator to create a clear method with this name.

4. Responses – This defines the possible outcomes of an API call. We will specify the structure of a successful 200 OK response or any other errors here.

5. Components / Schemas – This defines all the reusable components and data models. If we have a Post schema definer here, the generator will use this to create a Post struct in Swift to match this.

Keeping in mind all these elements, I compiled a yaml file for us to use for this tutorial:

# openapi.yaml
openapi: "3.0.3"
info:
  title: "JSONPlaceholder API"
  version: "1.0.0"
servers:
  - url: "https://jsonplaceholder.typicode.com"
paths:
  /posts:
    get:
      summary: "Get all posts"
      operationId: "getPosts"
      responses:
        "200":
          description: "A list of posts"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Post"
components:
  schemas:
    Post:
      type: object
      required:
        - userId
        - id
        - title
        - body
      properties:
        userId:
          type: integer
        id:
          type: integer
        title:
          type: string
        body:
          type: string

The first line here, openapi: “3.0.3”, just tells the generators and parsers that we are using version 3.0.3.

Next, we have some more metadata – the name and version of the API. We also have the server we are calling with our APIs.

After defining this metadata, we now define our endpoints. For the sake of this example, let’s assume that we only have one endpoint to call to get posts. We represent this by saying /posts under paths. We then specify which kind it is by specifying get:.

We give a short description of what it does in the summary and then specify an operationId which is what we this function will be called in our generated code. We also specify exactly what structure the response will have, that is, a JSON of an array of Posts.

We then list any components we have across our APIs like the Post. Note that we are using the Post schema in the return response structure before we define it further down. The schemas in components will determine the Model structs we will generate using this yaml file.

Step 2: Set up your project

Create a new SwiftUI project. For the purpose of this tutorial, we’ll use an iOS app – but you can do this with any app. Select Swift as the language and SwiftUI for the interface.

Add the openapi.yaml file we just created to this project. (You can also create this file in Xcode and copy, paste from the script above.)

Now, add the following swift packages to the project. (Note: Please read the entire section about adding packages before you proceed.)

1. Swift OpenAPI Generator – https://github.com/apple/swift-openapi-generator – The Core Generator Plugin.

   

   

2. Swift OpenAPI Runtime – https://github.com/apple/swift-openapi-runtime – This contains the common types and protocols used by the code generated by the generator plugin.

   

3. Swift OpenAPI URLSession – https://github.com/apple/swift-openapi-urlsession – This is a transport layer that allows the generated code to use the Apple URLSession to make network requests.

   

One major caveat to note here when adding these packages is that The Swift OpenAPI Generator should not be added to your project target. This is because we’re only using this to generate the code, but we’re not using it in the app.

If you get this error: swift-openapi-generator/Sources/_OpenAPIGeneratorCore/PlatformChecks.swift:21:5 _OpenAPIGeneratorCore is only to be used by swift-openapi-generator itself—your target should not link this library or the command line tool directly. – then you made this mistake.

The easiest way to fix this is removing the package and adding it again. Or you can go to Project → Target → Build Phases → Link Binary with Libraries → Remove Swift OpenAPI Generator.

Now that we added these generator and runtime plugins, we need to give the generator some instructions on what to generate. You can do this with an openapi-generator-config.yaml file. For our project, use the following file. It’s really simple:

generate:
  - types
  - client

This tells our generator to generate the types – the swift structs, enums, and so on from the schema section of the file, and the client – the main class which interacts with the networking logic.

Save this into an openapi-generator-config.yaml file as shown.

And finally, we want the generator to run whenever we want to build this application/target. We can specify this in the Build Phases tab of the target. Under the “ Target → Build Phases → Run Build Tool Plug-ins” , add the OpenAPIGenerator Plugin.

The first time the project is built after setting this, Xcode will display a security dialog. This will let us “Trust and Enable” for this plugin. It’s a one time confirmation that gives this plugin the permission required to run during the build process.

As soon as you build the second time after giving these permissions, you will generate the files. You might not see any changes in the Xcode window itself. But if you’re curious to see the result, go to this folder.

DerivedData → <ProjectName>*identifier → Build → intermediates.noindex → BuildToolPluginIntermediates → <TargetName>.output → <TargetName> → OpenAPIGenerator → GeneratedSources

More on derived data folder here: https://gayeugur.medium.com/derived-data-2e9468c6da9b if you’re curious.

Keep in mind that this location might vary based on Xcode version, OpenAPI version, and your project settings. But you don’t need to worry about the file location.

You will see three files called Client.swift, Types.swift, and Server.swift.

These are the files that the our generator created and populated with the types and functions we need.

In the next section, we discuss how to use these files to make calls to the server.

Step 3: Write a wrapper

While it’s certainly possible to make the calls to server using just the generated code (Client) type throughout our application, a more maintainable approach is to use a wrapper around these types. This will provide a stable, clean interface for the rest our our app to use, and it decouples feature code from the generated code.

I can hear you thinking: “Wait a second. Isn’t the entire purpose of generating this code to avoid this boilerplate abstraction?”

While it adds some abstraction on top of the generated code, it’s valuable to have this for number of reasons. Here are but a few of them:

1. Better naming. The generated Post struct right now will be called Components.Schemas.Post.

2. If you ever want to move away from the generator, an abstraction is really helpful.

3. If you want to Mock this server call, you can do this via the abstraction.

4. UI Optimization. You might want to flatten the structure of a model to reduce the number of computed variables in there, and so on.

So, we want to wrap this around a file called WebService.swift:

// WebService.swift
import Foundation
import OpenAPIURLSession

// A clean, app-specific Post model.
// This decouples views from the generated types.
struct AppPost: Identifiable, Codable {
    let id: Int
    let title: String
    let body: String
}

class WebService {
    private let client: Client

    init() {
        // The server URL and transport are from the generated code.
        // `Servers.Server1.url()` corresponds to the first URL in the `servers` array of the spec.
        self.client = Client(
            serverURL: try! Servers.Server1.url(),
            transport: URLSessionTransport()
        )
    }

    func getPosts() async throws -> [AppPost] {
        // Call the generated method, which was named using `operationId`.
        let response = try await client.getPosts(.init())

        // The generated response is a type-safe enum covering all documented status codes.
        switch response {
        case.ok(let okResponse):
            // The body is also a type-safe enum for different content types.
            switch okResponse.body {
            case.json(let posts):
                // Map the generated `Components.Schemas.Post` to our clean `AppPost` model.
                return posts.map { post in
                    AppPost(id: post.id, title: post.title, body: post.body)
                }
            }
        // The generator forces the handling of other documented responses.
        // Our simple spec only has a 200, so any other response is undocumented.
        case.undocumented(statusCode: let statusCode, _):
            throw URLError(.badServerResponse, userInfo: ["statusCode": statusCode])
        }
    }
}

Let’s go through this file to understand what we’re doing.

First, we import OpenAPIUrlSession along with Foundation. This allows us to call the server, get a response and parse that response.

Next, we define the new AppPost struct. This is meant to be the representation of a Post in the App. In the generated Types.Swift file, we have the generated Post structure. This is defined as:

/// - Remark: Generated from `#/components/schemas/Post`.
        internal struct Post: Codable, Hashable, Sendable {
            /// - Remark: Generated from `#/components/schemas/Post/userId`.
            internal var userId: Swift.Int
            /// - Remark: Generated from `#/components/schemas/Post/id`.
            internal var id: Swift.Int
            /// - Remark: Generated from `#/components/schemas/Post/title`.
            internal var title: Swift.String
            /// - Remark: Generated from `#/components/schemas/Post/body`.
            internal var body: Swift.String
            /// Creates a new `Post`.
            ///
            /// - Parameters:
            ///   - userId:
            ///   - id:
            ///   - title:
            ///   - body:
            internal init(
                userId: Swift.Int,
                id: Swift.Int,
                title: Swift.String,
                body: Swift.String
            ) {
                self.userId = userId
                self.id = id
                self.title = title
                self.body = body
            }
            internal enum CodingKeys: String, CodingKey {
                case userId
                case id
                case title
                case body
            }
        }

As you can see, our AppPost struct is different from this generated type. We omit the userId since we do not care about it (at least for now).

Back to the WebService class, we see a client attribute. This is a generated type variable that will let us interact with the servers. In the initializer of the WebService class, we create a new Client using the first server URL we specified in the schema and use the URLSessionTransport object for making these calls.

We then define our methods. In this case, our getPosts() function which returns [AppPost] array.

let response = try await client.getPosts(.init()) will call the function getPosts() on the Client object. The Client.getPosts() function here takes in an input struct called Operations.getPosts.Input which is initialized by the .init() passed here.

This generated response is a type-safe enum covering all documented codes. (Currently only 200 in our yaml file). So, we use a simple switch to look at both these cases and further use more switch statements to get the proper response. You can see how much easier this is than to parse the response manually.

Once we get the Components.Schemas.Post response, we map and convert it into [AppPost] array and return it.

Now, let’s use this wrapper to display data in our app.

Step 4: Call the wrapper and display the data

We’re at the final step now. We’ll use the wrapper we created to display the fetched posts. We’ll also use a state variable to store our AppPost array in our ContentView view. We’ll then call getPosts() when the view is first displayed to the user.

// ContentView.swift
import SwiftUI

struct ContentView: View {
    @State private var posts: [AppPost] = []
    @State private var errorMessage: String?

    private let webService = WebService()

    var body: some View {
        NavigationStack {
            List(posts) { post in
                VStack(alignment:.leading, spacing: 8) {
                    Text(post.title)
                       .font(.headline)
                    Text(post.body)
                       .font(.subheadline)
                       .foregroundColor(.secondary)
                }
               .padding(.vertical, 4)
            }
           .navigationTitle("Posts")
           .task {
                await loadPosts()
            }
           .overlay {
                if let errorMessage {
                    ContentUnavailableView("Error", systemImage: "xmark.octagon", description: Text(errorMessage))
                } else if posts.isEmpty {
                    ProgressView()
                }
            }
        }
    }

    func loadPosts() async {
        self.errorMessage = nil
        do {
            self.posts = try await webService.getPosts()
        } catch {
            self.errorMessage = error.localizedDescription
        }
    }
}

#Preview {
    ContentView()
}

You can see the dummy posts in the Preview. As you can see, all we had to do was call the webService.getPosts() to populate the variable.

You might be thinking that this is a lot of setup for a simple struct like Post for which we had to create a wrapper called AppPost anyway. But if you had ten types like this and twenty endpoints to call? You wouldn’t have to deal with a lot of repetitive, error-prone code.

Potential Pitfalls

Unfortunately, no process is perfect. You might still face a lot of issues with generated code and this method. I’ve listed some of them here and how to deal with them.

Verbose or ugly generated code

If you have very verbose or ugly generated code, the problem is almost always the missing operationId for an API path. If you don’t specify one, the generator must create a name from the path and the HTTP method with results in long unwieldy names. Adding a clear operationId will mitigate this issue.

Large Specs and Performance Issues

If you have a very large Spec file, generating a client for this entire specification can significantly increase the compile time. It can also result in absolutely massive Types.swift and Client.swift files.

There is a filter option in the openapi-generator-config.yaml file that will allow the generator to include only parts of the spec that are relevant to the application to improve build times and so on. But if you want everything in an API that has hundreds of endpoints, the only way to reduce compile times is to avoid regenerating this every time and decouple this step from the regular build process.

Unsupported Spec Features

While the swift package, swift-openapi-generator, is robust, it does not support all the features included in the specification. I had issues with some features of the newer spec version ( 3.1.1 and had to downgrade to 3.0.3 to make it work well ).

There are also known issues like lack of support for certain types of recursive schemas. Sometimes, the generator errors out and fails and some other times, it generates incomplete types – which can result in a few hours of debugging (I speak from experience).

In any case, knowing the limits of this generator can be helpful in avoiding issues it might cause. Also keep in mind that it is always getting better thanks to its open source nature.

Conclusion: Embrace Spec-Driven Development

In this guide, you navigated the journey of adopting swift-openapi-generator – from understanding the power of API contracts to building a functional SwiftUI app. You also learned about the real life challenges of this process. While there is an initial learning curve, the benefits of this approach are profound.

The core tenet of this approach is to foster more disciplined and more robust method for building applications. By making the OpenAPI document the single source of truth, you make sure that both the frontend and backend are perfectly in sync in perpetuity.

Using this approach also results in more type-safe, maintainable code. The result is less time spent on writing boilerplate and debugging random integration errors and more time spent creating the app itself.

For developers ready to explore further, please checkout the official swift-openapi-generator repository on Github here: https://github.com/apple/swift-openapi-generator.

You can follow me on GitHub and Hashnode for my other posts and projects.

Throughout this handbook, you will learn how to:

• Correctly establish and manage an app's unique identity.

• Understand the roles of different Apple developer certificates and how to create and manage them.

• Differentiate between various types of provisioning profiles and know when to use each one.

This guide is geared towards new developers who want to learn how the code signing process works, but it should also be useful experienced developers who want or need to refresh their memory.

Prerequisites

While there are no hard prerequisites to understanding the certificates, bundles, and provisioning profiles for distributing on Apple platforms, it helps to have an Apple developer account to follow along.

Table of Contents

• App IDs, Bundle IDs – Your App’s Identity

• Understanding Distribution: A Deep Dive into Certificates

• Bridge between everything: Provisioning Profiles

• Device management – Development and Ad Hoc Builds

• Possibilities: Enabling Capabilities and Services

• Conclusion

App IDs, Bundle IDs — Your App’s Identity

The Bundle ID and the corresponding App ID registered with Apple form the basis of an application’s identity. Establishing these correctly from the beginning is very important, as errors or misconfigurations here can lead to significant complications down the line, particularly once you’ve submitted your app to App Store Connect.

Understanding CFBundleIdentifier (Bundle ID)

What is the “Bundle ID”?

Think of the Bundle ID as a unique name or a fingerprint for your app. The CFBundleIdentifier, more commonly known as the Bundle ID, is a string that uniquely identifies your application.

This identifier is not just a name – it serves multiple crucial purposes.

• The operating system relies on it to apply specific preferences and settings to an app.

• This is used to launch the application from other apps etc.

• It plays an essential role in the validation of an app's code signature, ensuring the app's integrity and authenticity.

• The Bundle ID defined in an app's Info.plist file must exactly match the Bundle ID registered for the app in App Store Connect for successful submission and distribution.

The Bundle ID string must adhere to specific character limitations: it can only contain alphanumeric characters A-Z, a-z, 0-9, hyphens -, and periods .. It's important to note that Bundle IDs are treated as case-insensitive by the system.

How to Choose and Format Your Bundle ID (Reverse-DNS and Best Practices)

Apple highly recommends, and it is standard practice, to use a reverse-DNS (Domain Name System) format for Bundle IDs.

A common example would be com.yourcompanyname.appname. This convention leverages the global uniqueness of domain names to help ensure the global uniqueness of Bundle IDs.

If an organization uses its unique domain name (for example, sravan.gg becomes gg.sravan ) as the prefix, and the app name is unique within that organization, the resulting Bundle ID (for example, gg.sravan.mycoolapp ) is highly likely to be unique worldwide.

Sidenote: While Xcode won’t stop you from creating something like com.google.mapping or something like that even if you don’t work at Google, this will most likely get rejected when it goes through the AppStore review process. This is because this implies ownership of that domain. So, while it’s technically possible when starting out, you shouldn’t use domains that don’t belong to you.

The fundamental nature of the Bundle ID as a unique, system-wide identifier – coupled with its immutability after an app is first uploaded to App Store Connect – means that you should treat its selection with the same seriousness as choosing a permanent, unchangeable identifier for a critical entity. A mistake in the Bundle ID after this point can necessitate creating an entirely new app listing on the App Store.

App IDs in the Apple Developer Portal: Explicit vs. Wildcard

Which One Do You Need?

In the Apple Developer Portal, developers register an "App ID." This App ID is a record that links one or more applications from a single development team to specific app services (capabilities) and is used in provisioning profiles. We’ll learn more about this in the following sections.

There are two main types of App IDs:

• Explicit App ID: This type is used for a single application. The Bundle ID specified within an explicit App ID must be an exact match for the CFBundleIdentifier in the app's Info.plist file (for example, com.mycompany.myapp). Explicit App IDs are required for apps that use many of Apple's specific services and capabilities, such as In-App Purchases (which are enabled by default for explicit App IDs), Push Notifications, iCloud, HealthKit, and Sign in with Apple.

• Wildcard App ID: This type can be used for a set of applications that share a common Bundle ID prefix. It contains an asterisk (*) as the last part of its Bundle ID string (for example, com.mycompany.*). This wildcard App ID would match any app whose Bundle ID starts with com.mycompany., such as com.mycompany.app or com.mycompany.utility. But you can’t use wildcard App IDs if the app requires services or capabilities that mandate an explicit App ID.

The choice between an explicit and a wildcard App ID has significant implications. The App ID acts as a central registration point, and the capabilities are "enabled" for this registration – more on capabilities later in this handbook.

You can think of an explicit App ID as a specific key designed to unlock extra "keyholes" (capabilities). A wildcard App ID, being more generic, might not fit these extra keyholes. If you choose a wildcard App ID initially for convenience, but you need a feature requiring an explicit App ID (like Push Notifications) later, you’ll be forced to create a new explicit App ID and reconfigure associated settings and provisioning profiles.

So, make sure you carefully consider your current and future app features when selecting an App ID type. The following table provides a quick comparison**.**

My personal recommendation is always go with explicit App Ids unless you need the flexibility of wildcard app ids.

Step-by-Step: How to Register Your App ID in the Apple Developer Portal

To register an App ID, an you’ll need an Apple Developer Program membership. Also, the actions must be performed by someone with an Account Holder or Admin role.

The process is as follows:

1. Sign in to the Apple Developer Portal and navigate to "Certificates, Identifiers & Profiles," then select "Identifiers" from the sidebar.

2. Click the “Add button (+)” to create a new identifier.

   

3. Select "App IDs" from the list of options and click "Continue."

   

4. Make sure that the "App" type is selected (it usually is by default) and click "Continue."

   

5. Enter a "Description" for the App ID. This is for your reference within the portal (for example, "My very cool App ID").

   

6. Choose the "App ID Type": "Explicit" or "Wildcard."

7. For an "Explicit App ID," enter the exact Bundle ID that will be used in your Xcode project (for example, com.yourcompany.yourapp). For a "Wildcard App ID," enter a Bundle ID suffix ending with an asterisk (for example, com.yourcompany.*).

8. Scroll down to the "Capabilities" section and select the checkboxes for any app services your app will use. Some capabilities might require further configuration at this stage or later. (Again, we’ll cover app capabilities in more detail later on).

9. Click "Continue," review all the details carefully, and then click "Register" to finalize the App ID creation.

   

How to Manage Your Bundle ID: Xcode, App Store Connect, and the Point of No Return

The Bundle ID specified in an Xcode project is critical. To set it:

1. In the Xcode project navigator, select the target for your app.

2. Open the "Signing & Capabilities" tab.

3. Expand the "Signing" section.

4. In the "Bundle Identifier" text field, enter the Bundle ID. This identifier must precisely match the Bundle ID associated with an explicit App ID registered in the Developer Portal, or conform to the pattern of a wildcard App ID if applicable.

It's important to understand the difference between the "Bundle ID" (or CFBundleIdentifier) in the Xcode project and the "App ID" registered in the Developer Portal. The "App ID" in the developer portal is an entity that contains a “Bundle ID” string (either explicit or wildcard). The string in your Xcode project's "Bundle Identifier" field must match this contained string.

When preparing for distribution via TestFlight or the App Store, you’ll need to create an app record in App Store Connect. The Bundle ID you enter during this app record creation must exactly match the Bundle ID in the Xcode project.

A Critical Warning: Immutability After First Upload

This is a point of no return: Once you upload a build of an app to App Store Connect, the Bundle ID for that app record cannot be changed.

In addition, after an upload, you can’t delete the associated explicit App ID registered in the Developer Portal. This immutability highlights the need for careful planning and verification of the Bundle ID before any uploads occur.

If you prefer programmatic management or automation, the App Store Connect API provides resources for managing Bundle IDs. You can read more on that here.

Understanding Distribution: A Deep Dive into Certificates

What are Certificates?

Certificates are digital credentials that verify a developer's identity – that is, you – to Apple and, by extension, to the app users.

They are fundamental to Apple's code signing process, which is mandatory for all apps to ensure they originate from a known source and have not been tampered with since being signed.

What is Code Signing: Ensuring Trust and Integrity

Code signing is you as a developer signing the app with your signature. It is the process of attaching a digital signature to an app's code. This signature assures users of two key things:

1. Authenticity: The app was created by an identified Apple developer (an individual or a team).

2. Integrity: The app's code has not been altered or corrupted since it was signed by the developer.

The process involves using a private key, securely held by the developer (you), to create the signature. The corresponding public key, embedded within the developer's certificate (issued by Apple), is used by the system to verify this signature.

This system of identity verification and integrity checking is crucial. The developer's certificate, issued by Apple as a Certificate Authority (CA), vouches for their identity. The code signing process, using hashing and encryption, ensures that any modification to the code after signing would invalidate the signature.

For app developers, benefits of code signing include removing warnings on macOS for apps distributed outside the Mac App Store, providing a smoother user experience. It is a mandatory requirement for listing applications on any of Apple's App Stores. It also enhances security of the app as it acts as a deterrent against malicious tampering.

Types of Certificates: Development, Distribution, and Developer ID

Apple provides different types of certificates for various stages of development and methods of distribution. Each of them has a distinct role to play throughout the app development process.

1. Development Certificates (for example, "Apple Development"):

• Purpose: Used to sign apps during the development phase, allowing them to be installed and run on a limited number of registered test devices and simulators for debugging and testing.

• Identifies: Typically identifies an individual developer through their developer ID.

• Used with: Development provisioning profiles – more on this later.

2. Distribution Certificates (for example, "Apple Distribution"):

• Purpose: Used to sign apps intended for distribution, either through Ad Hoc methods (to a limited set of registered testers) or for submission to the App Store.

• Identifies: The development team via the team identifier.

• Use Cases:

  1. App Store: For signing the final version of an app that will be uploaded to App Store Connect for TestFlight beta testing or release on the App Store (iOS, macOS, tvOS, watchOS). These are used with App Store provisioning profiles – more on this later.

  2. Ad Hoc: For signing apps that will be distributed to a limited number of registered test devices outside of the App Store or TestFlight. These are used with Ad Hoc provisioning profile. More on this later.

3. Developer ID Certificates (for Mac apps distributed outside the Mac App Store):

• Purpose: Specifically for macOS developers who wish to distribute their applications directly to users (for example, from their own website) rather than through the Mac App Store. Gatekeeper on macOS recognizes apps signed with a Developer ID certificate, assuring users that the app is from a known developer and has not been tampered with.

• Types:

  1. Developer ID Application: Used to sign the Mac application bundle (.app) itself.

  2. Developer ID Installer: Used to sign a Mac Installer Package (.pkg) that contains the signed application.

  3. Limit: Developers can create up to five Developer ID Application certificates and up to five Developer ID Installer certificates.

The following table summarizes these certificate types:

How to Create an Apple Certificate – An Overview

Here’s a general outline of how you create an Apple Certificate:

• Generate a Certificate Signing Request (CSR) on your Mac. (Yes you need a mac.)

• You upload this CSR in AppStoreConnect as a part of creating the certificate.

• Download the certificate from AppStoreConnect once it’s issued.

• Install the certificate into your Keychain.

Now we’ll go through each step in more detail. This part is very important, since we have to save some of the files generated locally or we lose the ability to transfer these certificates. This would mean revoking and re-issuing certificates (I have done this more times than I’d like to admit).

How to Create a Certificate Signing Request (CSR)

A Certificate Signing Request (CSR) is a fancy name for an encrypted block of text containing information about who’s requesting the certificate (like your name and the public key). These are widely used in the cryptography world.

For our purposes, you’ll generate a CSR on your Mac and then submit it to Apple to request a digital certificate. The CSR generation process also creates a new public/private key pair on the Mac – the private key is stored in Keychain Access and is used for the eventual code signing.

To create a CSR using Keychain Access on macOS:

1. Launch Keychain Access (you can find it at /Applications/Utilities/ or use spotlight).

2. From the menu bar, choose Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority.... (Here the Certificate Authority would be Apple).

3. In the dialog, enter your email address and a common name for the key (for example, "My Mac Key" or "[Your Name] Dev Key"). This name is primarily for your identification in the Keychain.

4. Leave the "CA Email Address" field empty – we won’t email it to the Certificate Authority (Apple).

5. Select the "Saved to disk" option and click "Continue".

6. Save the file, which will have a .certSigningRequest extension. The corresponding private key is now stored in the login keychain. This private key is irreplaceable by Apple and you must store it yourself.

How to Generate and Download Your Apple Certificates

Once you’ve created a CSR, you can request a certificate from the Apple Developer Portal:

1. Navigate to "Certificates, Identifiers & Profiles" and select "Certificates".

2. Click the add button (+).

3. Choose the desired certificate type

4. Follow the prompts, and when asked, upload the .certSigningRequest file generated earlier.

5. After Apple processes the request, the certificate will be available for download as a .cer file.

   

To install the certificate, double-click the downloaded .cer file. It will be added to the Keychain Access application – usually appearing in the "login" keychain under the "My Certificates" category, where it should be paired with the private key generated during the CSR generation process earlier.

You can see my certificate and private key in the image below for reference.

To recap, the CSR certifies that you generated the request from your mac. The certificate certifies that Apple (in this case, an intermediary like the "Apple Worldwide Developer Relations Certification Authority") confirms that they verified the CSR and that it is indeed you who will sign with the certificate (.cer) file.

This is enforced by only you having access to the private key – if you lose it, you cannot use this certificate anymore.

So, if you use this certificate (and the private key) to sign an app, the app store / operating system knows that it is you for sure since Apple confirmed it.

How to Store Your Keys: What are .p12 Files?

As I mentioned in the previous section, to code sign an app you need your certificate (containing the public key) and the corresponding private key. This is created along with the CSR, and you can find it in the Keychain Access app.

We call the combination of the certificate and the private key a digital identity. This proves your identity when you sign an app with them.

.p12 Files (Personal Information Exchange):

A .p12 file is a password-protected archive format used to bundle a certificate along with its private key. Its primary purposes are:

• Backing up the digital identity in case you lose access to your Mac.

• Transferring the digital identity to another Mac (for example, for another team member or a new development machine).

• Providing the identity to automated build systems or third-party build services.

Historically, I have stored the .p12 file on a shared drive with my team and shared the password to it verbally – you can also store it in a local backup disk.

Great. So how do you create one?

To export a .p12 file from Keychain Access:

1. Open Keychain Access, select the "login" keychain, and go to the "My Certificates" category.

2. Locate the desired certificate. It should have an expandable disclosure triangle indicating an associated private key (look at the image of my certificate above).

3. Select both the certificate and its private key (or right-click the certificate and choose "Export").

4. Right-click and choose "Export [X] items...".

5. In the save dialog, choose the "Personal Information Exchange (.p12)" file format.

6. Assign a strong password to protect the .p12 file. This password will be required when importing the file elsewhere. It is crucial for security.

7. Save the file to a secure location.

   

Bridge Between Everything: Provisioning Profiles

Provisioning profiles are the final link between an App ID, developer certificates, and, in some cases, a list of specific test devices. They act as a permission slip, authorizing an app signed with a particular certificate to be installed and run either on designated devices or to be submitted to the App Store.

What Exactly is a Provisioning Profile?

A provisioning profile is a .mobileprovision (for iOS / VisionOS) or .provisionprofile (for macOS) file that holds several key pieces of information:

• The App ID: Specifies which application (or set of applications, if using a wildcard App ID) the profile applies to.

• Certificates: Contains one or more developer or distribution certificates that can be used to sign the app.

• Device UDIDs (for Development and Ad Hoc): For profiles intended for testing on specific devices, it includes a list of the Unique Device Identifiers (UDIDs) of those authorized devices – more on devices in the next section.

• Entitlements: A list of app services or capabilities (like Push Notifications, iCloud, App Groups) that the app is permitted to use. These are derived from the capabilities enabled for the associated App ID.

You can open the file using vim or any editor to see parts of the content which include the App Id, Operating Systems, Certificates, and so on.

The operating system checks the provisioning profile at app launch to ensure the app is authorized to run on the current device and use the requested services. If the profile is missing, invalid, or doesn't match the app's signature or the device, the app will not launch.

They are difference from certificates, because certificates are tied to you as a developer. But provisioning profiles are to a specific app – with specific capabilities to a specific developer and maybe on specific devices.

If any of these change (let’s say you added a capability or your certificate expired, for example), you’ll need to generate the provisioning profile again. These are the files you will work with the most out of all the above, and any change can cause your profile to become invalid.

Types of Provisioning Profiles: Development, Ad Hoc, App Store, (and Enterprise)

Types of Provisioning Profiles: Development, Ad Hoc, App Store, (and Enterprise)

Just like certificates, we have multiple types of provisioning profiles. Similar to certificates, there can be development and distribution provisioning profiles.

Since we also keep track of the devices a profile is supposed to run, we have several kinds of distribution profiles based on which devices it should run on.

We also have special profiles like “Enterprise” which will add additional capabilities (like main camera access on the Vision Pro) but will restrict your app distribution methods to enterprise only.

We will go over each of these types now. Feel free to skip to the one that you’re looking for.

Development Provisioning Profile:

• Allows an app to be installed and debugged on specific devices registered in the developer's account during the active development phase. More on device registration later.

• Contains an App ID, one or more development certificates, and a list of registered device UDIDs.

• Created manually in the Apple Developer Portal or generated automatically by Xcode if Automatically manage signing is enabled.

Ad Hoc Provisioning Profile:

• Allows distribution of an app to a limited number of registered test devices without requiring Xcode for installation. This is ideal for distributing builds to QA teams, beta testers, or clients for feedback.

• Contains an App ID (often an explicit App ID, or an Xcode-managed one like XC Wildcard or XC), a single distribution certificate, and a list of registered device UDIDs.

• Created manually in the Developer Portal or managed by Xcode's automatic signing.

App Store Connect Provisioning Profile:

• Required to sign an app for submission to App Store Connect. This is the pathway for distributing apps via TestFlight for broader beta testing and for official release on the App Store.

• Contains an explicit App ID (or an App ID that matches the app's bundle ID, including Xcode-managed App IDs), and a single distribution certificate. Device UDIDs are not included in this profile type since this is meant for broader distribution.

• Created manually in the Developer Portal or managed by Xcode's automatic signing.

Enterprise Provisioning Profile:

• Exclusively for members of the Apple Developer Enterprise Program. It allows developers of these orgs to distribute proprietary, in-house applications directly to their employees, bypassing the public App Store.

• Note: This program has stringent enrollment criteria and is strictly for internal distribution within the enrolled organization – these apps cannot be pushed to AppStore.

Developer ID Provisioning Profile:

• Required to utilize certain Apple services or advanced capabilities like Push Notifications, CloudKit, Sign in with Apple, or specific iCloud services.

• Contains an App ID, a Developer ID distribution certificate, the entitlements authorized for the app.

• Created manually in the Developer Portal – will not be added automatically by Xcode’s automatic signing.

How to Create and Manage Provisioning Profiles

Creating and managing provisioning profiles usually requires an Account Holder or Admin role in the Apple Developer Program. You also need a configured App ID, the appropriate certificate(s), and for Development or Ad Hoc profiles, a list of registered device UDIDs.

If you are new developer, my recommendation is to read this article completely, then get back to this section once you have your devices setup.

General steps for manual creation in the Developer Portal:

1. Navigate to "Certificates, Identifiers & Profiles" and select "Profiles".

2. Click the add button (+).

3. Select the type of provisioning profile to create (for example, "iOS App Development," "Ad Hoc," "App Store").

4. Choose the App ID you’re targeting from the dropdown list.

5. Select the certificate(s) to include in the profile. Development profiles can include multiple development certificates – so you can include all the team member certificates here. Ad Hoc and App Store profiles include a single distribution certificate.

6. If creating a Development or Ad Hoc profile, select the registered devices to include.

7. Provide a name for the provisioning profile (this is for identification in the portal and Xcode).

8. Click "Generate" and then "Download" the .mobileprovision or .provisionprofile file.

You need to make downloaded profiles available to Xcode. You can often do this by double-clicking the downloaded file or by refreshing profiles within Xcode's account settings (Preferences > Accounts).

I really like Xcode's "Automatically manage signing" feature and it can simplify profile management by a lot. It creates and updates profiles as needed. But, understanding the manual process is crucial for troubleshooting because when things go wrong, it is straightforward to debug the issue with this knowledge.

Provisioning profiles will become invalid and require regeneration if:

• The capabilities of the associated App ID are changed – let’s say you added a new capability.

• An included certificate expires or is revoked.

• For Development/Ad Hoc profiles, if devices are added or removed from the registered list in a way that affects the profile's device set, or if the profile's own expiration date is reached. When such changes occur, you have to edit the profile (if possible) or delete it and recreate it in the Developer Portal, then re-download it and install it again. While this may seem like a complicated step, it’s straightforward if you do it a couple of times.

Device Management — Development and Ad Hoc Builds

For testing applications on physical Apple hardware outside of Testflight or AppStore, you’ll need to register the Unique Device Identifiers (UDIDs) of your test devices with your Apple Developer account. This registration is a necessary step for creating Development and Ad Hoc provisioning profiles.

Why You Need to Register Test Devices

Development and Ad Hoc provisioning profiles are specifically tied to a list of registered devices. An app signed with this profile can be installed directly without going through App Store process. This means that you need to register devices you intend to develop on. This restricts bad faith actors from releasing apps widely without developer and App Store supervision.

The UUID of a device is like a physical address (think Mac Address). If you don’t include this in the provisioning profile you used to sign an app package, it cannot be installed on that device.

Let’s go over the steps to do that.

How to Find Your Device's UDID (Unique Device Identifier)

A UDID is a unique 40-character hexadecimal string (for older devices) or a 25-character string (format XXXXXXXX-XXXXXXXXXXXXXXXX) that uniquely identifies a specific iPhone, iPad, Apple Watch, Apple TV, Vision Pro or Mac.

There are several ways to find a device's UDID:

• Xcode: Connect the device to a Mac running Xcode. Open Xcode and navigate to Window > Devices and Simulators. Select the connected device from the list on the left. The UDID will be displayed as the "Identifier" in the device information panel.

• Finder (macOS Catalina and later): Connect the iOS or iPadOS device to a Mac. Open Finder and select the device from the sidebar under "Locations." The UDID may be displayed directly, or it might be necessary to click on the line of text beneath the device's name (which shows model, storage, and OS version) to cycle through to display the UDID.

• iTunes (older macOS versions): For Macs running macOS Mojave or earlier, connect the device and open iTunes. Select the device icon when it appears. In the "Summary" tab, click on the "Serial Number" field; this will change to display the UDID.

• Apple Silicon Macs: When registering an Apple Silicon Mac, it's important to look for the "Provisioning UDID," which can be found in System Information under Hardware > Provisioning UDID.

• Other Ways: There are some websites that will install a profile on to your device to get the UUID – so as an absolute last resort, you can do this. But I highly recommend doing it in the one of the official ways to avoid any potential issues.

How to Register Devices in the Apple Developer Portal

Device registration is managed through the "Certificates, Identifiers & Profiles" section of the Apple Developer Portal (developer.apple.com) and typically requires an Account Holder or Admin role.

To manually register a single device:

1. Sign in to the Apple Developer Portal and navigate to "Certificates, Identifiers & Profiles," then select "Devices" from the sidebar.

2. Click the add button (+) to register a new device.

3. Select the correct platform for the device (for example, iOS, macOS, tvOS, watchOS).

4. Enter a descriptive "Device Name" (this is for your reference, for example, "Sravan’s iPhone 11 Pro") and the device's UDID obtained in the previous step.

5. Click "Continue," review the information to make sure everything is correct, and then click "Register".

For registering multiple devices, the portal supports uploading a specially formatted text file (a .txt or a .deviceids file) containing device names and UDIDs.

If "Automatically manage signing" is enabled in Xcode, Xcode can automatically register a connected device when it's selected as a build target. This is the way I managed all of my personal projects and devices. On the other hand, the file upload was really useful at my workplace to keep track of all the devices and add them at once.

Understanding Device Limits and Annual Resets

The Apple Developer Program imposes limits on the number of devices that can be registered for testing:

• Annual Limit: Each membership year, a development team can register up to 100 devices for each product family (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro, Mac). If you are a large team, this can potentially bottleneck you. When we ran into this issue, we created a new development team that could be split so that it didn’t have too much interdependence. There is no other way as far as I know, other than asking Apple and appealing them.

• Disabling Devices: While a device can be disabled in the portal during the membership year, doing so does not free up its slot or increase the number of available devices for that year. This part is frustrating but I think this is the only way they can enforce the 100 device limit to avoid people swapping devices. They should just provide a pathway to increase the limit, really. Disabling a device will, however, invalidate any provisioning profiles that include it, requiring those profiles to be regenerated.

• Resetting Device List (Start of New Membership Year): At the beginning of a new membership year, Account Holders, Admins, and App Managers are given a one-time option when they first sign in to "Certificates, Identifiers & Profiles" to remove devices from their list. This allows them to "reset" their available device count back to 100 for each product family. You can choose to remove specific devices or all registered devices. This is your one chance per year to remove unused devices completely and free up slots for new devices.

• Membership Expiration: If a developer program membership is nearing expiration and is not planned for renewal, the Account Holder will have an option, starting 30 days before expiration, to download a copy of their registered device list. They can also opt to have all devices removed from the account immediately upon membership expiration. If no action is taken, devices are typically removed automatically 180 days after membership expiration.

Possibilities: Enabling Capabilities and Services

App Capabilities (or App Services) are features provided by Apple that we (as developers) can integrate into our applications to extend functionality and provide richer user experiences. Examples include iCloud storage, Push Notifications, Sign in with Apple, Apple Pay and HealthKit integration. Enabling these often requires explicit configuration for an app's App ID in the Apple Developer Portal and within the Xcode project.

Why You Should Use Capabilities

Making full use of these App capabilities can set your app apart from other apps in a very noticeable way. You can use Apple Wallet integration if you want users to scan a membership card. You can use journaling suggestions if you want to prompt them to journal something. You can use iCloud Storage to lean further into inter-device synchronization.

When you enable a capability for an App ID, it results in specific entitlements being added to the app's provisioning profile. These entitlements are permissions that the operating system checks at runtime to ensure the app is authorized to use the requested service.

How to Configure Capabilities for Your App ID (Apple Developer Portal)

Enabling and configuring capabilities is typically done by an Account Holder or Admin in the Apple Developer Portal (developer.apple.com).

1. Navigate to "Certificates, Identifiers & Profiles" and select "Identifiers."

2. Choose the App ID for which capabilities need to be configured.

3. In the App ID's settings, there will be a "Capabilities" tab. Select the checkboxes for the capabilities the app requires.

4. Many capabilities require additional configuration steps. For these, a "Configure" or "Edit" button will usually appear next to the capability once selected. Examples include:

• App Groups: Requires creating or selecting an app group identifier to allow data sharing between a main app and its extensions, or between different apps from the same developer.

• Apple Pay: Requires associating one or more Merchant IDs with the App ID.

• iCloud: May require choosing Xcode version compatibility and creating or assigning iCloud containers for Key-Value or Document storage

• Sign in with Apple: May require configuring the App ID as a primary app or grouping it with an existing primary App ID, and optionally providing a server-to-server notification endpoint URL.

5. After configuring all selected capabilities, click "Save." A warning dialog may appear, which needs confirmation to finalize the changes.

Enabling a capability in the Developer Portal is only one part of the process. You’ll also need to add and configure it within the app's target in the Xcode project, under the "Signing & Capabilities" tab.

1. Navigate to the project settings and select “Signing & Capabilities”.

2. Press the “+ Capability” button to select the capability.

3. Once selected, the capability should appear in the pane. Depending on the capability, you might want to configure it further.

This Xcode step integrates the necessary frameworks, adds entitlements files to the project, and adjusts build settings.

How Enabling Capabilities Affects Your Provisioning Profiles

Changes to an App ID's enabled capabilities have a direct and significant impact on its associated provisioning profiles.

• Invalidation: When a capability is enabled, disabled, or its configuration is modified for an App ID, all existing provisioning profiles that use that App ID immediately become invalid.

• Regeneration Required: These invalidated provisioning profiles must be regenerated (either by editing and re-saving them in the Developer Portal or by having Xcode's automatic signing handle it). The regenerated profiles will then include the updated set of entitlements corresponding to the newly configured capabilities.

• Platform Impact: Enabling a capability for an App ID that is used across multiple platforms (for example, an iOS app and its watchOS companion) will affect the provisioning profiles for all eligible platforms that use that App ID.

This is something to keep in mind. Especially when it comes to distribution profiles since those are usually manually managed.

Conclusion

While all of these might seem daunting, Apple’s automatic process should handle most of it. But I highly recommend learning how everything works so that you can debug it in case something goes wrong. I also highly recommend using manually created profiles for distribution.

While signing and handling certificates is not the most exciting part of the App development process, it is a necessary skill to have. In my next article, I will go over distributing an app from start to finish (which includes these processes and more restrictions).

You can follow me at Sravan Karuturi for my other posts.