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.
1. Automated Linux install (recommended)
Run the installer on a supported Linux server:
curl -fsSL https://get.cielstack.com | bashThe 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/cielor the selected installation directory. - Verifies that the installed binary can run.
Start CIEL after the installation completes:
ciel start
ciel statusciel 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:
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_dataLaunch the container:
docker compose up -dOption B: Standalone Docker / Podman (CLI)
Run CIEL Controller with a persistent volume:
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:latestOption C: Rootless Podman with Symmetric Path Binding
When using rootless Podman to run CIEL Controller and execute sibling runner containers, use Symmetric Path Binding:
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:latestWhy 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:
ciel doctorSample output:
[PASS] Database connection healthy (0.4ms)
[PASS] Master encryption key valid
[PASS] Runner engine ready
[PASS] SSH client binary ready
[PASS] Execution environments verified4. External References
For upstream service management, container configurations, and execution environments:
- Systemd Service Management: Documentation on Linux unit files, service supervision, and auto-restart policies.
- Docker Compose Documentation: Compose file specification for multi-container deployments.
- Podman Rootless Tutorial: Setting up rootless containers and user systemd socket integration.
- Ansible Execution Environments: Building and customizing OCI execution environment container images.