To run Keycloak 17+ (Quarkus) with MySQL on the same server (XAMPP/LAMPP). It covers two supported setups. Pick A (TCP) for a production-style config, or B (UNIX socket) if you want to keep XAMPP in socket-only mode (what you just proved works).

I’ll assume:

• Keycloak home: /opt/auth.holidaylandmark.com
• XAMPP home: /opt/lampp
• DB name: keycloak_db
• Socket path: /opt/lampp/var/mysql/mysql.sock

0) Prereqs (one-time)

sudo /opt/lampp/lampp status   # Apache/MySQL running
/opt/lampp/bin/mysql -u root -S /opt/lampp/var/mysql/mysql.sock -e "SELECT VERSION();"
Code language: PHP (php)

Create the database (safe if it already exists):

/opt/lampp/bin/mysql -u root -S /opt/lampp/var/mysql/mysql.sock <<'SQL'
CREATE DATABASE IF NOT EXISTS keycloak_db
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
SQL
Code language: JavaScript (javascript)

If you also want a dedicated DB user for TCP (recommended in A): you’ll create it in step A-2.

A) Run Keycloak with MySQL over TCP (recommended)

A-1) Enable TCP listening on MySQL

Edit /opt/lampp/etc/my.cnf (under [mysqld]):

bind-address=127.0.0.1
# make sure there is NO 'skip-networking'
Code language: PHP (php)

Restart & verify:

sudo /opt/lampp/lampp restartmysql
ss -lntp | grep 3306     # should show mysqld on 127.0.0.1:3306
Code language: PHP (php)

A-2) Create a TCP user and grant access

/opt/lampp/bin/mysql -u root -S /opt/lampp/var/mysql/mysql.sock <<'SQL'
CREATE USER IF NOT EXISTS 'keycloak'@'127.0.0.1' IDENTIFIED BY 'Strong#Passw0rd!';
GRANT ALL PRIVILEGES ON keycloak_db.* TO 'keycloak'@'127.0.0.1';
FLUSH PRIVILEGES;
SQL
Code language: JavaScript (javascript)

Quick test:

/opt/lampp/bin/mysql -h 127.0.0.1 -P 3306 -u keycloak -p keycloak_db -e "SELECT 1;"
Code language: JavaScript (javascript)

A-3) Configure Keycloak for MySQL/TCP

Edit /opt/auth.holidaylandmark.com/conf/keycloak.conf:

db=mysql
db-url=jdbc:mysql://127.0.0.1:3306/keycloak_db?useSSL=false&allowPublicKeyRetrieval=true
db-username=keycloak
# (omit db-password here; supply via env to avoid special-char parsing issues)
Code language: PHP (php)

A-4) Build once, then start

cd /opt/auth.holidaylandmark.com/bin
./kc.sh build
export KC_DB_PASSWORD='Strong#Passw0rd!'
# Optional first-run admin (if you haven't created it yet):
export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD='Admin#12345'
./kc.sh start-dev --verbose
Code language: PHP (php)

You should see DB schema creation logs and the dev UI at http://localhost:8080.

B) Run Keycloak using UNIX socket (XAMPP socket-only)

This is exactly what you just ran successfully.

B-1) Verify the socket exists

ls -l /opt/lampp/var/mysql/mysql.sock
Code language: JavaScript (javascript)

B-2) Configure Keycloak to use the MariaDB driver + socket

Edit /opt/auth.holidaylandmark.com/conf/keycloak.conf:

db=mariadb
db-url=jdbc:mariadb://localhost:3306/keycloak_db?localSocket=/opt/lampp/var/mysql/mysql.sock
db-username=root
# (omit db-password here; supply via env)
Code language: PHP (php)

Some MariaDB Connector/J versions also accept unixSocket=.... Stick with localSocket= if it works for you.

B-3) Build once, then start

cd /opt/auth.holidaylandmark.com/bin
./kc.sh build
export KC_DB_PASSWORD='Hs?gb?S345?3#s'
# Optional first-run admin:
export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD='Admin#12345'
./kc.sh start-dev --verbose
Code language: PHP (php)

You should now see logs mentioning org.mariadb.jdbc... (driver family) and normal startup.

1) Verifications (either A or B)

• Show effective DB settings: ./kc.sh show-config --all | egrep '^(db=|db-url=|quarkus.datasource.db-kind=)'
• Confirm driver family in logs on error (handy trick):
  com.mysql.cj... → MySQL driver; org.mariadb.jdbc... → MariaDB driver.
• Health endpoints (after start): curl -s http://localhost:8080/health | jq . curl -s http://localhost:8080/metrics | head

2) Make it persistent (systemd example)

Create /etc/systemd/system/keycloak.service:

[Unit]
Description=Keycloak
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/auth.holidaylandmark.com/bin
# --- Choose ONE block (A or B) ---

# (A) MySQL/TCP
# Environment=KC_DB=mysql
# Environment=KC_DB_URL=jdbc:mysql://127.0.0.1:3306/keycloak_db?useSSL=false&allowPublicKeyRetrieval=true
# Environment=KC_DB_USERNAME=keycloak
# Environment=KC_DB_PASSWORD=Strong#Passw0rd!

# (B) MariaDB/socket
# Environment=KC_DB=mariadb
# Environment=KC_DB_URL=jdbc:mariadb://localhost:3306/keycloak_db?localSocket=/opt/lampp/var/mysql/mysql.sock
# Environment=KC_DB_USERNAME=root
# Environment=KC_DB_PASSWORD=Hs?gb?S345?3#s

# Optional admin bootstrap (first run only; then remove)
# Environment=KEYCLOAK_ADMIN=admin
# Environment=KEYCLOAK_ADMIN_PASSWORD=Admin#12345

ExecStart=/opt/auth.holidaylandmark.com/bin/kc.sh start
Restart=always

[Install]
WantedBy=multi-user.target
Code language: PHP (php)

Enable & start:

sudo systemctl daemon-reload
sudo systemctl enable --now keycloak
sudo systemctl status keycloak

3) Common pitfalls & fixes

• “Communications link failure / Connection refused”
  • TCP path: MySQL not listening on 127.0.0.1:3306 → fix my.cnf & restart; verify with ss -lntp | grep 3306.
  • Socket path: URL must be jdbc:mariadb://... with db=mariadb and localSocket=....
• “Driver does not support the provided URL”
  • Mismatch between db= and URL scheme.
    Use db=mysql + jdbc:mysql://... or db=mariadb + jdbc:mariadb://....
• Password contains # or special chars
  • Put the password in env (KC_DB_PASSWORD=...), not in keycloak.conf.
• Keycloak keeps using the wrong driver
  • Check env overrides: env | egrep '^KC_DB|KC_DB_URL|KC_DB_USERNAME|KC_DB_PASSWORD'
  • show-config confirms what Keycloak will actually use.

4) Upgrade-safe habits

• Keep DB settings in keycloak.conf, secrets in env.
• Run ./kc.sh build after changing drivers or providers.
• Prefer TCP (A) for production and remote/containerized deployments.
• Use socket (B) only if you’re intentionally running socket-only MySQL on the same host.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.