kit·intermediate·updated 2026-07-13

PDFCraft – PDF Processing & Automation Kit

Your PDFs, organized, annotated, and searchable — self-hosted.

DjangoHTMXPostgreSQL

A self-hosted PDF vault — upload and organize documents into collections, annotate with highlights and notes, share with your team, and lock it down with WebAuthn/TOTP, all backed by Django and PostgreSQL.

Install

~60 seconds

terminal

bash

git clone https://github.com/yashthakur1/PdfDing_8.git pdfcraft
cd pdfcraft
poetry install

~/ what's inside

Already wired, so you can skip to features.

Smart collections

Organize PDFs into collections instead of one long flat document list.

Annotation & highlights

Mark up PDFs with highlights and notes directly in the browser.

WebAuthn & TOTP

Lock the vault down with passkeys or two-factor auth, not just a password.

Team sharing

Share individual documents or whole collections with teammates.

~/ the stack behind it

Every dependency has a reason.

Django 5
Python backend, auth, and admin — server-rendered with HTMX for interactivity.
HTMX + Alpine.js
Dynamic UI without a separate frontend build step or SPA framework.
Tailwind CSS
Utility-first styling for the document grid, viewer, and collections UI.
PostgreSQL / SQLite
Postgres for production, SQLite for zero-config local development.

~/ environment

Here's every env var, labeled.

Copy to .env.local. The included first-run script refuses to boot if any of them are missing — you'll know immediately.

.env.example

dotenv

DEBUG=True
SECRET_KEY=your-super-secret-development-key
DATABASE_TYPE=SQLITE

~/ walkthrough

Zero to first deploy.

This is the exact sequence we'd run from a blank directory. Steps are reproducible — if one fails, we want to know.

1. Install backend dependencies
Use Poetry (recommended) or pip to install the Django backend's dependencies.
```
poetry install
# or
pip install -r requirements.txt
```

2. Configure the database

SQLite works out of the box for local dev. For Postgres, create the database yourself first, point the POSTGRES_* env vars at it, then run migrations.

# .env for Postgres
DATABASE_TYPE=POSTGRES
POSTGRES_NAME=docvault
POSTGRES_USER=youruser
POSTGRES_PASSWORD=yourpassword
POSTGRES_HOST=127.0.0.1
POSTGRES_PORT=5432

python manage.py migrate

3. Build the frontend and run the server
Install and build the Tailwind/HTMX frontend assets, then start the Django dev server from the pdfding directory.
```
npm install
npm run build
cd pdfding
python manage.py runserver
```

~/ known gotchas

The stuff that ate our afternoons.

Things we'd have wanted a heads-up on. Logged as we hit them.

!DEBUG=True is for local dev only — set it to False and configure a real SECRET_KEY before production.
!Switching to Postgres means creating the database yourself first — the app won't create it for you.
!The Django server expects frontend assets already built (npm run build) — skip that step and the UI serves unstyled or broken pages.

when not

If you just need to view or convert a couple of PDFs, this is overkill — accounts, collections, and WebAuthn add real setup (Django + Postgres + a frontend build) for something a simple PDF viewer does with zero setup. This kit is for teams that want a private, self-hosted document vault.

license: Not specified — the source repo ships no LICENSE file. Confirm terms with the author before redistributing.·star on github →

Got stuck, or want this shipped end-to-end for you? bitroot.club builds custom products for founders. →