Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cgwire/zou/llms.txt

Use this file to discover all available pages before exploring further.

​
Installing Zou

This guide walks you through setting up a Zou instance from scratch. You’ll install the required dependencies, configure the database, and prepare the API for first use.

​
Prerequisites

1

Python 3.10 or higher

Zou supports Python 3.10 through 3.14. Verify your Python version:
python3 --version
If you need to install Python, visit python.org.
2

PostgreSQL 12 or higher

Zou requires PostgreSQL as its primary database. Install PostgreSQL for your platform:
sudo apt update
sudo apt install postgresql postgresql-contrib
Verify PostgreSQL is running:
psql --version
3

Redis (Optional but Recommended)

Redis is used for caching and token management. While optional for development, it’s required for production.
sudo apt install redis-server
sudo systemctl start redis-server
Test Redis connection:
redis-cli ping
# Should return: PONG

​
Database Setup

1

Create PostgreSQL Database

Connect to PostgreSQL and create the Zou database:
# Switch to postgres user (Linux)
sudo -u postgres psql

# Or connect directly (macOS/Windows)
psql -U postgres
Then create the database:
CREATE DATABASE zoudb;
CREATE USER zouuser WITH ENCRYPTED PASSWORD 'mysecretpassword';
GRANT ALL PRIVILEGES ON DATABASE zoudb TO zouuser;
\q
Choose a strong password for production deployments and store it securely.
2

Configure Database Connection

Zou uses environment variables for configuration. Set these before running the application:
export DB_HOST=localhost
export DB_PORT=5432
export DB_USERNAME=zouuser
export DB_PASSWORD=mysecretpassword
export DB_DATABASE=zoudb
export DB_DRIVER=postgresql+psycopg
For persistent configuration, add these to your shell profile (~/.bashrc, ~/.zshrc) or use a .env file with a process manager.

​
Install Zou

1

Install via pip

Install Zou from PyPI:
pip install zou
This will install Zou and all its dependencies listed in setup.cfg:
  • Flask and extensions (Flask-JWT-Extended, Flask-SQLAlchemy, etc.)
  • Database drivers (psycopg 3.x)
  • Background job processing (RQ, Redis)
  • Media processing (ffmpeg-python, Pillow, OpenCV)
  • And many more production-ready libraries
Zou has over 50 dependencies. Installation may take a few minutes.
2

Verify Installation

Check that Zou was installed correctly:
zou version
You should see output like:
Zou version: 1.0.15

​
Environment Configuration

Zou is configured entirely through environment variables. Here are the essential settings:

​
Required Settings

# Database Configuration
export DB_HOST=localhost
export DB_PORT=5432
export DB_USERNAME=zouuser
export DB_PASSWORD=mysecretpassword
export DB_DATABASE=zoudb

# Security
export SECRET_KEY="your-secret-key-here-min-32-chars"

# Redis (Key-Value Store)
export KV_HOST=localhost
export KV_PORT=6379

​
Optional Settings

# Enable debug mode
export DEBUG=true
export DEBUG_HOST=127.0.0.1
export DEBUG_PORT=5000

# Mail (disabled for dev)
export MAIL_ENABLED=false
For a complete list of configuration options, see the zou/app/config.py file in the source code.

​
Initialize the Database

1

Run Database Migrations

Initialize the database schema:
zou init-db
Output:
Creating database and tables...
Database and tables created.
This command runs all Flask-Migrate migrations to create the required tables.
2

Initialize Default Data

Populate the database with essential data (task statuses, file statuses, etc.):
zou init-data
This creates:
  • Default task statuses (Todo, Work In Progress, Done, etc.)
  • Default file statuses
  • Default project settings
  • System metadata descriptors
3

Create Admin User

Create your first admin user:
zou create-admin admin@example.com --password YourSecurePassword123
Output:
Admin successfully created.
Use a strong password for the admin account. This user has full access to all production data.
4

Verify Database Status

Check that the database is ready:
zou is-db-ready
Output:
Database is initialized.

​
Additional Dependencies

​
FFmpeg (Required for Preview Processing)

Zou uses FFmpeg to process video previews and generate thumbnails. 
sudo apt update
sudo apt install ffmpeg
Verify FFmpeg installation: 
ffmpeg -version

​
Meilisearch (Optional - Search Indexing)

For full-text search capabilities, install Meilisearch: 
# Download and run Meilisearch
curl -L https://install.meilisearch.com | sh
./meilisearch --master-key=your_master_key
Configure Zou to use it: 
export INDEXER_HOST=localhost
export INDEXER_PORT=7700
export INDEXER_KEY=your_master_key

​
Upgrading Zou

To upgrade an existing Zou installation:
1

Update the Package

pip install --upgrade zou
2

Run Database Migrations

zou upgrade-db
This applies any new database schema changes.
3

Restart Services

Restart your Zou server and any background workers.

​
Common Configuration Examples

​
Using a .env File

Create a .env file for your configuration: 
# .env
DB_HOST=localhost
DB_USERNAME=zouuser
DB_PASSWORD=mysecretpassword
DB_DATABASE=zoudb
SECRET_KEY=your-secret-key-at-least-32-characters-long
KV_HOST=localhost
KV_PORT=6379
DEBUG=false
Load it before starting Zou: 
set -a && source .env && set +a

​
Docker Compose

For containerized deployments, see the CGWire Docker setup repository.

​
Next Steps

Now that Zou is installed and configured, proceed to the Quick Start guide to run the server and make your first API request.

Build docs developers (and LLMs) love

Get started for freeTalk to us