Skip to main content
Installing Zipline from source gives you full control over the build process and is ideal for development, contributing, or running custom modifications.

​
Prerequisites

Before installing from source, ensure you have:
  • Node.js 22.x or later (LTS recommended)
  • pnpm 10.x or later
  • PostgreSQL 16 or later
  • FFmpeg (optional, for video thumbnail generation)
If you use Nix with direnv, you can skip manual dependency installation. See the development with Nix section.

​
Installation

1

Clone the repository

git clone https://github.com/diced/zipline.git
cd zipline
2

Install dependencies

Install all required packages using pnpm:
pnpm install
3

Configure environment

Create a .env file with your configuration. Here’s a complete example:
.env
# Enable debug logging (optional)
DEBUG=zipline

# Required: 32+ character secret for encryption
CORE_SECRET="your-secret-that-is-32-characters-long-minimum"

# Required: PostgreSQL connection
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zipline?schema=public"

# Optional: Server configuration
CORE_PORT=3000
CORE_HOSTNAME=0.0.0.0

# Required: Choose datasource type
DATASOURCE_TYPE="local"
# DATASOURCE_TYPE="s3"

# If DATASOURCE_TYPE=local
DATASOURCE_LOCAL_DIRECTORY="./uploads"

# If DATASOURCE_TYPE=s3
# DATASOURCE_S3_ACCESS_KEY_ID="your-access-key-id"
# DATASOURCE_S3_SECRET_ACCESS_KEY="your-secret-access-key"
# DATASOURCE_S3_REGION="us-west-2"
# DATASOURCE_S3_BUCKET="zipline"
# DATASOURCE_S3_ENDPOINT="https://s3.example.com"  # Optional: for non-AWS providers
The CORE_SECRET must be at least 32 characters long. Generate a secure random string:
openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32
4

Start development server

Run Zipline in development mode with hot reload:
pnpm dev
The server will start on http://localhost:3000 (or your configured port).

​
Building for production

To build and run Zipline in production mode: 
pnpm build
The build process compiles both the server and client code. The output is placed in the build/ directory.

​
Development with Nix

If you have Nix and direnv installed, setup is even simpler: 
direnv allow
Your shell will automatically be configured with all dependencies.

​
Useful Nix commands

The Nix environment provides helpful commands for development:
CommandDescription
pgupStarts PostgreSQL server in the background
pg_ctl statusCheck if PostgreSQL is running
minioupStart a Minio server for testing S3
downallStop all running PostgreSQL and Minio services

​
Database management

Zipline uses Prisma as its ORM. Here are common database operations:

​
Making schema changes

After modifying prisma/schema.prisma, create a migration: 
pnpm db:migrate
This generates a migration file but doesn’t apply it. Zipline automatically applies migrations on startup.

​
Prototyping changes

For testing schema changes without creating migrations: 
pnpm db:prototype
Only use db:prototype for development. Never use it in production.

​
Code quality

Zipline enforces code quality standards. Before submitting changes:

​
Validate and format

pnpm validate
This runs:
  • ESLint for code linting
  • Prettier for code formatting
  • TypeScript type checking
The build will fail if code doesn’t pass validation. Always run pnpm validate before committing.

​
Using zipline-ctl

Zipline includes a command-line tool for administrative tasks: 
pnpm build:server

​
Available scripts

Here are all available npm scripts:
  • pnpm dev - Start development server with debug logging
  • pnpm dev:nd - Start development server without debug logging
  • pnpm dev:inspector - Start with Node.js inspector on port 9229
  • pnpm build - Build for production
  • pnpm start - Run production server
  • pnpm start:inspector - Run production server with inspector
  • pnpm db:migrate - Create a new migration
  • pnpm db:prototype - Push schema changes without migration
  • pnpm validate - Run linting, formatting, and type checking
  • pnpm ctl - Run zipline-ctl commands
  • pnpm build:server - Build the server and CLI

​
Troubleshooting

​
Build fails with validation errors

Run pnpm validate to identify and fix linting or formatting issues.

​
Database connection errors

  1. Verify PostgreSQL is running
  2. Check your DATABASE_URL in .env
  3. Ensure the database exists: createdb zipline

​
Module not found errors

  1. Delete node_modules and pnpm-lock.yaml
  2. Run pnpm install again
  3. Clear Prisma client: rm -rf node_modules/.prisma

​
Port already in use

Change the CORE_PORT in your .env file to an available port.

​
Next steps

First steps

Create your admin account and configure basic settings

Configuration

Explore all configuration options

Contributing

Learn how to contribute to Zipline

API reference

Explore the Zipline API

Build docs developers (and LLMs) love

Get started for freeTalk to us