Installation guide

Get up and running in under a minute.

Drop a folder into your web server. Open it in a browser. Run the 3-step installer. You're managing databases. Pick the method that fits your stack — git, zip, or Docker.

~60 seconds No build step No Composer MIT licensed
~/htdocs — bash
$ cd /path/to/htdocs
$ git clone https://github.com/ClearanceClarence/Ledger.git ledger
Cloning into 'ledger'...
Receiving objects: 100% (482/482), done.
$ open http://localhost/ledger/
✓ Installer ready
Pick your method

Three ways to install.
Same destination.

Clone

Clone into your web root.

Open a terminal, navigate to your web server's document root, and clone the repository. The destination folder name becomes your URL path — choose whatever fits your setup.

cd /path/to/htdocs
git clone https://github.com/ClearanceClarence/Ledger.git ledger
Common web roots: XAMPP uses C:\xampp\htdocs\. MAMP uses /Applications/MAMP/htdocs/. Most Linux setups use /var/www/html/.
Open

Visit the URL in your browser.

Open http://localhost/ledger/ in your browser (or whatever path matches the folder name you chose). The installer page loads automatically when no config.php exists yet.

open http://localhost/ledger/
Configure

Run the 3-step installer.

The visual installer walks you through database connection, admin account, and confirmation. Each step validates before proceeding — connection tested live, password strength checked, common passwords rejected.

3.1
Database connection

Host, port, username, password. Tested before proceeding — failures show the exact PDO error with suggestions.

3.2
Admin account

Username and password (min 6 chars, common passwords rejected). Bcrypt-hashed immediately.

3.3
Done

config.php is generated. You're redirected to the login page.

Download

Get the release zip.

Download the latest release from GitHub. Source code zip is fine — no separate build artifact needed.

Download v1.0.2-beta
Extract

Extract into your web root.

Unzip to a folder inside your web server's document root. Rename the folder if you want a shorter URL path — Ledger-1.0.2-beta/ becomes ledger/ for cleaner URLs.

On Windows: right-click the zip and use "Extract All", not the preview view. The preview lets you copy files individually, which is slower and sometimes corrupts paths.
Configure

Open the URL and run the installer.

Same 3-step wizard as the Git method — database connection, admin account, done. Open http://localhost/ledger/ and follow the prompts.

open http://localhost/ledger/
Clone

Clone the repository.

The repository ships with a Dockerfile and docker-compose.yml at the root. No separate Docker image to pull.

git clone https://github.com/ClearanceClarence/Ledger.git
cd Ledger
Start

Bring up the stack.

Two containers come up: Ledger on PHP 8.2 + Apache, and MySQL 8.0. Three named volumes persist data across restarts.

docker-compose up -d
Ports: Ledger on 8080. MySQL exposed on 3307 for external clients.
Configure

Open and configure.

Visit http://localhost:8080/. In the installer, use db as the host (the container name on the internal Docker network) and the default root password ledger_root_pass.

open http://localhost:8080/
Production note: change ledger_root_pass in docker-compose.yml before deploying anywhere reachable.
Requirements

What you'll need.

Ledger runs on the same stack you already have. No special anything.

PHP
Minimum 7.4
Recommended 8.2+
MySQL
Minimum 5.7
Recommended 8.0+
MariaDB
Minimum 10.3
Recommended 10.11+
Web server
Minimum Apache 2.4
Recommended + mod_rewrite
PHP extensions
Required PDO, PDO_MySQL
Plus session
Verified on XAMPP WAMP MAMP Laragon DDEV Herd Docker Apache + PHP-FPM
Troubleshooting

Things that occasionally go wrong.

The most common install issues. If yours isn't here, file a bug report — real questions help everyone.

The installer loads but the connection test fails

Usually one of three things. Check in order:

  1. MySQL/MariaDB isn't running. Check your service status. On XAMPP, the control panel needs both Apache and MySQL started.
  2. Wrong host. 127.0.0.1 works almost always. localhost sometimes fails on Linux because PHP tries the socket path instead of TCP.
  3. Wrong port. Default is 3306. MAMP uses 8889 sometimes. Check your installation docs.
"Could not write config.php" during step 3

The web server user (typically www-data on Linux or SYSTEM on Windows) can't write to the install directory. Two options:

  • Make the install directory writable: chmod 755 ledger/ on Linux, or check folder permissions on Windows.
  • Manually create config.php by copying config.template.php and filling in your values. The installer skips this step if the file already exists.
