ZineCore2
Getting Started

Installation

Step-by-step guide to setting up the ZineCore2 reference implementation

This guide will walk you through installing and running the ZineCore2 Django REST API server on your local machine or server.

Prerequisites

Before you begin, ensure you have:

    • Python 3.12+ installed
    • PostgreSQL 16+ installed and running
    • Git for cloning the repository
    • Basic command-line skills
    • macOS or Linux (Windows via WSL2)

Check Prerequisites

# Check Python version
python3 --version
# Should output: Python 3.12.x or higher

# Check PostgreSQL version
psql --version
# Should output: psql (PostgreSQL) 16.x or higher

# Check Git
git --version
# Should output: git version 2.x

Installation Methods

Choose your preferred installation method:

Quick Start (Onboarding Script)

The easiest way to get started is using the interactive onboarding script.

Step 1: Clone the Repository

git clone https://github.com/ZineCore2/server.git
cd server/

Step 2: Initialize Submodules

The spec repository is included as a git submodule:

git submodule update --init

This downloads the ZineCore2 specification into spec/.

Step 3: Run Onboarding

The onboarding script will guide you through setup:

./onboarding.sh

The script will:

  1. ✅ Check that Python 3.12+ is installed
  2. ✅ Check that PostgreSQL is running
  3. ✅ Install uv package manager (if needed)
  4. ✅ Create Python virtual environment (.venv/)
  5. ✅ Install all dependencies
  6. ✅ Create PostgreSQL database
  7. ✅ Run database migrations
  8. ✅ Load controlled vocabularies
  9. ✅ Load geographic data (GeoNames)
  10. ✅ Load language codes (ISO 639)
  11. ✅ Create superuser account

Follow the prompts — the script will ask for:

  • PostgreSQL credentials (default: localhost:5433)
  • Database name (default: zinecore2)
  • Superuser username and password

Step 4: Start the Server

./start.sh

The server will start at http://localhost:8000.

Step 5: Verify Installation

Open your browser to:

You should see the Django REST Framework browsable API.

Success! Your ZineCore2 server is running. Continue to First Steps to create your first records.

Manual Installation

For advanced users who want step-by-step control.

Step 1: Clone Repository

git clone https://github.com/ZineCore2/server.git
cd server/
git submodule update --init

Step 2: Install uv Package Manager

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew
brew install uv

# Or via pip (not recommended)
pip install uv

Step 3: Create Virtual Environment

# From project root
uv venv

# Activate virtual environment
source .venv/bin/activate

Step 4: Install Dependencies

# Install all dependencies (including dev dependencies)
uv sync

# Or install only production dependencies
uv sync --no-dev

This installs dependencies from both:

  • pyproject.toml (workspace root - includes textual for onboarding TUI)
  • backend/pyproject.toml (Django app dependencies)

Step 5: Create PostgreSQL Database

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE zinecore2;

# Create user (optional)
CREATE USER zinecore2 WITH PASSWORD 'yourpassword';
GRANT ALL PRIVILEGES ON DATABASE zinecore2 TO zinecore2;

# Exit psql
\q

Step 6: Configure Environment

Create a .env file in the backend/ directory:

# backend/.env
DJANGO_SETTINGS_MODULE=zinecore.settings.development
DATABASE_URL=postgresql://zinecore2:yourpassword@localhost:5433/zinecore2
SECRET_KEY=your-secret-key-here-change-in-production
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

Generate a secret key:

python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Step 7: Run Migrations

cd backend/

# Run migrations
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py migrate

Step 8: Load Data

Load vocabularies, geographic data, and language codes:

# Load GeoNames geographic data (must run first)
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py load_geonames

# Load controlled vocabularies from spec
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py load_vocabularies

# Load ISO 639 language codes
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py load_languages

# Load ISO 3166 country codes
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py load_countries

Order matters: Run load_geonames first, as some vocabularies reference geographic data.

Step 9: Create Superuser

DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py createsuperuser

Follow the prompts to set username, email, and password.

Step 10: Start Development Server

DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py runserver

Server runs at http://localhost:8000.

Docker Installation

For containerized deployment.

Step 1: Clone Repository

git clone https://github.com/ZineCore2/server.git
cd server/
git submodule update --init

Step 2: Start PostgreSQL with Docker Compose

The project includes a docker-compose.yml for PostgreSQL:

docker-compose up -d

This starts PostgreSQL on localhost:5433.

Step 3: Build Django Container (Optional)

Create a Dockerfile in the project root:

FROM python:3.12-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    postgresql-client \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install uv
RUN pip install uv

# Set working directory
WORKDIR /app

# Copy project files
COPY . .

# Initialize submodules
RUN git submodule update --init

# Install dependencies
RUN uv sync --no-dev

# Expose port
EXPOSE 8000

# Run migrations and start server
CMD ["sh", "-c", "cd backend && ../venv/bin/python manage.py migrate && ../venv/bin/python manage.py runserver 0.0.0.0:8000"]

Build and run:

# Build image
docker build -t zinecore2-server .

# Run container
docker run -p 8000:8000 \
  -e DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  -e DATABASE_URL=postgresql://postgres:[email protected]:5433/zinecore2 \
  zinecore2-server

Troubleshooting

PostgreSQL Connection Issues

Error: FATAL: password authentication failed

Solution: Check your PostgreSQL credentials in .env or environment variables.

# Test connection
psql -U zinecore2 -h localhost -p 5433 -d zinecore2

Error: could not connect to server: Connection refused

Solution: Ensure PostgreSQL is running:

# macOS (Homebrew)
brew services start postgresql@16

# Linux (systemd)
sudo systemctl start postgresql

# Check status
pg_isready

Python Version Issues

Error: Python 3.12 or higher required

Solution: Install Python 3.12+ via:

# macOS
brew install [email protected]

# Ubuntu/Debian
sudo apt install python3.12

# Or use pyenv
pyenv install 3.12.0
pyenv local 3.12.0

uv Installation Issues

Error: uv: command not found

Solution: Ensure ~/.cargo/bin is in your PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Migration Errors

Error: django.db.utils.ProgrammingError: relation does not exist

Solution: Ensure migrations are run in correct order:

# Drop and recreate database (WARNING: loses all data)
psql -U postgres -c "DROP DATABASE zinecore2;"
psql -U postgres -c "CREATE DATABASE zinecore2;"

# Run migrations again
cd backend/
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py migrate

Vocabulary Loading Errors

Error: ValueError: GeoPlace matching query does not exist

Solution: Load GeoNames data before vocabularies:

# Correct order:
cd backend/
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py load_geonames

DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../venv/bin/python manage.py load_vocabularies

Verification Checklist

After installation, verify everything works:

  • Server starts without errors
  • Admin interface loads at /admin/
  • API root loads at /api/
  • Can log in to admin with superuser account
  • Vocabularies are loaded (check /api/vocabularies/)
  • Can create a test zine record via admin interface
  • API returns JSON responses

Next Steps

Now that your server is running:

Installation complete! Your ZineCore2 server is ready. Continue to First Steps to start cataloging zines.

Reference Implementation

Django REST API server for ZineCore2 metadata

First Steps

Create your first ZineCore2 records via the API

Copyright ©2026 ZineCore2 Contributors,