Skip to content
Klutch.sh Docs

Deploying an Adminer App

Introduction

Adminer is a lightweight, single-file database management tool that supports MySQL, MariaDB, PostgreSQL, SQLite, MS SQL, Oracle, and more. It provides a powerful web-based interface for exploring schemas, running queries, editing data, and managing users—often as a simpler, faster alternative to tools like phpMyAdmin.

Deploying Adminer on Klutch.sh with a Dockerfile gives you a secure, always-available database console that you control. This guide explains how to build an Adminer Docker image, push it to GitHub, deploy it through the Klutch.sh dashboard at klutch.sh/app, and connect it to databases running on Klutch.sh or external providers.

Prerequisites

Before you begin, make sure you have:

  • A Klutch.sh account
  • A GitHub account (GitHub is the only supported git source)
  • Docker installed locally for testing (optional but recommended)
  • Basic familiarity with relational databases and connection settings (host, port, username, password, database name)

Project Setup for Adminer

1. Create a Project Directory

Create a new directory for your Adminer deployment:

Terminal window
mkdir adminer-klutch
cd adminer-klutch
git init

2. Decide on Your Database Targets

Adminer itself does not store your database data—it connects to existing database servers. Typical deployment patterns include:

  • Connecting to databases hosted on Klutch.sh (for example, PostgreSQL, MySQL, or MariaDB apps using TCP traffic on port 8000).
  • Connecting to managed databases from cloud providers.
  • Managing development databases during debugging or migrations.

You’ll configure the connection details directly in the Adminer login form at runtime.

Creating a Dockerfile for Adminer

Klutch.sh automatically detects a Dockerfile in your repository’s root directory and uses it for deployment. You do not select Docker as a special option in the UI, and you don’t specify a Dockerfile path—the detection is fully automated when a Dockerfile exists.

Create a file named Dockerfile in the project root:

FROM adminer:latest


# Adminer is a PHP application running under a web server (Apache or similar)
# in the official image. It listens on port 8080 by default.


WORKDIR /var/www/html


# Optional: copy custom Adminer plugins or themes into the image
# COPY plugins /var/www/html/plugins
# COPY adminer.css /var/www/html/adminer.css


# Expose Adminer HTTP port
ENV PORT=8080
EXPOSE 8080


# Use the default entrypoint and command from the official Adminer image

Dockerfile Notes

  • The official adminer:latest image serves the web UI on port 8080, which will be your internal port in Klutch.sh.
  • You can optionally add themes or plugins by copying them into /var/www/html (for example, plugins/ or adminer.css).
  • Because Adminer is stateless, it does not require a complex runtime; the image is rebuilt and redeployed easily whenever you add plugins or styling.

Optional: Local Testing with Docker

Test your Adminer image locally before deploying to Klutch.sh:

Terminal window
docker build -t adminer-klutch .


docker run -d \
  --name adminer-test \
  -p 8080:8080 \
  adminer-klutch

Then open http://localhost:8080 to verify that the Adminer login page loads correctly.

For more complex local setups (for example, running Adminer plus databases together), you can use Docker Compose on your machine. Docker Compose is strictly for local development; Klutch.sh does not deploy via Docker Compose.

Pushing Your Adminer Project to GitHub

Once your Dockerfile (and any optional plugin/theme files) are ready, push the repository to GitHub:

Terminal window
git add .
git commit -m "Initial Adminer Docker setup for Klutch.sh"
git branch -M main
git remote add origin https://github.com/your-username/adminer-klutch.git
git push -u origin main

Klutch.sh will use this GitHub repository as the source for building and deploying your Adminer app.

Creating an Adminer App on Klutch.sh

With your repository available on GitHub, you can configure and deploy Adminer through the Klutch.sh dashboard.

Connect the GitHub Repository

  1. Sign in at klutch.sh/app.
  2. Go to Create Project and give your project a name like adminer-console.
  3. Open Create App and:
    • Choose GitHub as the git source.
    • Select your Adminer repository and the branch you want to deploy (for example, main).

Klutch.sh will automatically detect the Dockerfile in the repository root and use it for the build.

Traffic Type and Internal Port

  • Traffic Type: Select HTTP (Adminer is a web-based application).
  • Internal Port: Set to 8080, matching the port exposed in your Dockerfile and used by the Adminer container.

This configuration routes HTTP traffic from your Klutch.sh app’s URL to the Adminer web interface running inside the container.

Environment Variables on Klutch.sh

Adminer can be used without any environment variables, but you may choose to set:

  • TZ – your timezone (for example, UTC or America/New_York) to ensure consistent timestamp logging.

