1. Prerequisites
Install OrbStack (recommended for macOS), Docker Desktop, or Docker Engine for Linux, and make sure it is running:You should see
Hello from Docker! in the output.2. Quick start
Clone the example and build the image:You should see:
OK — dataset=solar, year=2027, lcoe=43.39 USD/MWh3. The Python code
The example separates the model from the platform plumbing:main.py — the entry point
main.py
error result for a non-positive discount rate, and wraps main() so any exception exits with code 1. A non-zero exit tells the platform the run failed.
lcoe/airelabs.py — the helpers
Reads the input JSON and writes the output JSON, converting the platform’s decimal strings to and from Python numbers:read_hook_input()returns the list of input parameters.require_number(),require_string(),require_boolean(),require_date()extract one parameter by name and raise if it is missing.number_result(),number_array_result(),string_result(),boolean_result(),date_result(),error_result()build result entries.write_hook_output()writes the results file.
lcoe/data_lookup.py — bundled data
Containers have no network access when they run, so reference data is built into the image.data_lookup.py resolves data/ relative to its own file, not the working directory, and raises a clear error for an unknown dataset or year. See No Internet: Bundling Data for why and for how to bring in data from remote sources.
4. Different inputs
Copy a different fixture into/tmp/airelabs/hook-input.json and re-run the docker run command from the quick start.
Run the tests inside the image:
5. Writing your own function
- Write your model as plain Python that takes arguments and returns values.
- Edit
main.pyto read the parameters your model needs with therequire_*helpers and write its results with the*_resulthelpers. - Add a fixture in
fixtures/with the parameters your model expects. - Add dependencies to
dependenciesinpyproject.toml, then runuv lock. They are installed when the image is built. - Rebuild and run with
docker buildand the samedocker runcommand, using your fixture.
6. The Dockerfile
The example uses the official uv image and installs the locked dependencies at build time:Dockerfile
uv sync --lockedinstalls exactly the versions inuv.lock, so every build gets the same packages.COPY . /appcopies your code,data/, and fixtures into the image.CMDruns your entry point. It is aCMD, not anENTRYPOINT, so you can override it locally, as the test commands above do.
The platform runs
linux/amd64 images. If you build on Apple Silicon, build with docker build --platform linux/amd64 before you publish. The publishing workflow does this for you.7. Develop with moon
Thedocker commands above need nothing but Docker. The example repository also defines its test, lint, build, and release steps as moon tasks. moon installs the pinned Python and uv versions, keeps the virtual environment in sync with uv.lock, and skips a task when its inputs have not changed since the last run. The same tasks run in the repository’s GitHub Actions, so a green run on your machine means a green run in CI.
Install proto, the toolchain manager, then provision the pinned versions from the repository root:
.prototools. There is no separate install step: moon runs uv sync before each task when the lockfile has changed.
lcoe:build prints the name of the image it built. Use that name in place of lcoe-python in the docker run commands above.
To publish with lcoe:release, pass your organization ID and an API key with Registry Push permission (see Publishing Container Functions), and set RELEASE_ENV=production. Your organization ID is the part of your registry hostname between org- and .registry:
org-<your-org-id>.registry.airelabs.run/lcoe-python:v1.2.0. Set IMAGE_REPO to publish under a different image name. Without RELEASE_VERSION, the tag is the git tag on the current commit, or branch-<branch>-<short-sha> if there is none.
