yoshida yoshida DEV
Open the editor

Docs Start

Server and Docker

On this page

yoshida-server is a small static HTTP server. It serves the built editor and, when enabled, renders a whole card set on the machine it runs on and returns a zip of PNGs (the "hybrid" mode, handy for home labs and big sets). It uses the same core as the CLI and the browser, so the pixels are identical.

yoshida-server [--host ADDR] [--port N] [--web DIR] [--no-render]
               [--max-cards N] [--max-body-mb N] [--threads N]
OptionEnvironment variableDefaultMeaning
--hostYOSHIDA_HOST0.0.0.0Address to listen on
--portYOSHIDA_PORT8080Port
--webYOSHIDA_WEBwebFolder with the built editor (web/dist from a source build, web/ in the release zip)
--no-renderYOSHIDA_RENDER=0rendering onServe the editor only; POST /api/render answers 403 and the editor hides the Render on server switch
--max-cardsYOSHIDA_MAX_CARDS1000Largest set the server will render in one request
--max-body-mbYOSHIDA_MAX_BODY_MB200Largest request body
--threadsYOSHIDA_THREADSall CPUsWorker threads used to render a set

The limits of a design (500 layers per card and the others) are raised with YOSHIDA_MAX_LAYERS, YOSHIDA_MAX_REPEAT, YOSHIDA_MAX_CANVAS, YOSHIDA_MAX_IMAGE_MP and YOSHIDA_MAX_SET_CARDS, environment variables only; the editor served by the server follows them. See Raising a limit.

Command-line options win over environment variables. The server can also keep optional, anonymous usage statistics (on by default at the basic level, see that page for its options: --no-telemetry, --telemetry-dir, --telemetry-default, --telemetry-force, --telemetry-retention-days, --admin-token).

Running the release zip

The start scripts run the server for you: ./start.sh, start.command or start.bat. They pass --host 127.0.0.1, so the editor is reachable from your own computer only. To let other machines in, run the binary directly:

bin/x86_64-linux/yoshida-server --host 0.0.0.0 --web web

The server has no authentication and no TLS. Put it behind a reverse proxy (and an access control of your choice) before exposing it beyond a trusted network.

Docker

The Dockerfile is a multi-stage build: Zig 0.16.0 (from the ziglang package on PyPI) builds the two static binaries and the WASM module, Node 22 builds the editor, Zola builds the website, and the final image is scratch with just yoshida, yoshida-server and the website, with the editor in /editor/ and the docs in /docs/. It runs as an unprivileged user (65534:65534).

docker build -t yoshida .
docker run -p 8080:8080 yoshida                       # editor + server render
docker run -p 8080:8080 -e YOSHIDA_RENDER=0 yoshida   # editor only (render in the browser)

The image sets YOSHIDA_WEB=/web, YOSHIDA_PORT=8080 and YOSHIDA_TELEMETRY_DIR=/data, and exposes port 8080. All other options are environment variables (table above).

Docker Compose

compose.yaml builds and starts the container. Its settings are in a file named .env beside it, one environment variable per line (table above). .env.example lists them all with their defaults; copy it and edit the copy:

cp .env.example .env
docker compose up --build
YOSHIDA_RENDER=1
YOSHIDA_MAX_CARDS=1000
YOSHIDA_MAX_BODY_MB=200
#YOSHIDA_THREADS=4

Compose reads .env by itself: for YOSHIDA_CHANNEL, which it passes to the build, for YOSHIDA_PUBLISH_PORT, the port on your machine (default 8080), and for the variables it hands to the container. .env is not committed and is left out of the image, so an admin token in it stays on your machine. Without a .env the server runs with its defaults. The usage counts are kept in the volume yoshida-data, see Where the counts are stored. A variable set in the shell (YOSHIDA_CHANNEL=dev docker compose up --build) wins over the file for the build and the port; the container only gets what is in the file.

The image also contains the yoshida CLI at /yoshida, which you can run with docker run --rm -v "$PWD:/p" --entrypoint /yoshida yoshida render /p/my-cards.

Using server rendering from the editor

When the editor is served by yoshida-server with rendering enabled, the toolbar shows a Render on server switch next to the export buttons. Switched on, ZIP and PDF upload the project's files to POST /api/render and download the result; otherwise rendering happens in the browser. The export dialog sends PNG, SVG and PDF files and sheets of whole designs the same way, one request per design and format, with its resolution, crop marks, PDF pages (vector or image) and PNG settings; JPEG and WebP still render in the browser. See Saving, Images and Privacy for what is and is not sent.

The progress window shows each step (pack, upload with the bytes sent, render on the server with the cards done, download, save) and an activity log; the same lines go to the browser console as [yoshida] …. The cards done come from GET /api/render/progress.

The server logs every render request on stderr (docker logs), for example:

render #3: receiving 4.2 MB
render #3: 31 files, set 'boards', 120 cards as png on 8 thread(s)
render #3: 12/120 cards
…
render #3: done, 120 cards in 9412 ms, sending 38.0 MB of zip

Refused and failed requests are logged too (over --max-body-mb or --max-cards, unknown set, a project with errors).

The server never downloads images from URLs; upload images with the project instead (an unreachable URL is error 4001).

HTTP API

The API is small and documented in Server API: GET /api/capabilities, POST /api/render, the usage statistics endpoints, and static files for everything else. You can call it from your own tools.

↑↓ to moveEnter to openEsc to close