Core

DATABASE_URL

Zipline requires a database connection, supplied through DATABASE_URL or all five PostgreSQL variables below. DATABASE_URL can be a PostgreSQL connection string or a PGlite directory.

DATABASE_URL=postgresql://user:password@localhost:5432/zipline

If you prefer, you can also set the individual components of the connection string using the following environment variables: DATABASE_NAME, DATABASE_USERNAME, DATABASE_PASSWORD, DATABASE_HOST, and DATABASE_PORT.

DATABASE_NAME=zipline
DATABASE_USERNAME=user
DATABASE_PASSWORD=password
DATABASE_HOST=localhost
DATABASE_PORT=5432

PGlite

PGlite stores the database in a local directory without a separate PostgreSQL server. Use an absolute path, not a relative path or a server address:

DATABASE_URL=pglite:///var/lib/zipline/database

The directory must be writable by Zipline. It stores the database, not uploaded files; keep your datasource configured separately.

For Docker, the path is inside the container. Mount persistent storage so that recreating the container does not lose the database. For example, merge these settings into the zipline service, keeping its other environment variables and upload volumes:

services:
  zipline:
    environment:
      DATABASE_URL: pglite:///zipline/data/database
    volumes:
      - './data:/zipline/data'

A new PGlite instance does not need the PostgreSQL service or its depends_on entry. If you already have data in PostgreSQL, follow Migrating to PGlite before changing the connection; changing the URL alone does not copy your data.

To back up PGlite, stop Zipline before copying the entire database directory, and keep it stopped until the copy finishes. Back up uploaded files separately. To restore, use the saved directory while Zipline is stopped and point DATABASE_URL at it.

CORE_HOSTNAME

CORE_HOSTNAME is an optional environment variable that specifies the hostname that Zipline will bind to, it defaults to 0.0.0.0. If using Docker, you can set this to 0.0.0.0 so that you can access Zipline from outside the container (with a exposed port).

If you want to listen on a UNIX socket, like /tmp/zipline.sock you can do so by setting this environment variable to the path to a socket. The CORE_PORT variable still needs to be set, but will obviously have no effect.

CORE_HOSTNAME=127.0.0.1
CORE_HOSTNAME=0.0.0.0

CORE_PORT

CORE_PORT is an optional environment variable that specifies the port that Zipline will bind to, it defaults to 3000.

CORE_PORT=3000

CORE_SECRET

CORE_SECRET is a required environment variable that is used to sign website cookies, and should be kept private. It is recommended to generate this value using a password manager, or with the following command:

openssl rand -base64 32 # 32 is the length, you can change this

CORE_SECRET="p5g9NUcnpSbSl+N/70rlv+YXcoL5X0LA6fTc8Anz74w="

CORE_SECRET_FILE=/run/secrets/core_secret