Docker Deployment

What Is This?

Zipoly Server is a packaged program that runs on your server via Docker (container technology). You don't need to install any programming language or dependencies — just:

1. Download an image package (.tar, ~50 MB)
2. Load and start it with Docker
3. Open a browser and it works

No Docker yet?

• Windows: Docker Desktop (free)
• Linux: curl -fsSL https://get.docker.com | sh
• Mac: Docker Desktop (free)

After installing, verify docker --version prints a version number.

Requirements

Item	Minimum	Recommended
OS	Linux / Windows / macOS	Ubuntu 22.04 LTS
Memory	2 GB	4 GB+
Disk	10 GB free	SSD with temp space for processed files
Docker	20.10+	Latest stable

Step 1: Get the Image

Download docker-dist.zip (~50 MB) from the "Team Edition" button on the homepage or from Gitee Releases. Unzip to get the release directory docker-dist/ with 3 files:

File	Purpose
zipoly-server-v2.1.0-image.tar	Docker image package, load directly with docker load -i
docker-compose.yml	Delivery compose file (image pre-configured, no changes needed)
DEPLOY.md	This deployment guide

# Load the image into local Docker (like unzipping the package into Docker)
docker load -i zipoly-server-v2.1.0-image.tar

# Confirm it loaded (you should see zipoly-server:2.1.0)
docker images

Step 2: Start the Service

Recommended: the delivery bundle includes a ready-to-use docker-compose.yml (image and data volume pre-configured). Go into the delivery directory and start:

cd docker-dist
cp docker-compose.yml ..   # optional: copy into your project directory
# Edit docker-compose.yml and replace ZIPOLY__SERVER__API_KEY, then:
docker compose up -d

You can also start with docker run directly:

docker run -d \
  --name zipoly-server \
  --restart unless-stopped \
  -p 8080:80 \
  -v zipoly-data:/app/data \
  -e ZIPOLY__SERVER__API_KEY=your-secure-api-key \
  zipoly-server:2.1.0

What Do These Parameters Mean?

Parameter	In one sentence
-d	Runs in the background, doesn't occupy your terminal
--name zipoly-server	Names the container for easier management
--restart unless-stopped	Auto-restarts the service after a server reboot
-p 8080:80	Maps the container's port 80 to port 8080 on your machine
-v zipoly-data:/app/data	Creates a persistent volume; data survives container deletion
-e ZIPOLY__SERVER__API_KEY=xxx	Sets the API key (required — use your own secret)

The API Key is like the service's password. Every API call must carry it to prevent others from abusing your service. Use a long random string.

Step 3: Verify It Works

# Command-line test (replace your-secure-api-key with the key you set)
curl -H "X-API-Key: your-secure-api-key" http://localhost:8080/api/v1/health

A response of {"status":"ok"} means success.

Then open http://localhost:8080/ in a browser — you should see the admin console.

Managing with docker-compose (Recommended)

The docker-compose.yml in the delivery bundle is production-ready (the build: section is replaced with image:, so it pulls the local image directly). If you want to write your own, use this template:

services:
  zipoly-server:
    image: zipoly-server:2.1.0
    container_name: zipoly-server
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - zipoly-data:/app/data
    environment:
      - ZIPOLY__SERVER__API_KEY=your-secure-api-key
      - ZIPOLY__LOGGING__LEVEL=info

volumes:
  zipoly-data:

# Start
docker compose up -d

# View logs (useful when troubleshooting)
docker compose logs -f

# Stop
docker compose down

Configuring a Domain and HTTPS (required for production)

If your server has a public IP or domain, add an nginx reverse proxy with an SSL certificate:

server {
    listen 443 ssl;
    server_name zipoly.example.com;   # replace with your domain

    ssl_certificate     /etc/nginx/certs/zipoly.pem;
    ssl_certificate_key /etc/nginx/certs/zipoly.key;

    client_max_body_size 512m;        # allow large uploads (important!)

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;       # large files may take a while
    }
}

Important: upload size limit

nginx only allows 1MB uploads by default — 3D models are usually much larger. You must set client_max_body_size, or uploads will fail with a 413 error.

Data Backup

All data (task records, uploaded files, processing results) lives in the /app/data volume. Backup is one command:

# Backup to the current directory
docker run --rm -v zipoly-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/zipoly-data-backup.tar.gz -C /data .

# Restore (new environment)
docker run --rm -v zipoly-new-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/zipoly-data-backup.tar.gz -C /data

Upgrading Versions

# 1. Stop and remove the old container (data stays in the volume)
docker stop zipoly-server && docker rm zipoly-server

# 2. Load the new image
docker load -i zipoly-server-v2.1.0-image.tar

# 3. Restart with the delivery compose file (data stays in the volume)
cd docker-dist && docker compose up -d

FAQ

Getting 401 after startup?

The request is missing the API Key, or the key is wrong. Check that -H "X-API-Key: ..." in your curl command matches what you set at startup.

Large file upload fails (413)?

The nginx client_max_body_size mentioned above isn't set, or is too small. Change it to 512m or larger.

Port 8080 is already in use?

Use a different port: -p 9090:80, then visit http://localhost:9090.

Tasks stay queued forever?

Not enough server memory, or the concurrency limit is set too low. See Configuration for queue tuning.

Data is gone after restart?

The -v zipoly-data:/app/data volume wasn't mounted at startup. Data is deleted with the container and cannot be recovered.

For API-level issues, see the API Reference.