500 error on every page after install

Usually a missing PHP extension or an unreadable config.php. Check the PHP error log first — it's the fastest path to the actual cause.

  • Apache: usually logs/error.log inside your Apache directory.
  • PHP-FPM: usually /var/log/php-fpm/error.log or wherever error_log points in php.ini.
  • XAMPP: xampp/apache/logs/error.log and xampp/php/logs/.

The most common missing extension is pdo_mysql. Run php -m | grep pdo from the command line to verify.

Login works but every page is blank or broken

Usually a session or .htaccess issue. Try:

  • Check the browser console for 404s on js/ledger.js or CSS files. If they 404, your web server doesn't have the right rewrite rules or alias.
  • If your install lives at a subpath like /admin/ledger/, make sure mod_rewrite is enabled and .htaccess is being read (AllowOverride All in Apache).
I'm running on shared hosting and ____ doesn't work

Shared hosting varies wildly. Some common ones:

  • cPanel hosts usually work out of the box. Upload via File Manager, set permissions, open the URL.
  • open_basedir restrictions can block logs/ writes. Set 'log_dir' => '/tmp/ledger/' in config.php if you can't relax the restriction.
  • PHP version pinning — many hosts still default to 7.4. The dropdown to switch is usually in cPanel under "MultiPHP Manager".
  • If nothing works, open an issue with the hosting provider name and PHP version. Real-world testing on hosts the author doesn't have is exactly the kind of contribution welcomed.
FAQ

Questions that come up.

The answers people actually want before they install. If yours isn't here, ask in Discussions.

Why not just use phpMyAdmin? It works.

phpMyAdmin works, has worked for two decades, and probably will work for two more. Don't switch tools without a reason.

Reasons to consider Ledger anyway:

  • You want a modern AJAX interface instead of full-page reloads on every action.
  • You want a real SQL editor with context-aware autocomplete that understands your table aliases.
  • You want a zero-dependency install — no Composer, no config.inc.php ritual, no vendor directory.
  • You're tired of the phpMyAdmin UI and want something that looks like it was built in this decade.

If none of those resonate, phpMyAdmin is still a great choice. We're not trying to talk you out of it.

Is it secure enough for production?

For the same scenarios phpMyAdmin is used in, yes. Ledger ships a 12-layer security chain enabled by default: bcrypt passwords, TOTP 2FA per user, CSRF tokens on every mutation, brute-force lockout, IP whitelist with CIDR support, read-only mode, prepared statements throughout, security headers, session hardening, query audit log, and more.

That said, two important caveats apply to any web-based database admin tool — including phpMyAdmin, Adminer, and Ledger:

  • Never expose it on a public URL without HTTPS. All three tools rely on session cookies. Without TLS, those are sniffable.
  • Restrict access at the firewall or web server level too. Application-layer auth is one defense; network-layer restriction is another. The IP whitelist feature exists for a reason — use it.

This is a v1.0.2-beta release. The code has been in private development since December 2025 and used internally, but it hasn't had wide community review yet. If you find a security issue, please follow the disclosure process in SECURITY.md.

Will it work on my shared hosting?

Almost certainly. If your host runs PHP 7.4+ with PDO and PDO_MySQL (every host does), Apache with mod_rewrite (every cPanel host does), and gives you access to htdocs/ via FTP or a file manager — Ledger will run.

Specific hosts verified to work include any standard cPanel host, DreamHost, SiteGround, Hostinger, and most national hosts. If yours has unusual restrictions (open_basedir, custom PHP sandboxes), see the troubleshooting section above.

What MySQL and MariaDB versions are supported?

MySQL 5.7+ and MariaDB 10.3+ are the minimum supported versions. Both are five-plus years old, so unless you're maintaining something legacy you should be fine.

Recommended versions: MySQL 8.0+ or MariaDB 10.11+. Tested primarily against these. Older versions work but some features (window functions, JSON paths, CTEs) won't be available because the server itself doesn't support them.

PostgreSQL and SQLite are not supported and aren't planned — Ledger is intentionally MySQL/MariaDB-focused. If you need a multi-database tool, use Adminer or DBeaver instead.

Can I migrate from phpMyAdmin without losing anything?

Yes. Ledger doesn't store anything in your databases that phpMyAdmin needs to know about — it keeps its own state (favorites, ER diagram layouts, query history) in flat files inside its own install directory. Run both side by side if you want.

