Local Infrastructure Setup¶

This guide walks you through setting up Qiskit Serverless on your local machine for development and testing.

Overview¶

You can choose between two deployment approaches:

Docker Compose (Recommended for beginners)
- Fastest and simplest setup
- Spins up containers for all services (gateway, scheduler, Ray)
- Ideal for quick testing and development
Kind (Kubernetes-in-Docker) (Advanced)
- More closely resembles production environments
- Useful for testing Kubernetes-specific behaviors
- Requires more setup but provides better production parity

Prerequisites¶

Before you begin, ensure you have:

Python 3.10 or later
Git
Docker runtime (required for both approaches)
- Colima (recommended, especially for macOS with ARM processors)
- Docker Desktop
- Podman
Docker Compose (for Docker Compose approach)
Kind and kubectl (for Kubernetes approach - Kind runs Kubernetes in Docker)

Step 1: Prepare Your Environment¶

1.1 Create a Python Virtual Environment¶

We recommend using Python virtual environments to isolate dependencies.

On Linux/macOS:

python3 -m venv /path/to/virtual/environment
source /path/to/virtual/environment/bin/activate

On Windows (PowerShell):

python3 -m venv c:\path\to\virtual\environment
c:\path\to\virtual\environment\Scripts\Activate.ps1

For more information, see the Python virtual environments documentation.

1.2 Clone the Repository¶

cd /path/to/workspace/
git clone git@github.com:Qiskit/qiskit-serverless.git
cd qiskit-serverless

Step 2: Install and Configure Docker Runtime¶

Both deployment methods (Docker Compose and Kind) require a Docker runtime. We recommend Colima, especially for macOS with ARM processors, as it provides better performance and avoids architecture-related issues.

2.1: Install Docker Runtime¶

Recommended: Colima

Install Colima following the installation guide.

Alternative Options:

For more details, see the project README.

2.2: Start Docker with Adequate Resources¶

Qiskit Serverless uses distributed computing and requires adequate resources:

CPU: 4+ cores (minimum)
Memory: 8+ GB (minimum)
Disk: 100+ GB (minimum)

For Colima:

colima start --cpu 4 --memory 8 --disk 100

Adjust these values based on your workload. For intensive computations, consider allocating more resources.

Step 3: Choose Your Deployment Method¶

Now that Docker is running, choose how you want to deploy Qiskit Serverless:

Option A: Docker Compose Setup (Recommended)¶

This is the fastest way to get started with Qiskit Serverless locally.

3A.1: Start the Services

From the repository root, run:

docker compose up

This starts the core services. For additional services (logging, monitoring), use:

docker compose --profile full up

The services will be available at:

Gateway API: http://localhost:8000
Ray Dashboard: http://localhost:8265 (if using local Ray)

Option B: Kind (Kubernetes) Setup (Advanced)¶

This approach deploys a local Kubernetes cluster, providing an environment closer to production.

3B.1: Install Kind

Follow the Kind installation guide.

3B.2: Deploy the Cluster

We provide a script that initializes all required resources:

tox -e cluster-deploy

This command:

Creates a Kind cluster (running in Docker)
Deploys the Qiskit Serverless gateway
Sets up Ray operator and clusters
Configures networking

The services will be available at:

Gateway API: http://localhost

Step 4: Verify Your Setup¶

Once your infrastructure is running, verify it’s working correctly:

Check that all containers/pods are running:

Docker Compose:
```
docker compose ps
```
Kind:
```
kubectl get pods -A
```

Test the gateway API:

curl http://localhost:8000/health  # Docker Compose
curl http://localhost/health        # Kind

Step 5: Configure the Client¶

Now that your infrastructure is running, configure the Qiskit Serverless client to connect to it.

See the Client Configuration guide for detailed instructions.

Quick example:

from qiskit_serverless import ServerlessClient

client = ServerlessClient(
    token="awesome_token",
    instance="awesome_crn",
    host="http://localhost:8000",  # or "http://localhost" for Kind
)

Step 6: Run Your First Function¶

With everything set up, you’re ready to run quantum functions!

Explore the Function Features tutorials to learn how to:

Create and upload functions
Run distributed workloads
Retrieve results
And more

Next Steps¶

Function Features - Learn how to build and run Qiskit Functions
Client Configuration - Detailed client configuration options
Deployment - Deploy to production environments (advanced)

Troubleshooting¶

Services won’t start:

Ensure Docker/Kind is running
Check resource allocation (CPU, memory, disk)
Review logs: docker compose logs or kubectl logs <pod-name>

Connection refused:

Verify the correct host URL (localhost:8000 for Docker Compose, localhost for Kind)
Check firewall settings
Ensure services are fully started (may take 1-2 minutes)

Performance issues:

Increase allocated resources
Close unnecessary applications
Consider using the Docker Compose approach for lighter resource usage