# ezx

Client / Employer: Open Source / Personal | Category: Personal Project | Year: 2026 | Status: In Progress

Deterministic, scriptable container entrypoint engine in Go — replaces fragile bash entrypoint trees with a single binary driven by a declarative JavaScript script.

Tags: Go, Containers, Automation

## Overview

ezx is a deterministic, scriptable container entrypoint engine written in Go. It replaces fragile bash entrypoint.sh trees — sed/awk config rewriting, sleep-based readiness polling, and pgrep supervision loops — with a single binary driven by a declarative JavaScript script. It spawns and supervises dependency trees of processes, converts environment variables into config files and CLI arguments, strips secrets before spawning children, and handles PID-1 init duties like zombie reaping, signal forwarding, and graceful drain — all without a line of shell.

## The Problem

Docker images conventionally ship a bash entrypoint. That works, but it is brittle, unreadable, and unportable. Config is rewritten with sed -i against multiline template strings, readiness is approximated with sleep 5 instead of real probes, supervision is done with pgrep polling loops instead of a proper process tree, and secrets leak into children because the environment is never filtered. Every image reinvents the same fragile shell scaffolding, and it is nearly impossible to reason about or test.

## The Solution

ezx replaces that with a single static binary plus a small declarative JavaScript script. The script speaks a require("ezx") host API and declaratively describes everything: which files to provision, how to build CLI arguments from environment variables, which processes to spawn, how they depend on each other, and how to supervise them. The core abstraction is a process dependency tree where children start after their parent, wait on a parent readiness probe, or run in parallel with siblings. Every node can carry a restart policy, a health server, a cron scheduler, signal forwarding, probes, and graceful shutdown config. ezx also offers two launch modes: exec the app so it becomes PID 1 with native signal handling, or keep ezx as PID 1 for full supervision. A faithful port of the official PostgreSQL docker-entrypoint.sh is included as a working reference.

## Key Outcomes

- **No Shell:** Replaces fragile bash entrypoint trees with a single Go binary and a declarative JavaScript script — no sed/awk, no sleep polling, no pgrep loops.
- **Process Dependency Tree:** Spawns and supervises dependency trees of processes with parent-readiness gating and parallel sibling startup.
- **Env-Driven Determinism:** Converts environment variables into config files and CLI arguments declaratively, with secret filtering before spawning children.
- **PID-1 Init Duties:** Reaps zombies, forwards signals, and drains gracefully — or hands PID 1 to the app for native signal behaviour.
- **Two Launch Modes:** Exec the app to become PID 1 with native signals, or keep ezx as PID 1 for supervision, health, scheduling, and dependency ordering.
- **Faithful Port:** Includes a 1:1 behavioural port of the production PostgreSQL container entrypoint as a working reference.

## Project Summary

ezx is a deterministic, scriptable container entrypoint engine in Go. It replaces fragile bash entrypoint trees with a single binary driven by a declarative JavaScript script, spawning and supervising process dependency trees, converting environment variables into config and CLI arguments, filtering secrets, and handling PID-1 init duties. Available at github.com/supanadit/ezx.

## Key Features

- Go Language
- Container Entrypoint Engine
- Declarative JavaScript Scripts
- Process Dependency Tree
- Parent-Readiness Gating
- Parallel Child Spawning
- Env-to-Config Conversion
- Env-to-CLI-Argument Building
- Secret Env Filtering
- PID-1 Init Duties
- Zombie Reaping
- Signal Forwarding
- Graceful Drain
- Health & Readiness Probes
- Cron Scheduler Nodes
- Deterministic YAML Serialization

## Link

https://github.com/supanadit/ezx