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_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 gyoza image, starts the server database, starts the gyoza server. 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.

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#