DOCSEARCHbyAlgolia
Submit Docs

Zipline Documentation

repository·trunk·Indexed 25 days ago

https://github.com/diced/zipline

A next-generation file upload server supporting URL shortening, image compression, video thumbnails, and webhook/OAuth2 integrations. Version 4.6.5 requires a CPU with AVX support. Features include S3 and local storage options, Docker Compose deployment, and a comprehensive API for managing files and folders.

Tokens
14.1K
Snippets
12
Records
106
Agent score
85%

What's inside Zipline

  1. Generate Environment Secrets

    trunk

    Use these commands to generate secure random strings for your .env file:

    echo "POSTGRESQL_PASSWORD=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32 | tr -d '\n')" > .env
echo "CORE_SECRET=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32 | tr -d '\n')" >> .env

    Note: The CORE_SECRET environment variable is required for Zipline to start.

  2. Install and Run Zipline with Docker

    trunk

    The recommended way to run Zipline is using Docker Compose. This setup includes a PostgreSQL database and the Zipline service.

    Warning: Zipline requires a CPU with AVX support. Binaries and images for non-AVX CPUs are not provided.

    1. Create a .env file with your required secrets (see Generating Secrets).
    2. Use the following docker-compose.yml configuration:
    services:
  postgresql:
    image: postgres:16
    restart: unless-stopped
    env_file:
      - .env
    environment:
      POSTGRES_USER: ${POSTGRESQL_USER:-zipline}
      POSTGRES_PASSWORD: ${POSTGRESQL_PASSWORD:?POSTGRESSQL_PASSWORD is required}
      POSTGRES_DB: ${POSTGRESQL_DB:-zipline}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'zipline']
      interval: 10s
      timeout: 5s
      retries: 5

  zipline:
    image: ghcr.io/diced/zipline
    ports:
      - '3000:3000'
    env_file:
      - .env
    environment:
      - DATABASE_URL=postgres://${POSTGRESQL_USER:-zipline}:${POSTGRESQL_PASSWORD}@postgresql:5432/${POSTGRESQL_DB:-zipline}
    depends_on:
      postgresql:
        condition: service_healthy
    volumes:
      - './uploads:/zipline/uploads'
      - './public:/zipline/public'
      - './themes:/zipline/themes'
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://localhost:3000/api/healthcheck']
      interval: 15s
      timeout: 2s
      retries: 2

volumes:
  pgdata:
    1. Start the server:
    docker compose up -d

  4. Set up Zipline for Development

    trunk

    To develop on Zipline locally:

    Using Nix

    If you have Nix and direnv installed, run:

    direnv allow

    Or manually enter the nix shell:

    nix develop --no-pure-eval

    Manual Setup (Node/pnpm)

    Prerequisites: Node.js (20.x or 22.x), pnpm (10.x), and a PostgreSQL server.

    1. Create a .env file with required variables (CORE_SECRET, DATABASE_URL) and optional ones (CORE_PORT, DATASOURCE_TYPE, etc.).
    2. Install dependencies:
    pnpm install
    1. Start the development server:
    pnpm dev
    1. To build the production version:
    pnpm build
    1. To run the production version:
    pnpm start
    pnpm install
pnpm dev

  5. Configure Zipline Volumes

    trunk

    When running Zipline, ensure the following directories are correctly mapped via volumes:

    • ./uploads: Stores all user uploads (default). Temporary files are stored in ./uploads/.tmp. You can set CORE_TEMP_DIRECTORY to a different filesystem (like tmpfs) to improve upload performance.
    • ./public: Stores public assets. Must be mounted to /zipline/public.
    • ./themes: Stores custom themes. Must be mounted to /zipline/themes.

  6. Configure S3 Datasource

    trunk

    To use S3 instead of the local filesystem, set DATASOURCE_TYPE to s3 and provide the following credentials:

    DATASOURCE_TYPE=s3
DATASOURCE_S3_ACCESS_KEY_ID=access_key_id
DATASOURCE_S3_SECRET_ACCESS_KEY=secret
DATASOURCE_S3_BUCKET=zipline
DATASOURCE_S3_REGION=us-west-2

    If using a custom endpoint (other than AWS S3), also set DATASOURCE_S3_ENDPOINT.

    DATASOURCE_TYPE=s3

DATASOURCE_S3_ACCESS_KEY_ID=access_key_id
DATASOURCE_S3_SECRET_ACCESS_KEY=secret
DATASOURCE_S3_BUCKET=zipline
DATASOURCE_S3_REGION=us-west-2

  7. Configure Upload Storage and Network

    trunk

    You can customize the storage location and network binding using environment variables:

    Storage Location

    Set DATASOURCE_LOCAL_DIRECTORY to change the upload folder. If you change this, you must also update the volume mappings in your docker-compose.yml.

    DATASOURCE_LOCAL_DIRECTORY=/path/to/your/local/files
