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.

---