Migration Guide

Zipline v4 includes built-in migration tools to import data from Zipline v3 or transfer data between Zipline v4 instances.

Migration Overview

Zipline supports two migration paths:

v3 to v4: Migrate from Zipline v3 to v4 (complete rewrite)
v4 to v4: Transfer data between v4 instances

Zipline v4 was a complete rewrite. There is no direct upgrade path from v3 - you must export data from v3 and import it into v4.

Before You Begin

Migrations must be performed by a SUPERADMIN user
Large exports (>1GB) may take significant time and memory
The import endpoint has a 24GB body size limit (~/workspace/source/src/server/routes/api/server/import/v3.ts:36)
Test migrations on a staging environment first

Migrating from Zipline v3 to v4

Export data from Zipline v3

In your Zipline v3 instance:

Log in as an administrator
Navigate to Manage → Export
Select what to export:
- Users
- Files
- Folders
- URLs
- Settings
Click Export Data
Download the export JSON file

The export includes metadata only. You’ll need to transfer actual files separately.

Transfer file storage

Copy your files from the v3 uploads directory to the v4 uploads directory:Local storage:

# From v3 uploads to v4 uploads
cp -r /path/to/zipline-v3/uploads/* /path/to/zipline-v4/uploads/

S3 storage:

# Files can remain in the same bucket
# Just configure v4 to use the same S3 bucket and credentials

Ensure file names are preserved exactly. Zipline uses the file name from the database to locate files.

Set up Zipline v4

Deploy Zipline v4 following the installation guide.Ensure you have:

A fresh v4 instance running
A SUPERADMIN user created
Access to the admin panel

Import data into v4

Use the v3 import API endpoint:

curl -X POST https://your-zipline-v4.com/api/server/import/v3 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d @export-v3.json

Or import via the admin dashboard if available.

The import process maps v3 data structures to v4:

Users (with passwords, OAuth, TOTP)
Files (with metadata, views, expiration)
Folders (with file associations)
URLs (shortened links)

See implementation: ~/workspace/source/src/server/routes/api/server/import/v3.ts

Verify the migration

After import completes:

Check the API response for import statistics:

{
  "users": {"old_id": "new_id", ...},
  "files": {"old_id": "new_id", ...},
  "folders": {"old_id": "new_id", ...},
  "urls": {"old_id": "new_id", ...}
}

Log in with your v3 credentials
Verify files are accessible
Check folders and organization
Test shortened URLs

Handle conflicts

If users or files already exist, they will be skipped:

Users: Skipped if username already exists
Files: Skipped if file name already exists
URLs: Skipped if URL code already exists
OAuth providers: Skipped if OAuth ID already exists

Check logs for warnings about skipped items:

docker compose logs zipline | grep "skipping importing"

Merge Import Option

You can import v3 data into an existing v4 user account:

curl -X POST https://your-zipline-v4.com/api/server/import/v3 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export3": {...},
    "importFromUser": "old_user_id_from_v3_export"
  }'

This merges the v3 user’s data into your current SUPERADMIN account.

Migrating Between Zipline v4 Instances

Use this to transfer data between v4 instances or for backups.

Export from source v4 instance

Use the export API endpoint:

curl -X POST https://source-instance.com/api/server/export \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -o export-v4.json

This exports:

Users
OAuth providers
User quotas
Passkeys
Folders (with hierarchy)
Files
Tags
URLs
Invites
Metrics (if enabled)

Transfer files

Local storage:

rsync -avz /source/uploads/ /destination/uploads/

S3 storage:

# Between different buckets
aws s3 sync s3://source-bucket s3://destination-bucket

# Or configure destination to use the same bucket

Import to destination v4 instance

curl -X POST https://destination-instance.com/api/server/import/v4 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d @export-v4.json

With configuration options:

curl -X POST https://destination-instance.com/api/server/import/v4 \
  -H "Authorization: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export4": {...},
    "config": {
      "settings": false,
      "mergeCurrentUser": "user_id_to_merge_into"
    }
  }'

Config options:

settings: Import instance settings (default: false)
mergeCurrentUser: Merge specified user into current admin account

Verify import

The API returns import statistics:

{
  "imported": {
    "users": 5,
    "oauthProviders": 3,
    "quotas": 2,
    "passkeys": 1,
    "folders": 10,
    "files": 1523,
    "tags": 15,
    "urls": 42,
    "invites": 3,
    "metrics": 1000
  }
}

Verify:

User count matches
Files are accessible
Folder hierarchy is preserved
Tags are assigned correctly

Import Behavior

Conflict Resolution

When importing data, conflicts are handled as follows:

Users

v3 import: Skipped if username exists (~/workspace/source/src/server/routes/api/server/import/v3.ts:69-76)v4 import: Skipped if username OR user ID exists (~/workspace/source/src/server/routes/api/server/import/v4.ts:68-80)Tokens: New tokens are generated for imported users

Files

Both imports: Skipped if file name already existsFile metadata imported:

Original name
Size and type
Views and max views
Deletion timestamp
Password protection
Favorite status

Folders

v3 import: Skipped if files for folder not foundv4 import: Skipped if folder name exists for userHierarchy: Parent-child relationships are preserved in v4 imports (~/workspace/source/src/server/routes/api/server/import/v4.ts:298-314)

URLs

Both imports: Skipped if URL code already existsURL properties imported:

Destination
Vanity code
Views and max views
Password
Enabled status

OAuth Providers

Both imports: Skipped if provider + OAuth ID combination existsImported providers:

Discord
Google
GitHub
OIDC

Data Relationships

The import process preserves relationships:

Users are imported first
OAuth providers and quotas are linked to imported users
Folders are created, then parent relationships are established
Files are linked to users and folders
Tags are created and linked to files
URLs and invites are linked to users
Metrics are imported with timestamps preserved

Troubleshooting

Import fails with 'not super admin' error

Only SUPERADMIN users can perform imports.Check your role:

curl https://your-instance.com/api/user/me \
  -H "Authorization: YOUR_TOKEN"

Ensure role is SUPERADMIN, not ADMIN or USER.

Files imported but return 404

This means database entries were created but files aren’t in storage:

Verify files were copied to correct location
Check file names match exactly (case-sensitive)
For S3, ensure bucket and subdirectory configuration matches
Check file permissions (local storage)

Import times out or fails on large exports

For very large exports:

Split the export into smaller batches
Import users first, then files, then URLs
Increase timeout limits in reverse proxy

Consider importing directly on the server:

docker exec -it zipline node /path/to/import-script.js

Users can't log in after import

v3 import: Passwords are imported as-isv4 import: Passwords are imported with original hashesIf users can’t log in:

Verify password was set in v3/source instance
Check if OAuth-only users (no password set)
Have users reset password via “Forgot Password”

OAuth providers not working after import

OAuth tokens may be expired or invalid:

Users may need to re-authenticate with OAuth providers
Verify OAuth client IDs/secrets match between instances
Check redirect URIs are updated for new domain

Many items skipped during import

Items are skipped when conflicts exist. Common causes:

Importing into a non-empty instance
Duplicate import attempts
Username/filename conflicts

Check logs for specific conflicts:

docker compose logs zipline | grep "skipping importing"

Best Practices

Test on staging first

Always test migrations on a staging environment before production:

Deploy fresh v4 instance
Import test export
Verify functionality
Document any issues

Backup before migration

Create backups before starting:

# Database backup
docker exec zipline-postgresql pg_dump -U zipline > backup.sql

# Files backup
tar -czf uploads-backup.tar.gz ./uploads

Plan downtime

For production migrations:

Schedule maintenance window
Put v3 in read-only mode (if possible)
Perform final export
Complete migration
Verify before switching DNS/traffic

Communicate with users

Inform users about:

Migration schedule
Expected downtime
Any action required (re-authentication, password resets)
New domain/URL if changing

Verify thoroughly

After migration:

Test file uploads
Verify existing files are accessible
Test URL shortening
Check user authentication (password + OAuth)
Verify folder structures
Test ShareX/API integrations

Post-Migration

After successful migration:

Update DNS: Point domain to new v4 instance
Update integrations: Update ShareX configs, API endpoints, etc.
Monitor logs: Watch for errors in the first few days
Keep v3 backup: Maintain v3 backup for 30 days as safety net
Update documentation: Document new endpoints, domains, or procedures

Consider running v3 and v4 in parallel for a transition period, allowing users to gradually migrate their integrations.

Get Started

Core Concepts

Configuration

Features

Integrations

Administration

Guides

Migration Guide

Migration Overview

Before You Begin

Migrating from Zipline v3 to v4

Merge Import Option

Migrating Between Zipline v4 Instances

Import Behavior

Conflict Resolution

Data Relationships

Troubleshooting

Best Practices

Post-Migration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Features

Integrations

Administration

Guides

​Migration Overview

​Before You Begin

​Migrating from Zipline v3 to v4

​Merge Import Option

​Migrating Between Zipline v4 Instances

​Import Behavior

​Conflict Resolution

​Data Relationships

​Troubleshooting

​Best Practices

​Post-Migration

Build docs developers (and LLMs) love

Migration Overview

Before You Begin

Migrating from Zipline v3 to v4

Merge Import Option

Migrating Between Zipline v4 Instances

Import Behavior

Conflict Resolution

Data Relationships

Troubleshooting

Best Practices

Post-Migration