Complete Step-by-Step Guide to Running and Managing Keycloak 26.3.3 on Linux (Production Ready)

Limited Time Offer!

For Less Than the Cost of a Starbucks Coffee, Access All DevOpsSchool Videos on YouTube Unlimitedly.
Master DevOps, SRE, DevSecOps Skills!

Enroll Now

1. Introduction

Keycloak is an open-source Identity and Access Management (IAM) tool that provides Single Sign-On (SSO), authentication, and authorization for applications and microservices.
In your case, Keycloak is running for your MyHospitalNow ecosystem — where multiple services (like mhn-core-ms, mhn-doctors-ms, and mhn-hospital-ms) use Keycloak for login and logout across platforms.

You are using Keycloak version 26.3.3, running on Ubuntu Linux, installed under:

/opt/auth.myhospitalnow.com

This tutorial will guide you through setup, common issues, debugging, and running Keycloak properly.

2. Understanding the Problem You Faced

When you ran:

./kc.sh start --optimized

you saw this:

ERROR: Unable to start HTTP server
ERROR: io.quarkus.runtime.QuarkusBindException: Port(s) already bound: 8080: Address already in use

This error means Keycloak was already running in the background (from your previous command).
That happened because you pressed Ctrl + Z, which only suspended the process instead of stopping it.

3. Understanding Keycloak Start Options

Let’s go over the most important Keycloak commands you’ll use.

Start Keycloak in Production Mode

./kc.sh start --optimized

--optimized = runs Keycloak using pre-built configuration and Quarkus optimizations (recommended for production).
By default, it listens on:
- http://0.0.0.0:8080 (main interface)
- http://0.0.0.0:9000 (management interface)

Stop Keycloak

If Keycloak was started in foreground (you see logs in the terminal):

Press Ctrl + C to stop it.

If Keycloak is running in the background:

sudo ss -ltnp | egrep ':8080|:9000'
sudo kill -TERM <pid>

4. Fixing “Address already in use” Error

When Keycloak fails to start because port 8080 or 9000 is already in use, follow these steps carefully.

Step 1: Check what is using the port

sudo ss -ltnp | egrep ':8080|:9000'

You’ll see output like:

LISTEN  *:8080  users:(("java",pid=464574,fd=362))
LISTEN  *:9000  users:(("java",pid=464574,fd=363))

This means the Keycloak Java process (PID 464574) is still running.

Step 2: Stop or Kill the process

Try to stop it gracefully first:

sudo kill -TERM 464574

If it doesn’t stop:

sudo kill -9 464574

Step 3: Verify that the port is free

sudo ss -ltnp | egrep ':8080|:9000' || echo "Ports are free"

Step 4: Restart Keycloak

cd /opt/auth.myhospitalnow.com/bin
./kc.sh start --optimized

Now Keycloak will start successfully and show:

Keycloak 26.3.3 started on http://0.0.0.0:8080
Profile prod activated

5. Running Keycloak in the Background (Permanent Setup)

If you want Keycloak to keep running even after you close SSH or the terminal, you have two main options.

Option A: Use `nohup` (Quick & Temporary)

nohup ./kc.sh start --optimized > /var/log/keycloak.out 2>&1 & disown

Keeps Keycloak running after you close the terminal.
Logs will go to /var/log/keycloak.out.

Option B: Create a `systemd` Service (Recommended for Production)

Step 1: Create the service file

Create a new systemd service file:

sudo nano /etc/systemd/system/keycloak.service

Step 2: Add this content

[Unit]
Description=Keycloak Server
After=network.target

[Service]
User=root
WorkingDirectory=/opt/auth.myhospitalnow.com
ExecStart=/opt/auth.myhospitalnow.com/bin/kc.sh start --optimized
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
Restart=on-failure
LimitNOFILE=102642

[Install]
WantedBy=multi-user.target

Step 3: Reload systemd and start the service

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

Now Keycloak will automatically start on every reboot.

6. Changing Default Ports

