diff --git a/README.md b/README.md index 31552ad..13071ab 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,123 @@ # Cross-Py-Builder -Cross-Py-Builder is a simple remote build tool for compiling Python projects with PyInstaller on different platforms on a local network. +Cross-Py-Builder is a remote build tool for compiling Python projects with PyInstaller on +different platforms (Linux, macOS, Windows) across a local network. + +It has two parts: + +- **Controller** — a small web service with a browser UI for submitting builds (upload a zip + or point at a git repo), tracking live progress, and downloading the resulting binaries. +- **Agent** (worker) — one per target OS/CPU. Runs the actual PyInstaller builds and exposes + them over HTTP; the controller dispatches builds to an agent matching the requested + OS + CPU. ## System Requirements -- **Ubuntu/Debian & macOS:** 2GB+ RAM -- **Windows:** 4GB+ RAM -- **Python 3.10 or later** installed -- **Local Network** for build agents +- **Ubuntu/Debian & macOS:** 2GB+ RAM +- **Windows:** 4GB+ RAM +- **Python 3.10 or later** installed on each host +- **Local network** between the controller and the agents --- -### Example Usage +## How it's packaged +This is a Python package installed with `setuptools` (`setup.py`). Installing it (editable, for +development) makes two commands available on your PATH: - ```sh - ./cross-py-builder.py --build /path/to/repo -cpu x64 -os windows +| Command | Runs | Purpose | +|---|---|---| +| `cross-py-controller` | `ctrl.app:main` | Web UI + scheduler (the machine you browse to) | +| `cross-py-agent` | `agent.build_agent:main` | Worker agent (one per target OS/CPU) | -options: - -h, --help show this help message and exit - --status Get status of available servers - --build BUILD Path to the project to build - -cpu CPU CPU architecture - -os OS Operating system - -d, --download Download after build - --delete-cache Delete cache - --update-all Update build agent - --restart RESTART Hostname to restart - --restart-all Restart all agents - --shutdown SHUTDOWN Hostname to shutdown - --shutdown-all Shutdown all agents +Start by installing the package into a virtualenv on **every** machine that will act as a +controller or agent: + +```sh +cd cross-py-builder +python3 -m venv venv +source venv/bin/activate + +pip install -e . # editable install: installs deps + links to your working dir +``` + +`-e` (editable) links the install to your checkout, so code changes take effect without +reinstalling. On the LXC workers you can alternatively copy the source and just run the `.py` +files (see below). + +--- + +## Running a worker (agent) + +On each target OS/CPU machine (e.g. each Ubuntu LXC): + +```sh +cd cross-py-builder +python3 -m venv venv +source venv/bin/activate +pip install -e . + +cross-py-agent +``` + +The agent binds on port `9001` and announces itself on the local network. To run it +directly without the package command: + +```sh +pip install -r requirements.txt +python agent/build_agent.py ``` --- -## Worker VM Setup Guide +## Running the controller -This guide provides steps to set up a worker VM on **Ubuntu/Debian, macOS, or Windows**. +On the machine that will serve the browser UI: +```sh +cd cross-py-builder +python3 -m venv venv +source venv/bin/activate +pip install -e . +``` -### Ubuntu/Debian or macOS -1. **Create a new VM** and install the OS. -2. **Update the system:** - - **Ubuntu/Debian:** - ```sh - sudo apt update && sudo apt upgrade -y - sudo apt install python3-pip python3-venv -y - ``` - - **macOS:** - ```sh - xcode-select --install # Install xcode tools - ``` -3. **Install Python** >=3.10 from [python.org](https://www.python.org/downloads/) (Windows and macOS - macOS) -4. **Set up a virtual environment:** - - **Ubuntu/Debian/macOS:** - ```sh - python3 -m venv venv - source venv/bin/activate - ``` - - **Windows:** - ```sh - python3 -m venv venv - venv\Scripts\activate - ``` -5. **Copy project files** and install dependencies: - ```sh - pip install -r requirements.txt - ``` -6. **Start Build Agent**: - - **Ubuntu/Debian/macOS:** - ```sh - python3 build_agent.py - ``` - - **Windows:** - ```sh - python build_agent.py - ``` ---- \ No newline at end of file +Set the static worker list (JSON array of `host:port`, matching where your agents are +listening) and start it: + +```sh +CROSS_PY_WORKERS='["192.168.1.40:9001","192.168.1.41:9001"]' \ +cross-py-controller +``` + +Then open `http://:8080` in a browser. + +### Controller environment variables + +| Variable | Default | Purpose | +|---|---|---| +| `CROSS_PY_WORKERS` | (none) | JSON array of agent `host:port` strings | +| `CROSS_PY_PORT` | `8080` | HTTP port the controller UI listens on | +| `CROSS_PY_MAX_CONCURRENT` | `1` | Max simultaneous builds (across distinct agents) | +| `CROSS_PY_DATA` | `/data` | Data dir (jobs DB, uploaded sources) | +| `CROSS_PY_BUILDS` | `/builds` | Dir where finished build artifacts are saved | +| `CROSS_PY_DEBUG` | off | Use Flask dev server instead of waitress | + +--- + +## Using the UI + +1. Open the controller in a browser. +2. Pick the target **OS** and **CPU** (or "any"). +3. Either upload a `.zip` of your project (PyInstaller spec + source) or paste a git + `repo_url`. +4. Submit. The job is queued → dispatched to a matching agent → built → artifacts fetched. +5. Watch live per-step progress, then download the built binaries from the job detail. + +A submitted project only needs the source plus at least one `*.spec` file; each spec file in +the archive produces a build. + +--- + +## Retired CLI + +The original single-command CLI (`./cross-py-builder.py --build ...`, `agent_manager.py`) has been +removed and replaced by the controller + agent model above.