Getting Started•4 min read•Recommended

Quickstart & Installation

Install the CIEL controller with the automated Linux installer or run it with Docker or Podman.

CIEL is a single-tenant, self-hosted web control plane for Ansible. Install it on a Linux server with the automated installer or run it as a container.

CIEL Controller Sign In and Onboarding Screen

Run the installer on a supported Linux server:

Terminal(bash)
curl -fsSL https://get.cielstack.com | bash

The installer:

  • Installs the required system packages.
  • Installs Ansible Core 2.18.2 in an isolated Python virtual environment when the installed version is missing or outdated.
  • Downloads the CIEL binary, verifies its SHA-256 checksum, and installs it in /usr/local/bin/ciel or the selected installation directory.
  • Verifies that the installed binary can run.

Start CIEL after the installation completes:

Terminal(bash)
ciel start
ciel status

ciel start initializes the controller directories, applies database migrations, creates the bootstrap administrator when needed, and starts CIEL in the background. Use ciel run instead when you want to keep the controller attached to the terminal.


2. Container Deployment (Docker & Podman)

If you run CIEL inside a container, choose between Docker Compose or standalone Podman/Docker CLI.

Option A: Docker Compose

Create a docker-compose.yml file:

docker-compose.yml(yaml)
services:
  ciel:
    image: cielstack/ciel:latest
    container_name: ciel
    restart: unless-stopped
    ports:
      - "8137:8137"
    volumes:
      - ciel_data:/root/.ciel
      # Optional: mount container socket to enable execution environment runners
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CIEL_BOOTSTRAP_ADMIN_USERNAME=admin
      - CIEL_BOOTSTRAP_ADMIN_PASSWORD=admin_password
      - [email protected]
      - CIEL_JWT_SECRET=replace-with-at-least-32-characters-random-secret
      - CIEL_ENCRYPTION_KEY=replace-with-a-different-long-random-encryption-key

volumes:
  ciel_data:
    name: ciel_data

Launch the container:

Terminal(bash)
docker compose up -d

Option B: Standalone Docker / Podman (CLI)

Run CIEL Controller with a persistent volume:

Terminal(bash)
docker run -d \
  --name ciel \
  --restart unless-stopped \
  -p 8137:8137 \
  -v ciel_data:/root/.ciel \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e CIEL_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e CIEL_BOOTSTRAP_ADMIN_PASSWORD=admin_password \
  -e [email protected] \
  cielstack/ciel:latest

Option C: Rootless Podman with Symmetric Path Binding

When using rootless Podman to run CIEL Controller and execute sibling runner containers, use Symmetric Path Binding:

Terminal(bash)
podman run -d \
  --name ciel \
  -p 8137:8137 \
  -v /opt/ciel-data:/opt/ciel-data:Z \
  -v /run/user/1000/podman/podman.sock:/run/podman/podman.sock:rw \
  -e CIEL_HOME=/opt/ciel-data \
  -e CIEL_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e CIEL_BOOTSTRAP_ADMIN_PASSWORD=admin_password \
  -e [email protected] \
  -e CIEL_JWT_SECRET=generate-a-secure-random-secret-here \
  -e CIEL_ENCRYPTION_KEY=generate-a-secure-random-encryption-key \
  cielstack/ciel:latest

Why Symmetric Path Binding Matters

When CIEL Controller spawns an OCI Execution Environment (such as quay.io/ansible/creator-ee), Ansible Runner communicates with the host container daemon via socket mount. The host daemon receives volume mount paths (such as /opt/ciel-data/workspaces/...) and resolves them directly against the host filesystem.

If you mount to a container default path like /root/.ciel, the rootless daemon on the host tries to access /root/.ciel on the host OS. Because /root is restricted to root:root (0700), the runner fails with statfs: permission denied. Setting identical host and container paths (-v /opt/ciel-data:/opt/ciel-data:Z with CIEL_HOME=/opt/ciel-data) ensures the host daemon finds the exact workspace path.


3. System Diagnostics (ciel doctor)

Verify that all dependencies and subsystems are operational:

Terminal(bash)
ciel doctor

Sample output:

text
[PASS] Database connection healthy (0.4ms)
[PASS] Master encryption key valid
[PASS] Runner engine ready
[PASS] SSH client binary ready
[PASS] Execution environments verified

4. External References

For upstream service management, container configurations, and execution environments: