mirror of
https://github.com/blw1138/cross-py-builder.git
synced 2026-09-07 21:41:09 -05:00
Brett Williams
18d8d2e398
Replace the CROSS_PY_WORKERS env list with a DB-backed worker store so agents can be added/removed (and their online status verified) from the browser. - db.py: add workers table + list_workers/add_worker/remove_worker. - workers.py: configured_workers() reads the DB instead of settings. - app.py: POST /api/workers (add, probes reachability) and DELETE /api/workers/<port>/<host>; startup log uses DB worker count. - UI: Workers card with add form, per-worker live status + OS/CPU, remove. - settings.py: drop CROSS_PY_WORKERS/_get_json_list; DB is single source. - README/DESIGN updated to describe UI-managed workers.
127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
# Cross-Py-Builder
|
|
|
|
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 on each host
|
|
- **Local network** between the controller and the agents
|
|
|
|
---
|
|
|
|
## 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:
|
|
|
|
| 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) |
|
|
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## Running the controller
|
|
|
|
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 .
|
|
```
|
|
|
|
Set the port (defaults to `8080`) and start it:
|
|
|
|
```sh
|
|
CROSS_PY_PORT=8080 cross-py-controller
|
|
```
|
|
|
|
Then open `http://<controller-ip>:8080` in a browser and add your agents from the
|
|
**Workers** section of the UI (in `host:port` form, e.g. `192.168.1.40:9001`). Each
|
|
row shows live status (ready/down) and the agent's OS/CPU/version. Configured workers
|
|
persist in the controller's SQLite DB, so they survive restarts — no environment
|
|
variables needed after setup.
|
|
|
|
### Controller environment variables
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `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` | `<repo>/data` | Data dir (SQLite jobs + workers DB, uploaded sources) |
|
|
| `CROSS_PY_BUILDS` | `<data>/builds` | Dir where finished build artifacts are saved |
|
|
| `CROSS_PY_DEBUG` | off | Use Flask dev server instead of waitress |
|
|
|
|
---
|
|
|
|
## Using the UI
|
|
|
|
1. **Add your agents** in the Workers section (`host:port`). Each shows live status
|
|
(ready/down) and OS/CPU once reachable.
|
|
2. Open the controller in a browser.
|
|
3. Pick the target **OS** and **CPU** (or "any").
|
|
4. Either upload a `.zip` of your project (PyInstaller spec + source) or paste a git
|
|
`repo_url`.
|
|
5. Submit. The job is queued → dispatched to a matching agent → built → artifacts fetched.
|
|
6. 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.
|