hyprcrd/README.md

hyprcrd

A self-hosted card/note manager with markdown, tags, image galleries, and Obsidian-compatible export.

Requirements

• PHP 8.3+
• Apache with mod_rewrite
• PHP extensions: pdo_sqlite, zip

No external dependencies. All frontend libraries load from CDN.

Quick Start (Docker)

git clone https://git.uesome.de/tanztee/hyprcrd.git
cd hyprcrd
docker build -t hyprcrd .
docker run -d -p 8080:80 -v hyprcrd-data:/var/www/html/data hyprcrd

Open http://localhost:8080 and set your password on first visit.

The -v hyprcrd-data:/var/www/html/data flag persists the database across container restarts.

Manual Installation

1. Clone

git clone https://git.uesome.de/tanztee/hyprcrd.git
cd hyprcrd

2. Set document root

Point your web server's document root to the public/ directory.

Apache vhost example:

<VirtualHost *:80>
    ServerName hyprcrd.local
    DocumentRoot /path/to/hyprcrd/public

    <Directory /path/to/hyprcrd/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Make sure mod_rewrite is enabled:

a2enmod rewrite
systemctl restart apache2

3. Set permissions

mkdir -p data public/uploads
chmod 755 data
chmod 777 public/uploads

The web server user (e.g. www-data) needs write access to both directories.

4. PHP settings (optional)

For larger image uploads, adjust in php.ini:

upload_max_filesize = 20M
post_max_size = 22M

5. Open and set password

Navigate to your URL. On first visit, you'll be prompted to set a password (min. 4 characters). That's it.

Directory Structure

hyprcrd/
├── config.php              # App constants (auto-configured)
├── Dockerfile
├── docker-entrypoint.sh
├── src/
│   ├── bootstrap.php       # Initialization
│   └── Database.php        # SQLite schema & migrations
├── public/                 # Document root
│   ├── index.php           # Entry point & API
│   ├── .htaccess           # URL rewriting
│   ├── css/style.css
│   ├── js/
│   │   ├── app.js          # Orchestrator
│   │   └── modules/        # Feature modules
│   └── uploads/            # User media (writable)
└── data/
    └── hyprcrd.db          # SQLite database (auto-created)

Features

• Cards with markdown body, color, tags, and position
• Buckets for organizing cards into groups
• Tags written as #tagname or hierarchical #parent/child in card body, extracted automatically
• Markdown with [[Card Title]] wiki-links, ```gallery image galleries, ```tree list views
• Search combining text and #tag filters (e.g. #project meeting notes)
• Image gallery with orphan detection and fullscreen viewer
• Split view showing tag-related and content-related cards
• Import/Export as JSON+media ZIP or Obsidian/Logseq-compatible markdown vault
• Drag & drop card reordering and grouping
• Keyboard shortcuts: Ctrl+K search, Shift+scroll zoom, arrow keys in autocomplete

Data & Backup

All data lives in two places:

• data/hyprcrd.db — SQLite database (cards, buckets, settings)
• public/uploads/ — uploaded images and audio

Back up both to preserve everything. The database auto-migrates on startup.

Export Formats

• JSON export (export button) — full backup with media, re-importable
• Markdown vault (vault button) — Obsidian/Logseq-compatible structure:

  Bucket Name/
    Card Title.md      # YAML frontmatter + markdown body
  attachments/
    image.jpg
  

Security

• Bcrypt password hashing
• CSRF protection on all mutations
• Rate-limited login (5 attempts/60s)
• Upload directory blocks PHP execution
• DOMPurify sanitizes all rendered markdown
• Security headers (X-Frame-Options, HSTS, etc.)

License

MIT