If port 8080 is already being used (for example, by Apache or Laravel), you can easily change Keycloak’s ports.

Change the HTTP Port

./kc.sh start --optimized --http-port=8081

Change the Management Port

./kc.sh start --optimized --http-management-port=9001

You can also make these changes permanent by editing:

/opt/auth.myhospitalnow.com/conf/keycloak.conf

and adding:

http-port=8081
http-management-port=9001

7. Understanding the Warnings

When starting Keycloak, you may see:

WARNING: Hostname v1 options [hostname-strict-backchannel, proxy] are still in use

This means you are still using the old hostname configuration keys (v1).
It’s not harmful, but it’s better to migrate to the v2 hostname settings.

Old v1 example:

hostname-strict-backchannel=true
proxy=edge

New v2 style example:

hostname=myhospitalnow.com
hostname-admin=auth.myhospitalnow.com
hostname-backchannel-dynamic=true

You can safely continue running with v1 for now, but plan to update this later.

8. Bootstrapping the Admin User

If you ever need to recreate or reset your Keycloak admin user:

Step 1: Set environment variables

export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD='StrongPassword@123'

Step 2: Start Keycloak once

./kc.sh start-dev

Step 3: Verify admin login

Visit:

http://<your-server-ip>:8080

9. Common Troubleshooting Scenarios

Case 1: “Access denied for user ‘root’@’localhost’”

This means Keycloak can’t connect to the MariaDB database.
Check your credentials in:

/opt/auth.myhospitalnow.com/conf/keycloak.conf

Ensure:

db=mariadb
db-username=root
db-password='YourPassword'
db-url=jdbc:mariadb://localhost:3306/keycloak_db?localSocket=/opt/lampp/var/mysql/mysql.sock

Test it manually:

mysql -u root -p

Case 2: “Address already in use”

We’ve covered this — always use:

sudo ss -ltnp | egrep ':8080|:9000'
sudo kill -9 <pid>

Case 3: Keycloak stops when terminal closes

Run it with:

nohup ./kc.sh start --optimized > /var/log/keycloak.out 2>&1 &

or use the systemd service.

10. Debugging and Logs

Logs are your best friend for finding errors.

View Keycloak logs in real time

tail -f /opt/auth.myhospitalnow.com/data/log/keycloak.log

If you used nohup:

tail -f /var/log/keycloak.out

11. Secure Production Deployment Without SSL

You mentioned that your Keycloak is running in production without SSL.
That’s fine for local or internal use, but for production it’s best to use HTTPS.

You can handle SSL in two ways:

Use a reverse proxy like Apache or Nginx to add SSL in front of Keycloak.
Configure SSL directly inside Keycloak using certificate files.

Example (using reverse proxy on Apache)

In your /etc/httpd/conf.d/auth.myhospitalnow.com.conf:

<VirtualHost *:443>
    ServerName auth.myhospitalnow.com

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/auth.myhospitalnow.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/auth.myhospitalnow.com/privkey.pem
</VirtualHost>

Then reload Apache:

sudo systemctl reload apache2

Now you can access Keycloak securely at:

https://auth.myhospitalnow.com

12. Quick Reference Commands

Task	Command
Start Keycloak	`./kc.sh start --optimized`
Stop Keycloak (graceful)	`sudo kill -TERM <pid>`
Stop Keycloak (force)	`sudo kill -9 <pid>`
Check Keycloak ports	`sudo ss -ltnp
Run in background	`nohup ./kc.sh start --optimized > /var/log/keycloak.out 2>&1 &`
Create systemd service	`sudo nano /etc/systemd/system/keycloak.service`
Reload systemd	`sudo systemctl daemon-reload`
Start service	`sudo systemctl start keycloak`
Enable autostart	`sudo systemctl enable keycloak`
Check logs	`tail -f /opt/auth.myhospitalnow.com/data/log/keycloak.log`

Troubleshooting cmds

sudo systemctl status keycloak
sudo systemctl daemon-reload
sudo systemctl restart keycloak
journalctl -u keycloak -f

Post Views: 1,031