Configuration Reference

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	Max requests per minute per key — prevents abuse

Storage (storage)

Environment variable	Default	Description
ZIPOLY__STORAGE__BACKEND	local	Storage backend: local (local disk) or s3 (object storage)
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
ZIPOLY__LICENSE__TRIAL_ENABLED	true	Whether trial mode is allowed. Set false to force a license

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"                   # local or s3
  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)
  trial_enabled: true                # allow trial
  trial_state_path: "./data/trial_state.json"

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 (Optional)

For cross-server shared storage or very large data volumes, switch to S3-compatible storage (e.g., MinIO, Alibaba Cloud OSS):

-e ZIPOLY__STORAGE__BACKEND=s3 \
-e ZIPOLY__STORAGE__S3__ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com \
-e ZIPOLY__STORAGE__S3__BUCKET=my-zipoly-bucket \
-e ZIPOLY__STORAGE__S3__ACCESS_KEY_ID=AKxxx \
-e ZIPOLY__STORAGE__S3__SECRET_ACCESS_KEY=SKxxx \
-e ZIPOLY__STORAGE__S3__REGION=cn-hangzhou

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