# or relative
DATASOURCE_LOCAL_DIRECTORY=./relative/path/to/files

    Port and Hostname

    By default, Zipline binds to 0.0.0.0:3000. Use CORE_PORT and CORE_HOSTNAME to change this. If you change the port, update the ports section in docker-compose.yml.

    CORE_PORT=80
CORE_HOSTNAME=localhost

  8. Manage Database Migrations (Development)

    trunk

    Zipline uses Prisma as its ORM. To manage schema changes:

    • Generate a migration file: After modifying prisma.schema, run pnpm db:migrate. This generates the file but does not apply it (Zipline applies migrations automatically on startup).
    • Push changes (Prototype only): To push changes directly to the database without a migration file (use for testing only, never in production), run pnpm db:prototype.
    pnpm db:migrate
pnpm db:prototype

  9. Configure Generator Options for Uploaders

    trunk

    When generating uploaders (like Flameshot, ShareX, or Shell Scripts), you can customize the behavior using several options. These options affect how files are named, how they are compressed, and how the generated configuration interacts with your operating system or specific apps.

    File Upload Options

    • format: The naming convention for uploaded files. Options include default, random, date, uuid, name (use file name), or gfycat (Gfycat-style name).
    • imageCompressionPercent: A number (0-100) to set the compression level for images. Leave blank to disable.
    • maxViews: The maximum number of views allowed before a file/URL is deleted. Leave blank for unlimited views.
    • addOriginalName: If enabled, the original file name is preserved for downloading, though the format option still dictates the storage name.
    • overrides_returnDomain: Allows you to specify a specific domain to be returned in your uploads, overriding the server default.
    • noJson: (Internal/Config) Controls JSON output format.

    App-Specific Compatibility

    • sharex_xshareCompatibility: Specifically for the Xshare app on Android. Enables compatibility by changing JSON formatting (e.g., {json:...} to $json:...$). Note that enabling this may prevent the config from working with standard ShareX.

    OS & Clipboard Compatibility (Unix-like systems)

    • wl_enableCompatibility: Uses wl-copy instead of xclip for Wayland environments.
    • mac_enableCompatibility: Uses pbcopy instead of xclip for macOS.
    • wl_compositorUnsupported: For users on compositors like Hyprland, this sets XDG_CURRENT_DESKTOP=sway to resolve Flameshot errors on Wayland.
    • unix_useEcho: Instead of copying the URL to the clipboard, the generator will simply output the URL to the terminal via echo.

  10. Configure OAuth and Authentication

    trunk

    Zipline supports multiple OAuth providers and MFA.

    OAuth Providers

    For each provider, you can configure clientId, clientSecret, and redirectUri. Supported providers include:

    • discord
    • github
    • google
    • oidc (OpenID Connect, requires authorizeUrl, userinfoUrl, and tokenUrl)

    Multi-Factor Authentication (MFA)

    • mfa.totp: Enable TOTP with a custom issuer (default: 'Zipline').
    • mfa.passkeys: Enable passkeys. Requires rpID (must be alphanumeric, dots, or hyphens) and origin (must be a valid http or https URL).

  11. Configure File and URL Routing

    trunk

    Customize how files and shortened URLs are served.

    Files

    • files.route: The URL prefix for files (default: /u).
    • files.maxFileSize: Maximum allowed file size (default: 100mb).
    • files.defaultFormat: The default naming format (random, date, uuid, name, gfycat, or random-words).
    • files.disabledTypes: An array of MIME types to disable (must follow type/subtype format).
    • files.disabledExtensions: An array of file extensions to disable.
    • files.maxFilesPerUpload: Maximum number of files in a single upload (default: 1000).

    URLs (Shortlinks)

    • urls.route: The URL prefix for shortlinks (default: /go).
    • urls.length: The length of the generated shortlink (default: 6).

  12. Configure Zipline Datasource (Local vs S3)

    trunk

    Zipline supports two types of data storage: local or s3.

    Local Storage

    Set datasource.type to 'local'.

    • local.directory: The directory where files are stored (default: ./uploads).

    S3 Storage

    Set datasource.type to 's3'. You must provide the following fields:

    • s3.accessKeyId
    • s3.secretAccessKey
    • s3.region
    • s3.bucket
    • s3.endpoint (optional)
    • s3.forcePathStyle (optional, default: false)
    • s3.subdirectory (optional)