Two specific migration points worth knowing:

  • SQL dumps are interchangeable. Ledger's "phpMyAdmin-compatible" export mode produces byte-for-byte equivalent SQL dumps — useful when sharing dumps with anyone still on phpMyAdmin, or when restoring an older phpMyAdmin backup.
  • User accounts are not shared. phpMyAdmin uses your MySQL user credentials directly; Ledger uses its own admin account layer on top. You set up Ledger admin users separately, which is intentional — keeps the MySQL root password out of session storage.
Why no Composer? Why no build step?

Deliberate. The whole project is one of Ledger's core principles: drop a folder, it runs.

Composer dependencies mean: developers have to install Composer, hosts have to allow CLI access, dependency conflicts become a thing, and security audits get harder because half the surface area lives in vendor/. Same logic for npm and a JS build step.

The downside is that some "obviously useful" libraries can't be used — every feature has to be either built from scratch or skipped. That's a real cost. It's also what keeps the entire codebase auditable in an afternoon.

Is this project actively maintained?

Yes. v1.0.0-beta released May 11, 2026 as the first public version; v1.0.1-beta released May 19, 2026 with hardening fixes from the first round of real-world bug reports; v1.0.2-beta released June 12, 2026, a security release from a full self-audit. Development started December 2025 under the project's earlier internal name (DBForge) and has been continuous since.

This is a solo-maintained project. That means:

  • Bug reports get triaged. Real reports get real responses.
  • Feature requests get considered against scope — features that fit get accepted, features that don't get a polite "no" with reasoning.
  • There's no SLA. If the maintainer takes two weeks to respond, it's because they took two weeks.

If you want a project with a larger team behind it, phpMyAdmin remains the right answer.

Can I use Ledger for free in commercial projects?

Yes. Ledger is MIT licensed. Use it commercially, fork it, embed it in your product, sell consulting around it — all fine. No royalties, no attribution required (though attribution is appreciated), no telemetry.

The full license is in LICENSE on GitHub.

Does it work on mobile / tablet?

The interface is responsive and usable on tablets. On phones, it's technically usable but database admin on a 380px screen is rarely a good idea regardless of the tool — there's just too much information to display.

For phone-based emergency access ("kill that runaway query"), the live process monitor and SQL editor work well on mobile. Browse / Structure / ER diagram are best on tablet or desktop.

Can I theme it / customize fonts?

Yes — there are 20 built-in themes (10 light, 10 dark) including Tokyo Night, Dracula, Catppuccin, GitHub, Gruvbox, Monokai, Nord, and Solarized. Switch from the header dropdown without a reload.

Custom themes are a folder of CSS variables — drop themes/your-theme/ with a theme.json and style.css and it appears in the dropdown. Override only the variables you care about.

Fonts can be customized per zone — body, headings, sidebar, table data, and SQL editor each have their own variable. 28 curated faces ship pre-configured, only fetched if you select them.

See /themes for the gallery.

What's the catch?

Three honest catches:

  • MySQL/MariaDB only. Not PostgreSQL, not SQLite, not anything else. If you work with multiple database engines, Ledger isn't your tool.
  • v1.0.2-beta. Stable enough to use, but expect rough edges on PHP version matrices, MariaDB forks, and hosting environments other than the development setup. Bug reports welcomed.
  • Solo-maintained. One person can only respond so fast. If you need enterprise support, this isn't it.

If those don't bother you, install it and let me know what breaks.

How does it compare to phpMyAdmin, Adminer, and DBeaver?

The comparison matrix on the Features page covers ~30 specific features in detail. The short version:

  • vs phpMyAdmin: Ledger is lighter (~2 MB vs ~50 MB), more modern UX (AJAX everywhere), themed by default. phpMyAdmin has more features, FIDO U2F support, and a larger team behind it.
  • vs Adminer: Adminer wins on file size (single 500 KB file) and multi-database support. Ledger wins on modern UX, built-in 2FA, themes, and depth of MySQL-specific features.
  • vs DBeaver: Different category. DBeaver is a heavyweight desktop tool with 80+ database types and advanced features. Ledger is a web tool you SSH-deploy. Use DBeaver if you need cross-database; use Ledger if you need to admin MySQL/MariaDB from any browser.

Need help with something specific?

Open an issue on GitHub. Include your PHP version, MySQL/MariaDB version, OS, and the exact error. Real bug reports get real responses.

Open an issue Discussions