Quickstart

This guide walks you through writing your first op, testing it locally, packaging it as a Docker image, and running it as a container.

Project structure

Create a folder greet-op/ with the following files:

greet-op/
├── main.py          # Op logic
├── gyoza.yml        # Gyoza manifest
├── Dockerfile       # Container recipe
└── pyproject.toml   # Python dependencies

main.py

A Gyoza Op is a plain Python function decorated with @gyoza_op. Inputs and outputs are Pydantic models that gyoza maps to a JSON-based I/O contract, wich allows the op to run inside a container, enabling it to work as a FaaS unit in the gyoza ecosystem.

from pydantic import BaseModel
from gyoza import gyoza_op


class Input(BaseModel):
    name: str
    times: int = 1


class Output(BaseModel):
    message: str


@gyoza_op(input_model=Input, output_model=Output)
def greet(name: str, times: int = 1):
    return (f"Hello, {name}! " * times).strip()

pyproject.toml

Declare gyoza as a dependency so it gets installed inside the container:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "greet-op"
version = "1.0.0"
requires-python = ">=3.12"
dependencies = [
    "gyoza @ git+https://github.com/g-e-o-i-a/gyoza.git",
]

[tool.setuptools]
py-modules = ["main"]

Dockerfile

The only gyoza-specific requirement is that the container’s default command calls gyoza run and that the dependencies of the op are installed in the container.

Because gyoza is installed from a private GitHub repository, the Dockerfile should include some git access to allow the pip install to work. In this example, we use a GITHUB_TOKEN build argument to authenticate the pip install and have access to the gyoza repository:

Important

For this example to work, you need to create a GitHub token with access to the gyoza repository and make it available in the build environment (e.g. as a build argument or environment variable).

FROM python:3.12-slim

ARG GITHUB_TOKEN

RUN apt-get update \
    && apt-get install -y --no-install-recommends git \
    && rm -rf /var/lib/apt/lists/*

RUN git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"

WORKDIR /app
COPY ./ /app/
RUN pip install --no-cache-dir .

CMD ["gyoza", "run", "--file", "main.py"]

gyoza.yml

The manifest tells gyoza how to build and identify your op:

name: greet-op
version: "1.0.0"
image: myregistry/greet-op:1.0.0

build:
  context: .
  dockerfile: Dockerfile
  args:
    GITHUB_TOKEN: "${GITHUB_TOKEN}"

Test locally

Before building the container, we can verify if the op logic works correctly by running it directly in the current Python process with gyoza run.

Since the I/O contract is JSON-based, inputs are passed as a JSON file. For testing, let’s create a input.json file:

{
  "name": "World",
  "times": 2
}

Then run the op (You should also specify file path for the output):

gyoza run --file greet-op/main.py \
  --input ./input.json \
  --output ./output.json

Check output.json for the result:

{
  "message": "Hello, World! Hello, World!"
}

See Test a Gyoza Op for all available options.

Build the container image

Once the op logic is ready, let’s build the op as a Docker image with:

gyoza build ./greet-op

See Build a Gyoza Op for full details on the build process.

The image should now be available in your local Docker registry:

>> docker images

REPOSITORY                             TAG       IMAGE ID       CREATED         SIZE
myregistry/greet-op                    1.0.0     31f3e0f1cfec   1 minute ago    1.2GB

Test the op as a container

Run the op inside the built image to verify it behaves correctly in the same conditions as production:

gyoza run-container myregistry/greet-op:1.0.0 \
  --input ./input.json \
  --output ./output.json

Next steps

This was a pretty quick guide to get you started with Gyoza. To understand the full development process, you can check the Build a Gyoza Op, Test a Gyoza Op and Deploy a Gyoza Op guides.

For understanding the full ecosystem components and how they fit together, you can check the Gyoza Ops, Gyoza Server and Gyoza Worker guides.

To start your own Gyoza cluster, you can check the Deploy the Gyoza Server and Deploy a Gyoza Worker guides.