Deploying Zipline

Introduction

Zipline is a modern, self-hosted image and file hosting solution designed to work seamlessly with ShareX and other screenshot/upload tools. It provides a fast, feature-rich platform for uploading, organizing, and sharing images, files, and text pastes.

Built with Next.js and designed for performance, Zipline offers a beautiful dashboard interface, powerful organization features, and extensive customization options. It’s the perfect solution for individuals and teams who want control over their file hosting without relying on third-party services.

Key highlights of Zipline:

• ShareX Compatible: Full integration with ShareX for screenshot and file uploads
• Multiple Upload Types: Support for images, videos, files, text pastes, and URLs
• Modern Dashboard: Beautiful, responsive interface for managing uploads
• User Management: Multi-user support with roles and permissions
• Folder Organization: Organize uploads into folders and collections
• Custom Domains: Vanity URLs for your uploads
• Embed Configuration: Customizable OpenGraph embeds for Discord and social media
• Statistics: Detailed upload and view statistics
• URL Shortening: Built-in URL shortener functionality
• OAuth Integration: Support for Discord, GitHub, and other OAuth providers
• Invites System: Control user registration with invite codes
• Themes: Light and dark mode with customizable themes

This guide walks through deploying Zipline on Klutch.sh using Docker, providing you with a powerful self-hosted file hosting platform.

Why Deploy Zipline on Klutch.sh

Deploying Zipline on Klutch.sh provides several advantages for file hosting:

Full Control: Host your own files without storage limits or terms of service restrictions.

HTTPS by Default: Automatic SSL certificates for secure file uploads and access.

Persistent Storage: Reliable storage for all your uploaded files and database.

GitHub Integration: Deploy updates automatically when you push configuration changes.

Custom Domains: Use your own domain for a branded file hosting experience.

Scalable Resources: Allocate storage and compute based on your needs.

Prerequisites

Before deploying Zipline on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic understanding of Docker and containerization
• ShareX or another compatible upload tool (optional)
• (Optional) A custom domain for your Zipline instance

Understanding Zipline Architecture

Zipline consists of several components:

Next.js Application: The main application handling the web interface and API.

PostgreSQL Database: Stores user data, file metadata, and configuration.

File Storage: Local or S3-compatible storage for uploaded files.

Background Jobs: Handle image processing and cleanup tasks.

Preparing Your Repository

Create a GitHub repository for your Zipline deployment.

Repository Structure

zipline-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for Zipline:

FROM ghcr.io/diced/zipline:latest

# Environment variables
ENV CORE_SECRET=${CORE_SECRET}
ENV CORE_DATABASE_URL=${DATABASE_URL}
ENV CORE_HOSTNAME=0.0.0.0
ENV CORE_PORT=3000

# Optional: Configure upload settings
ENV UPLOADER_DEFAULT_FORMAT=DATE
ENV UPLOADER_ROUTE=/u
ENV UPLOADER_LENGTH=6
ENV UPLOADER_DEFAULT_EXPIRATION=never

# Optional: Configure features
ENV FEATURES_INVITES=true
ENV FEATURES_USER_REGISTRATION=false
ENV FEATURES_OAUTH_REGISTRATION=false

# Optional: Configure URLs
ENV URLS_ROUTE=/go
ENV URLS_LENGTH=6

# Expose port
EXPOSE 3000

# The base image includes the default entrypoint

Environment Variables Reference

Variable	Required	Default	Description
CORE_SECRET	Yes	-	Secret key for encryption (generate with openssl rand -hex 32)
CORE_DATABASE_URL	Yes	-	PostgreSQL connection string
CORE_HOSTNAME	No	0.0.0.0	Hostname to bind
CORE_PORT	No	3000	Port for the web server
UPLOADER_DEFAULT_FORMAT	No	DATE	Default filename format
UPLOADER_ROUTE	No	/u	Route for file uploads
UPLOADER_LENGTH	No	6	Length of generated URLs
FEATURES_INVITES	No	true	Enable invite system
FEATURES_USER_REGISTRATION	No	false	Allow public registration

