DevStack Directory Docs

Complete documentation for installing, configuring, and running your DevStack Directory. No Composer, no Node, no build step — upload and run.

Overview

DevStack Directory is a self-hosted developer tool directory CMS. It supports two listing tiers — free (backlink required, auto-approved on verification) and paid (Polar.sh payment, priority manual review). Everything runs on PHP + SQLite with no external dependencies.

Out of the box you get: user registration with email verification, Google + GitHub OAuth, SMTP email, Polar.sh payments, reCAPTCHA, backlink verification, badge embed codes, OG image + favicon upload, and a full admin panel.

Requirements

• PHP 8.1 or higher — uses match(), str_contains(), named arguments
• PHP extensions: sqlite3, pdo_sqlite, gd, curl
• Apache with mod_rewrite enabled, or Nginx
• Write permission on the data/ directory

Installation

First setup

After logging in, go to Admin → Settings and configure at minimum:

• Site name and tagline
• Badge domain — your full domain without https:// (e.g. yourdomain.com)
• From address — sender email for outgoing mail
• SMTP credentials — required for email to work (see Email / SMTP)
• Polar.sh credentials — required for paid listings (see Polar.sh)

Admin panel

The admin panel is at /admin. It has five sections accessible from the left sidebar.

Tools

Full list of submitted tools with filters by status and tier. Actions per tool:

• Approve — makes the listing live on the directory
• Reject — removes from public view; user can edit and resubmit
• Delete — permanently removes the listing
• Recheck backlink — re-runs backlink verification for free listings

Paid listings are marked with a PAID badge so you can prioritise them in your review queue.

Categories

Create, edit, and delete categories. Each category has a name, slug, and optional icon (emoji or short text). Categories appear as filter pills on the homepage. Deleting a category does not delete its tools — they become uncategorised.

Users

List of all registered users with email, registration date, verification status, and listing count. You can suspend accounts from this panel — suspended users cannot log in.

Settings reference

Email / SMTP

All transactional emails (verification, password reset) go through SMTP. PHP's mail() is used as a fallback when SMTP is not configured, but most modern hosts require SMTP for reliable delivery.

Recommended: SendPulse

Free tier: 15,000 emails/month. No daily cap. No domain ownership verification required to start.

Testing: Mailtrap

For staging and testing, Mailtrap catches all outgoing emails in a test inbox — nothing reaches real users. Sign up, go to Email Testing → My Inbox → SMTP Settings, copy the credentials, and paste into admin settings. When going live, swap for SendPulse.

Email triggers

Polar.sh payments

Polar.sh handles checkout for Pro listings. The integration supports both sandbox (testing) and production modes via a toggle in admin settings.

Setup steps

Payment flow

1. User selects Pro listing and submits the tool form
2. They are redirected to Polar checkout
3. After successful payment, Polar redirects them back to their profile with a success message
4. Listing shows as PAID PENDING REVIEW in their dashboard
5. Admin reviews and approves — paid listings are priority

Social login

Google OAuth

GitHub OAuth

OAuth behavior

• If the email from Google/GitHub matches an existing account, the user is logged in to that account
• If no account exists, one is created automatically with email already verified
• OAuth users don't have a password — they can request a password reset if they want email/password access

reCAPTCHA

Google reCAPTCHA v2 ("I'm not a robot" checkbox) on the submission and registration forms.

Backlink verification

Free listings require a backlink from the submitter's site. The system verifies this automatically.

1. User submits a free listing and provides the URL of the page where their badge/link is placed
2. The system fetches that page using PHP's curl and searches for a link containing your domain
3. If found → listing is AUTO-APPROVED and goes live immediately
4. If not found → listing goes to PENDING for manual review

From Admin → Tools, click Recheck on any free listing to re-run verification. There is also a bulk recheck option in Admin → Settings that processes all pending free listings at once.

Badge system

The badge lets submitters display a "Listed on [YourDirectory]" badge on their site, satisfying the backlink requirement.

After submission, users get two embed options — dark and light variants. The embed code is a fully inline-styled <a> tag that works on any external site without needing CSS from your directory.

Badge endpoint

/badge.php generates an SVG badge image. Parameters: style=dark (default) or style=light

Listing flow

Free listing

Submit form
  → System fetches backlink URL
  → Link to your domain found?
      ✓ Yes → Auto-approved → Live immediately
      ✗ No  → Pending → Admin review → Approve / Reject

Pro listing

Submit form
  → Redirect to Polar checkout
  → Payment complete
  → Return to profile (/profile/index.php?paid=1)
  → Success message shown
  → Listing: PAID / PENDING REVIEW
  → Admin sees PAID badge → Priority review → Approve / Reject

Status meanings

User accounts

Registration methods

• Email + password — requires email verification before login
• Google OAuth — auto-verified, no password set
• GitHub OAuth — auto-verified, no password set

Email verification flow

• Link sent on registration, expires in 24 hours
• Login attempt with unverified account → fresh link resent automatically
• Resend button available in profile dashboard (rate limited: once per 5 minutes)
• Clicking an expired link shows instructions to sign in and request a new one

Password reset

Available at /profile/forgot. Sends a reset link valid for 1 hour. Enter email, receive link, set new password.

File structure

Moving to a new domain

The database carries all settings, listings, users, and categories — nothing needs reconfiguring except domain-specific fields.

1. Upload all files to the new host
2. Upload data/directory.db and data/uploads/ separately
3. In Admin → Settings update: Badge domain, From address
4. In Polar dashboard → Settings → Webhooks: update the webhook URL to the new domain
5. In Google Cloud Console: add new domain to Authorized JavaScript origins and new callback URI to Authorized redirect URIs
6. In GitHub OAuth App: update Homepage URL and Authorization callback URL
7. In Google reCAPTCHA admin: add the new domain to allowed domains

Nginx configuration

If using Nginx instead of Apache, add the following server block:

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/html;
    index index.php;

    # PHP handling
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # Block direct access to database
    location /data/ { deny all; }

    # Allow webhook endpoint
    location /webhook/ {
        try_files $uri $uri/ =404;
    }

    location / {
        try_files $uri $uri/ =404;
    }
}

Security notes

• data/ directory has a .htaccess blocking PHP execution and directory listing — keep this in place
• Admin password stored as a bcrypt hash in the database
• User passwords stored as bcrypt hashes
• CSRF tokens verified on all POST forms
• SQL queries use PDO prepared statements throughout — no raw string interpolation
• Webhook signature verified via HMAC-SHA256 before processing any Polar events
• OAuth state parameter verified to prevent CSRF on OAuth flows
• Uploaded files stored in data/uploads/ which blocks PHP execution

Recommended before going live

• Change the default admin password
• Enable reCAPTCHA to reduce spam submissions
• Configure SMTP — mail() fallback is unreliable on most hosts
• Back up data/directory.db regularly — it contains everything
• Enable HTTPS — most hosts offer free SSL via Let's Encrypt through cPanel