archiso-compiler

Containerized micro-service system for building Arch Linux ISO images

Overview

A composable micro-service platform for building, tracking, and delivering Arch Linux ISO images via archiso with RESTful API. Designed for cloud-native deployment.

Services & Tools

• api-gateway: Elixir/Phoenix API gateway. Handles build requests, REST endpoints, user interaction, build tracking, and connects to PostgreSQL and the iso-builder.
• iso-builder: Elixir/Phoenix microservice. Performs actual Arch Linux ISO build jobs, file delivery, and low-level orchestration using mkarchiso and archiso.
• db: Official PostgreSQL 15 container. Provides persistent storage and transactional capabilities for tracking builds, status, and metadata. Volumes are used for data durability.

Usage

Deployment

1. Clone the repository:

   git clone https://github.com/Mournweiss/archiso-compiler.git
   
   cd archiso-compiler

2. Prepare and run build.sh:

   chmod +x build.sh
   
   ./build.sh

   build.sh arguments:

   --docker, -d              Use docker-compose backend orchestration
   --podman, -p              Use podman-compose as orchestrator
   --foreground, -f          Run containers in foreground (not detached)
   

   Note: build.sh automatically selects an available orchestration engine if no option is specified.

API Overview

The project exposes a single point of entry for ISO build requests and artifact delivery through the api-gateway service.

POST /build

Start a new Arch ISO build.

• Request:

  • Content-Type: application/json
  • JSON Body:
    • source_path (string, optional): Path to source directory (mounted in container)
    • source_url (string, optional): Git HTTPS URL with sources
    • output_path (string, optional): Directory for ISO output (default: "build/")
  • At least one of source_path or source_url must be supplied.

• Response:

  • { "status": "started", "id": "<build_id>" } on success
  • { "error": <reason> } on error

• cURL Example:

  # Using local path
  curl -X POST http://localhost:4000/build \
    -H "Content-Type: application/json" \
    -d '{"source_path": "data/example", "output_path": "build/output"}'
  
  # Using a git repo
  curl -X POST http://localhost:4000/build \
    -H "Content-Type: application/json" \
    -d '{"source_url": "https://github.com/user/repo.git"}'

GET /status/:id

Query build job status by build identifier.

• Path Param:
  • id (string): Build identifier returned from /build
• Response:
  • { "id": "<build_id>", "status": "done" | "running" | "not_found" }
• cURL Example:

  curl http://localhost:4000/status/abcd1234ef567890

GET /download/:id

Download the completed ISO.

• Path Param:
  • id (string): Build identifier
• Response:
  • ISO file as application/octet-stream (on success)
  • { "error": "..." } (if file not ready or not found)
• cURL Example:

  curl -OJ http://localhost:4000/download/abcd1234ef567890

(Replace build_id with an actual job ID returned from /build.)

Primary Environment Variables

• API_HOST — Host/IP for API gateway HTTP server (default: 0.0.0.0)
• API_PORT — API gateway HTTP port (default: 4000)
• ISO_BUILDER_HOST — Host or DNS for iso-builder service (default: iso-builder)
• ISO_BUILDER_PORT — iso-builder service API port (default: 4001)
• POSTGRES_USER — Database username (default: postgres)
• POSTGRES_PASSWORD — Database password (default: postgres)
• POSTGRES_DB — PostgreSQL database name (default: archiso_api)
• POSTGRES_HOST — Database host (default: db)
• POSTGRES_PORT — Database port (default: 5432)