Documentation
Votepit runs on classic PHP/MySQL shared hosting, no Docker required — if you'd rather run a container, an alternative Docker package is available. Here's how to get it installed and configured.
Requirements
PHP 8.2 or newer with pdo_mysql, mbstring and intl. A MySQL or MariaDB database. FTPES access (SSH optional). Ideally your web root points at the public/ folder; on hosts where that isn't configurable, the bundled .htaccess keeps everything outside public/ protected, so it works either way.
Install — build locally, upload via FTP
Clone the repo and run composer install --no-dev --optimize-autoloader on your own machine (vendor/ isn't committed, so this happens locally, not on the server). Copy config/config.example.php to config/config.php and fill in your database, SMTP, app_url, admin_emails and a generated app_key. Upload the finished folder via FTPES and point the web root at public/ (otherwise the bundled .htaccess protects the rest). There is no web installer — configuration is a plain file you edit by hand.
Database schema
db/schema.sql alone is only a starting baseline — run php bin/migrate.php (works over SSH or a one-off PHP-CLI cron job on hosts without a shell) to apply it plus every schema update since, both on a brand-new install and on every later update. This is the one required step, not an optional extra for later releases.
Configuration
Secrets live in config/config.php (database, SMTP for magic-link mail, app_key) and are never committed. You copy the example file and fill it in by hand — there is no setup wizard that writes it for you.
Boards & branding
One install serves many boards, addressed by a slug in the path (/{board}/…). Each board has its own name, accent color and intro, managed in the admin area.
Agent API, MCP & CLI
A token-secured REST API (/api/v1/*) and an MCP server (JSON-RPC over HTTP) allow an AI agent to read and create ideas on a board. @votepit/cli wraps the same API in a zero-dependency command-line tool — install it with npm i -g @votepit/cli, with no MCP round-trip required.
Webhooks
Configure a target endpoint per board that gets an HMAC-signed HTTP request when an idea is created or its status changes — for wiring your own Slack, Discord, or CI notifications. The target URL is re-validated before every delivery (SSRF-guarded), internal addresses are rejected.
Docker (alternative)
Prefer a container over uploading via FTPES? Clone the repo, fill in .env from .env.example, and run docker compose up -d. It runs the exact same application as the shared-hosting path, including automatic migrations on start — not a replacement for the standard path, just an equally supported second option.
Updating
Back up your database and config/config.php, upload the new release over the old files (keep config/), then run php bin/migrate.php if a migration is needed.
Complete reference — architecture, configuration, REST API, MCP server, operations, troubleshooting.