If you ever deploy a non-Docker version using Nixpacks for an application that includes Adminer, you can customize commands using:

  • BUILD_COMMAND – override the default build command Nixpacks uses.
  • START_COMMAND – override the default start command Nixpacks runs.

Set these environment variables in the Klutch.sh dashboard when you need to customize Nixpacks behavior.

Attaching Persistent Volumes

Adminer itself is stateless, but you might want persistent storage for:

  • Custom Adminer plugins (for example, additional drivers, authentication helpers, or UI extensions)
  • Custom CSS themes or branding

To make these customizations persistent across deployments:

In the app’s Storage/Volumes section, add:

  • Adminer Customization Volume
    • Mount path: /var/www/html
    • Size: A small volume (for example, 1 GiB) is usually more than enough for plugins and static assets.

You can then place your plugins (for example, in /var/www/html/plugins) or stylesheets (for example, /var/www/html/adminer.css) into this volume, and they will persist across container restarts and redeployments.

Sample Code: Connecting to a Database Managed via Adminer

Adminer is a web UI rather than a programming library, but you’ll typically use it alongside application code that connects to the same databases. Below are simple examples showing how code in your apps might connect to a PostgreSQL database that you also manage with Adminer deployed on Klutch.sh.

Assume you have:

  • A database app on Klutch.sh configured with TCP traffic, reachable at example-app.klutch.sh on external port 8000, and internal port 5432 for PostgreSQL.
  • Your Adminer app deployed separately with HTTP traffic and internal port 8080, used for interactive management.

Node.js PostgreSQL Connection Example

const { Client } = require('pg');


async function main() {
  const client = new Client({
    host: 'example-app.klutch.sh', // your PostgreSQL app on Klutch.sh
    port: 8000,                    // Klutch.sh TCP port for database apps
    user: 'db_user',
    password: 'db_password',
    database: 'my_database',
  });


  try {
    await client.connect();
    console.log('Connected to PostgreSQL via Klutch.sh');


    const result = await client.query('SELECT NOW() AS current_time');
    console.log(result.rows[0].current_time);
  } catch (err) {
    console.error('Database connection error:', err);
  } finally {
    await client.end();
  }
}


main();

You can use the same host (example-app.klutch.sh), port (8000), username, password, and database name in Adminer’s login form to manage this database through the browser.

PHP PDO Example (MySQL/MariaDB)

<?php
$dsn = 'mysql:host=example-app.klutch.sh;port=8000;dbname=my_database;charset=utf8mb4';
$username = 'db_user';
$password = 'db_password';


try {
    $pdo = new PDO($dsn, $username, $password, [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ]);


    $stmt = $pdo->query('SELECT NOW() AS current_time');
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    echo 'Current time: ' . $row['current_time'];
} catch (PDOException $e) {
    echo 'Connection failed: ' . $e->getMessage();
}

Again, you can reuse these same connection parameters in Adminer to explore and manage the database through the Adminer UI hosted on Klutch.sh.

Verifying Your Deployment

After the first deployment completes in the Klutch.sh dashboard:

  1. Visit your Adminer app URL, for example:

    https://example-app.klutch.sh

  2. Check that:

    • The Adminer login screen loads successfully.
    • You can log in to your target database (whether hosted on Klutch.sh with TCP traffic or externally).
    • Any custom plugins or themes placed in the /var/www/html volume are available and applied.

If you encounter issues, inspect the app logs in Klutch.sh and double-check your internal port and volume mount configuration.

Troubleshooting

Adminer Page Not Loading

  • Confirm the app’s Traffic Type is HTTP.
  • Verify the internal port is set to 8080 and matches the EXPOSE 8080 directive in your Dockerfile.
  • Check the build and runtime logs in the Klutch.sh dashboard for any errors from the Adminer container.

Cannot Connect to Database from Adminer

  • Ensure the database app on Klutch.sh is configured with TCP traffic and the correct internal port (for example, 5432 for PostgreSQL or 3306 for MySQL).
  • Use the external host (example-app.klutch.sh) and port 8000 in the Adminer connection form.
  • Verify your database credentials and confirm the database allows connections from the Adminer app’s environment.

Customizations Not Persisting

  • Ensure a persistent volume is configured with mount path /var/www/html.
  • Verify that your plugins, themes, or other custom files are placed within that directory.
  • Confirm that the volume size is sufficient and that the container has write access.

Deploying an Adminer app on Klutch.sh with a Dockerfile gives you a fast, portable database management console you can access from anywhere. With a minimal Dockerfile, a correctly configured internal port, and optional persistent storage for custom plugins and themes, you can manage databases running on Klutch.sh or external providers through a simple, secure, self-hosted Adminer instance.