Skip to content

Installation

Requirements

  • Python 3.10+
  • Django 4.2+
  • Pillow (for card preview rendering)

Piggyback is published on PyPI as pypiggyback:

pip install pypiggyback

Pin a version for reproducible builds:

pip install "pypiggyback==0.1.0"

Optional extras:

pip install "pypiggyback[docker]"   # Gunicorn + PostgreSQL driver for Docker/production

The pip package name is pypiggyback; the Django app you add to INSTALLED_APPS is piggyback.

Django setup

Add to your settings.py:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "rest_framework",
    "django_filters",
    "piggyback",
]

# Optional Piggyback settings
PIGGYBACK_PUBLIC_URL = "https://cards.yoursite.com"
PIGGYBACK_ECARD_PRICE = 299          # pence
PIGGYBACK_POSTED_CARD_PRICE = 399
PIGGYBACK_REMINDER_DAYS_BEFORE = [7, 3, 1]

Wire up URLs:

from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("piggyback.urls")),
]

Run migrations and load sample data:

python manage.py migrate
python manage.py load_sample_data
python manage.py createsuperuser
python manage.py runserver

Visit http://localhost:8000 — browse the card shop, open the editor, and sign in via /admin/login/ to save and send.

Install from source

For development or contributing:

git clone https://github.com/kurtisrogers/piggyback.git
cd piggyback
pip install -e ".[dev]"

See the Quick Start guide and Contributing for the full dev workflow.

Media files

Piggyback uses ImageField for templates, previews, and uploads. Configure media in development:

MEDIA_URL = "media/"
MEDIA_ROOT = BASE_DIR / "media"

Email delivery

For e-cards, configure Django's email backend:

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.example.com"
# ...

In development, use the console backend to see emails in your terminal:

EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"

Upgrading

pip install --upgrade pypiggyback
python manage.py migrate

Check the PyPI release history for version notes.