Configuration Reference

Every runtime parameter of Zipoly Server lives here: API keys, License entitlement, queue concurrency, file retention and log levels. Configuration comes in via ZIPOLY__-prefixed environment variables or a config.yaml file; restart the container to apply changes.

Two Ways to Configure

Method	When to use	Priority
Environment variables (recommended)	Passed via -e at container startup; secrets never touch the disk	High
config.yaml	A file for many settings, mounted into the container	Low

You can mix both — environment variables override the same-named keys in the YAML.

Quick Reference: The Most Common Settings

In most cases you only need to change these:

docker run -d \
  -e ZIPOLY__SERVER__API_KEY=your-key \             # required! API access password
  -e ZIPOLY__LICENSE__KEY=your-license-key \        # optional, fill in after purchase
  -e ZIPOLY__QUEUE__MAX_CONCURRENT=10 \             # concurrent tasks (raise with more RAM)
  -e ZIPOLY__STORAGE__RETENTION_HOURS=24 \          # file retention (hours)
  zipoly-server:2.1.0

All Configuration Options

Server (server)

Environment variable	Default	Description
ZIPOLY__SERVER__HOST	0.0.0.0	Listen address — usually leave as is
ZIPOLY__SERVER__PORT	8080	Port inside the container — usually leave as is (external port is controlled by -p)
ZIPOLY__SERVER__API_KEY	(required)	API key. Every request must carry it — it's the service's password
ZIPOLY__SERVER__RATE_LIMIT_PER_MINUTE	60	Reserved: rate limiting is not yet active in this version

Storage (storage)

Environment variable	Default	Description
ZIPOLY__STORAGE__BACKEND	local	Storage backend — only local (local disk) is supported in this version
ZIPOLY__STORAGE__RETENTION_HOURS	24	How long uploaded files and results are kept before auto-cleanup (hours)

File cleanup behavior

Results are deleted automatically after 24 hours by default. If your team downloads late, consider:

• Intranet use: set 168 (one week)
• Public service: keep 24 or shorter

Task Queue (queue)

Environment variable	Default	Description
ZIPOLY__QUEUE__MAX_CONCURRENT	10	Number of tasks processed simultaneously. With 8G+ RAM you can raise it to 20–30
ZIPOLY__QUEUE__TASK_TIMEOUT_SECONDS	600	Max execution time per task (seconds); timed-out tasks are terminated. Large models may need more

License (license)

Environment variable	Default	Description
ZIPOLY__LICENSE__KEY	empty	License Key — fill in after purchase. Empty = trial mode

Trial mode limits are described in Server Licensing.

Logging (logging)

Environment variable	Default	Description
ZIPOLY__LOGGING__LEVEL	info	Log level: debug (most verbose) → info → warn → error (least)
ZIPOLY__LOGGING__FORMAT	json	Output format: json (structured, easy to collect) or text (human-readable)

Switch to debug temporarily when troubleshooting:

-e ZIPOLY__LOGGING__LEVEL=debug -e ZIPOLY__LOGGING__FORMAT=text

Configuring with config.yaml (Advanced)

When there are many settings, manage them with a YAML file:

# config.yaml
server:
  host: "0.0.0.0"
  port: 8080
  api_key: "your-secure-api-key"     # required
  rate_limit_per_minute: 60

storage:
  backend: "local"                   # only local is supported in this version
  retention_hours: 24                # file retention (hours)
  local:
    upload_dir: "/tmp/uploads"
    result_dir: "/tmp/results"

queue:
  max_concurrent: 10                  # concurrency
  task_timeout_seconds: 600           # timeout (seconds)

license:
  key: ""                            # License Key (optional)

logging:
  level: "info"                      # debug / info / warn / error
  format: "json"                     # json / text
  file_path: null                    # empty = console only

Mount it into the container:

docker run -d \
  -v ./config.yaml:/app/config.yaml:ro \
  ...other parameters...

:ro mounts the file read-only — the container cannot modify it.

S3 Object Storage (Planned)

S3-compatible storage (MinIO, Alibaba Cloud OSS, etc.) is planned. This version only supports local disk storage (local).

Tuning Recommendations

Scenario 1: Daily team use (5–10 people)

-e ZIPOLY__QUEUE__MAX_CONCURRENT=5 \
-e ZIPOLY__STORAGE__RETENTION_HOURS=168   # keep for a week

Scenario 2: CI/CD pipeline integration

-e ZIPOLY__QUEUE__MAX_CONCURRENT=2 \
-e ZIPOLY__QUEUE__TASK_TIMEOUT_SECONDS=300 \
-e ZIPOLY__STORAGE__RETENTION_HOURS=4      # the pipeline fetches results immediately

Scenario 3: High-volume processing (100+ files/day)

-e ZIPOLY__QUEUE__MAX_CONCURRENT=20 \
-e ZIPOLY__LOGGING__LEVEL=warn            # reduce log volume