Deploying Zipline on Klutch.sh

Generate Your Secret Key

Create a secure secret for Zipline:

openssl rand -hex 32

Save this key for the environment variables configuration.

Push Your Repository to GitHub

Initialize and push your configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “zipline” or “file-host”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP for the web interface:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Configure the following:

Variable	Value
CORE_SECRET	Your generated secret key
CORE_DATABASE_URL	PostgreSQL connection string
FEATURES_USER_REGISTRATION	false (enable after initial setup)

Attach Persistent Volumes

Add storage for uploads and database:

Mount Path	Recommended Size	Purpose
/zipline/uploads	50+ GB	Uploaded files
/zipline/public	1 GB	Public assets

Deploy Your Application

Click Deploy to build and start Zipline.

Access Zipline

Once deployment completes, access your instance at https://your-app-name.klutch.sh.

Initial Setup

First-Time Configuration

1. Navigate to your Zipline instance
2. The first user to register becomes the administrator
3. Go to Settings to configure your preferences

Creating Admin Account

On first launch:

1. Click “Register” to create your admin account
2. Choose a secure username and password
3. After registration, disable public registration in settings

Configuring Upload Settings

Customize upload behavior:

1. Navigate to Dashboard > Settings > Uploader
2. Configure filename format (DATE, RANDOM, UUID)
3. Set maximum file size and allowed types
4. Configure expiration defaults

ShareX Integration

Generating ShareX Configuration

1. Log in to Zipline
2. Navigate to Dashboard > Settings > ShareX
3. Click “Generate Config”
4. Download the .sxcu file
5. Import into ShareX

ShareX Setup

1. Open ShareX
2. Go to Destinations > Custom Uploader Settings
3. Import the Zipline configuration
4. Set Zipline as your default image uploader

Testing Upload

1. Take a screenshot with ShareX
2. Verify it uploads to your Zipline instance
3. Check that the URL is copied to clipboard

Managing Files

Dashboard Features

The Zipline dashboard provides:

• Grid and list views for uploads
• Search and filter functionality
• Bulk operations (delete, move, export)
• Preview for images and videos
• Statistics and analytics

Organizing with Folders

Create folders to organize uploads:

1. Navigate to Dashboard > Folders
2. Create new folders for categories
3. Move uploads between folders
4. Share folders with other users

URL Shortening

Use the built-in URL shortener:

1. Navigate to Dashboard > URLs
2. Enter the long URL
3. Optionally customize the short code
4. Share the shortened URL

Customization

Themes

Customize the appearance:

1. Go to Dashboard > Settings > Appearance
2. Choose light or dark mode
3. Select accent colors
4. Configure embed colors for social media

Embed Configuration

Customize OpenGraph embeds for Discord and social media:

1. Navigate to Settings > Embed
2. Set embed title, description, and color
3. Configure site name and author
4. Preview embeds before saving

Troubleshooting Common Issues

Uploads Failing

Solutions:

• Check file size limits in configuration
• Verify storage volume has sufficient space
• Review logs for specific error messages
• Confirm ShareX token is correct

Images Not Displaying

Solutions:

• Verify the upload route configuration
• Check that the uploads volume is correctly mounted
• Review nginx/proxy configuration

ShareX Connection Issues

Solutions:

• Regenerate the ShareX configuration
• Verify the API token is current
• Check that HTTPS is working correctly

Additional Resources

• Zipline Documentation
• Zipline GitHub Repository
• Zipline Discord Community
• ShareX Official Website

Conclusion

Deploying Zipline on Klutch.sh gives you a powerful, self-hosted file hosting platform with seamless ShareX integration. With its modern dashboard, extensive customization options, and multi-user support, Zipline provides everything you need for hosting and sharing images, files, and URLs on infrastructure you control.