Deploy the Gyoza Server#

The gyoza server is the control plane for the entire ecosystem. It exposes the REST API, persists state in MongoDB, and schedules OpRuns across workers. This guide shows how to deploy it using the Docker Compose setup included in the gyoza repository.

Prerequisites#

Clone the repository#

If you haven’t already, clone the gyoza repository and move into its root directory:

git clone https://github.com/g-e-o-i-a/gyoza.git
cd gyoza

All the commands in this guide assume you are in the repository root.

Environment variables#

The Docker Compose file reads several environment variables at startup. You can set them in a .env file at the repository root or export them directly in your shell.

Variable

Default

Description

GYOZA_API_KEY

(empty)

When set, every request must include the X-API-Key header with this value, otherwise the server returns 401 Unauthorized. Leave empty to disable authentication.

GYOZA_PORT

5555

Port the server listens on. This is the port you will use to reach the REST API.

GYOZA_UI_PORT

3000

Host port for the web UI container (gyoza-ui). With the default Compose setup, open http://localhost:3000 in a browser.

GYOZA_LOG_LEVEL

info

Log verbosity (debug, info, warning, error).

GYOZA_WORKER_TIMEOUT

60

Seconds before a silent worker is considered inactive and evicted from the pool.

A minimal .env file looks like this:

GYOZA_API_KEY=my-secret-key

Important

Save the values you choose for GYOZA_API_KEY and the full server URL (e.g. http://localhost:5555, http://gyoza.geoia.tech). You will need them later when configuring workers and the CLI/SDK:

Value

Used as

Server URL (e.g. http://<host>:5555)

GYOZA_SERVER_URL environment variable in the worker, CLI, and SDK.

API key (the GYOZA_API_KEY you set)

GYOZA_API_KEY environment variable in the worker, CLI, and SDK.

Start the server#

The scripts/start_server.sh helper wraps Docker Compose so you don’t have to remember the compose file path. From the repository root, run:

./scripts/start_server.sh up

This builds the images, starts MongoDB, the gyoza server, and the web UI (gyoza-ui). By default the process runs in the foreground so you can see the logs directly. To run it in the background, pass the -d flag:

./scripts/start_server.sh up -d

The script accepts the same actions as docker compose, you can use it to stop the server, build the image, etc. Any extra arguments after the action are forwarded to docker compose, so you can use flags like -d, --force-recreate, or --no-cache as needed.

Verify the server is running#

Once started, hit the health endpoint:

curl -H "X-API-Key: my-secret-key" http://localhost:5555/health

A {"status": "healthy"} response confirms the server is up and ready to accept requests.

Web UI#

The same Compose file runs the gyoza-ui service: a static SPA plus nginx that proxies /definitions, /runs, /workers, and /health to gyoza-server on the Docker network. After the stack is up, open the UI at http://localhost:<GYOZA_UI_PORT> (default 3000). The REST API is still available directly at http://localhost:<GYOZA_PORT> (default 5555) for workers, the CLI, and the SDK.

When GYOZA_API_KEY is set for Compose, the UI container forwards that key to the server on proxied API requests, so the browser does not need a separate key for those routes.

Stop the server#

./scripts/start_server.sh down

This stops and removes all containers created by the Compose file while preserving the MongoDB data volume.

Next steps#