Installation

Qimchi supports multiple installation methods, including Docker, uv, and pip. We recommend using Docker, as it provides a containerized environment that isolates Qimchi from your local system. This ensures a smooth setup with all required dependencies and avoids potential conflicts with other software.

This guide provides instructions for installing Qimchi using various methods. Choose the one that best suits your use case.

---

Docker Installation

Prerequisites

First, ensure Docker is installed on your system. You can find installation instructions on the official Docker website.

Attention

Docker requires administrative privileges on Windows and may require sudo on macOS and Linux.

---

Basic Setup

To get started quickly without domain configuration, use the following compose.yaml file:

networks:
  squad:
    driver: bridge

services:
  qimchi:
    image: registry.gitlab.com/squad-lab/qimchi:latest
    container_name: qimchi
    profiles: ["webdev"]
    restart: unless-stopped
    ports:
      - 80:80
    volumes:
      - ./qimchi/data:/root/.qimchi/
      - /your/data/:/data/
    networks:
      - squad

Environment variables can be provided via a .env file:

NUM_WORKERS=10

This setup exposes Qimchi on localhost:80.

---

Advanced Setup (with Cloudflare Domain + HTTPS)

For production deployments with HTTPS and domain support (e.g., via Cloudflare), use the following compose.yaml configuration:

networks:
  squad:
    driver: bridge

services:
  nginx:
    image: nginx:latest
    container_name: nginx
    profiles: ["webdev"]
    user: root
    restart: unless-stopped
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/letsencrypt:/etc/letsencrypt
      - ./nginx/html:/usr/share/nginx/html
    ports:
      - 80:80
      - 443:443
    networks:
      - squad

  certbot:
    image: certbot/dns-cloudflare
    container_name: certbot
    profiles: ["webdev"]
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./nginx/letsencrypt:/etc/letsencrypt
      - ./nginx/html:/usr/share/nginx/html
      - ./nginx/certbot-secrets:/certbot-secrets
    entrypoint: >
      /bin/sh -c '
      echo "dns_cloudflare_api_token=$$CLOUDFLARE_API_TOKEN" > /certbot-secrets/cloudflare.ini;
      chmod 600 /certbot-secrets/cloudflare.ini;
      trap exit TERM;
      while :; do certbot renew; sleep 12h & wait $${!}; done;
      '
    networks:
      - squad

  qimchi:
    image: registry.gitlab.com/squad-lab/qimchi:latest
    container_name: qimchi
    profiles: ["webdev"]
    restart: unless-stopped
    volumes:
      - ./qimchi/data:/root/.qimchi/
      - /your/data/:/data/
    networks:
      - squad

Environment file .env example:

CLOUDFLARE_API_TOKEN=your_cloudflare_api_token
NUM_WORKERS=10

Example NGINX configuration (./nginx/conf.d/default.conf):

server {
    listen 80;
    server_name example.domain.org;

    # Redirect all HTTP traffic to HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name plot.domain.org;

    ssl_certificate /etc/letsencrypt/live/domain.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/domain.org/privkey.pem;

    location / {
        proxy_pass http://qimchi:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

This setup uses Certbot with Cloudflare for automatic TLS certificate renewal. Be sure to replace domain.org and plot.domain.org with your actual domain names.

Caution

Note The CLOUDFLARE_API_TOKEN environment variable is used to authenticate with Cloudflare’s DNS API for domain verification.

Local Installation

With uv

Follow the official instructions from Astral’s website to install uv. uv manages virtual environments and dependencies for you, making it easier to work with Python packages. For this project, we include the lock file which allows you to use the exact package versions we used to develop the package.

Measure and Plot

   uv init measurement_name
   cd measurement_name
   uv add qimchi

This method should automatically generate a virtual environment and install the package with all its dependencies. To add more packages to the current measurement/project, you can use the uv add command. For example, to add qcodes to the current project, run:

   uv add qcodes

uv automatically creates and manages the virtual environment for you.

Run Qimchi

To run Qimchi, use the following command:

   uv run -m qimchi

This command will start the Qimchi application, and you can access it in your web browser at http://localhost. If you can’t. please check if you are allowed to have a hosted session at port 80. If not, you can run the application on a different port by using the -p option:

   uv run -m qimchi -p 8080

With pip

Create and activate a virtual environment

On macOS or Linux:

   python3 -m venv .venv
   source .venv/bin/activate

On Windows:

   python3 -m venv .venv
   .venv\Scripts\activate

Install the package

   pip install git+https://gitlab.com/squad-lab/qimchi.git

Run Qimchi

After activating the virtual environment, you can run the package with:

   python -m qimchi

This command will start the Qimchi application, and you can access it in your web browser at http://localhost. If you can’t. please check if you are allowed to have a hosted session at port 80. If not, you can run the application on a different port by using the -p option:

   python -m qimchi -p 8080

Development Installation

We strongly recommend using uv for development. You can clone and install the package locally with uv.

   git clone https://gitlab.com/squad-lab/qimchi.git
   cd qimchi
   uv add --dev .

This makes and installs qimchi in a virtual environment with all dependencies. The rest of the process is the same as [running qimchi normally](#### Run Qimchi).