Self-host Suils

Suils is designed to be self‑hosted. One docker compose command builds and runs the whole stack — the avatar API, the editor, and this documentation site — behind a single gateway.

With Docker Compose

From the repository root:

docker compose up -d --build

This starts two services behind an nginx gateway on port 8181:

• / → the avatar API (GET /<style>/<format>?seed=…)
• /editor → the visual editor
• /docs → this documentation

Put a TLS‑terminating reverse proxy (nginx, Caddy, IIS, a cloud load balancer…) in front of the gateway for production, and point your domain at it.

Environment variables

The API service reads the following environment variables (set them in docker-compose.yml under the api service):

Variable	Default	Description
HOST	0.0.0.0	Host to bind to inside the container.
PORT	3000	Port the API listens on inside the container.
MAX_SIZE	1024	Maximum allowed size (px) for output.
CACHE_CONTROL_MAX_AGE	86400	Cache-Control: max-age (seconds) on avatar responses.
PUBLIC_BASE_URL	https://avatars.suils.es	Base URL shown in the API landing‑page examples.

The gateway's published address and port are configurable too:

Variable	Default	Description
GATEWAY_BIND	0.0.0.0	Address the gateway publishes on.
GATEWAY_PORT	8181	Host port the gateway publishes on.

Raster rendering

PNG / JPG / WebP / AVIF output is rendered from the SVG with resvg and sharp. The API image ships a base font set so text‑based styles rasterize correctly.

Health check

The gateway and API both expose a health endpoint:

GET /healthz  →  200 ok