Keycloak - intentional that service deploys in development mode on install?

[max-brod]

Hello,

Disclaimer: This is a home lab deployment but for the sake of learning I wish to secure all my applications as if running in a business production setting. I am not very familiar with LXC containers yet.

I am pretty new to using Keycloak and deploying community-scripts such as these. I have read that it is not ideal to run Keycloak under development mode in a production environment for several security-related reasons.
How come that the script that installs Keycloak on an LXC does not account for this and deploys the service to run the executable in development mode? Is this intentional?

What is the intended way within the realm of this script to "upgrade" to production later on? Is there a way to switch to production within the Keycloak admin panel itself that I may have missed at some point? If not, should I edit the service itself to not use "start-dev" once everything is ready to run in production?

I do not intend to expose Keycloak directly as I will be putting it behind a reverse proxy.

Do you people have any advice for me? Am I overlooking something obvious?

Thank you for your time!

[jd-apprentice]

Hihi! At least for my understanding these scripts won't include what are "Production ready" installations, but I'll suggest you read something like:

https://www.keycloak.org/server/configuration-production

Which includes common practices to expose a Keycloak instance to the world, and yeah you may change some things here and there. You could also have it LAN only (depending on how things are communicating in your servers, or if you are willing to develop something in the meantime your instance is ready to be exposed).

Also here is a cool topic about it:

https://medium.com/@atondelier/keycloak-for-production-level-saas-authentication-b2ef0b1138d4

In any case I'll suggest you ask in some or their social media https://www.keycloak.org/community

[tremor021]

This is not true. We install the apps following the official install instructions (if present), or by translating Dockerfile/Makefile into a bare metal installs (for apps that are docker only). In case of a application that has a paid/license based model, we deploy the free to use version of said app. We don't deploy local dev versions unless thats the only possible deployment or the app is designed to run that way.
Almost all apps out there have instructions on how to deploy to production environment. We are following those instructions.

That said, we are not recommending ANY of our scripts to be used in official production environment, because apps constantly change, breaking changes are introduced all the time. We are supporting you to use it in your own homelab, but other than that we are not encouraging you to use these scripts commercially or in any type of production environment.

[jd-apprentice]

Thanks for the clarification! I was not sure about that, my bad.

[max-brod]

@tremor021

[...] We don't deploy local dev versions unless thats the only possible deployment or the app is designed to run that way. Almost all apps out there have instructions on how to deploy to production environment. We are following those instructions.
[...]

This is confusing to me, as the Keycloak deployment very much so DOES deploy as a local dev version, as evidenced within the command that invokes the Keycloak binary being start-dev instead of start. Keycloak has a separate instruction page on production deployment and that page and the initial setup page directly advises AGAINST running Keycloak with start-dev under production.
Would you like to provide additional clarification on that please? To me this seems contradictory

[tremor021]

Perhaps at the time of writing the script that was the only viable method of installing. Things constantly change, we can't really keep track of these things, so we rely on users to report such issues.

I can only say that we will look into the official documentation and see if we need to update the script

[IReclaimer]

I think adding an optional production mode would be a good idea, it being an authentication platform and all. The current script gets Keycloak running quickly for evaluation, which is great, but it starts in development mode. That leaves a number of insecure defaults in place. I have taken the container produced by the script and brought it up to a basic production posture. I'll share the steps below in the hope they help with adding a production path that can automate most of this.

My Keycloak sits behind an Nginx reverse proxy, so the configuration shown assumes TLS terminates at the proxy and Keycloak sees forwarded headers from a trusted source network or host.

1. Variables (these will need to be collected from the user or substituted with sensible defaults)

PUBLIC_FQDN="sso.example.com" # Public hostname seen by browsers
PROXY_CIDR="10.0.0.22/32" # IP and CIDR of trusted reverse proxy
DB_NAME="keycloak"
DB_USER="keycloak"
ADMIN_USER="admin"
ADMIN_PASS="$(openssl rand -base64 32)"
ENV_FILE="/etc/keycloak/keycloak.env"

If you want separate public and admin hostnames, add an ADMIN_FQDN variable and include it later in keycloak.conf.

2. Install & start PostgreSQL

apt update
apt install -y postgresql postgresql-contrib
systemctl enable --now postgresql

3. Generate DB password and create env file

install -d -m 700 /etc/keycloak
DBPASS="$(openssl rand -base64 48)"
umask 077
cat > "$ENV_FILE" <<EOF
KC_DB_PASSWORD=${DBPASS}
KC_BOOTSTRAP_ADMIN_USERNAME=${ADMIN_USER}
KC_BOOTSTRAP_ADMIN_PASSWORD=${ADMIN_PASS}
EOF
chmod 600 "$ENV_FILE"

4. Create PostgreSQL DB + user with that password

su - postgres -c "psql <<SQL_EOF
CREATE DATABASE $DB_NAME ENCODING 'UTF8';
CREATE USER $DB_USER WITH PASSWORD '$DBPASS';
GRANT ALL PRIVILEGES ON DATABASE $DB_NAME TO $DB_USER;
ALTER DATABASE $DB_NAME OWNER TO $DB_USER;
SQL_EOF
"

5. Write production /opt/keycloak/conf/keycloak.conf
   This example expects PostgreSQL on localhost and TLS terminated at Nginx. If you terminate TLS at Keycloak instead, uncomment the HTTPS lines and provide certificate paths.

cat > /opt/keycloak/conf/keycloak.conf <<EOF
# --- Keycloak production configuration (behind NGINX edge TLS) ---

## Database
db=postgres
db-url=jdbc:postgresql://localhost/${DB_NAME}
db-username=${DB_USER}
db-password=\${KC_DB_PASSWORD}

## Observability
health-enabled=true
metrics-enabled=true

## Reverse proxy / HTTP
http-enabled=true
proxy-headers=xforwarded
proxy-trusted-addresses=${PROXY_CIDR}
#proxy=edge   # optional; header parsing suffices

## Hostname
hostname=${PUBLIC_FQDN}
#hostname-admin=keycloak.lab.progenitorhivemind.com   # uncomment if you later split admin
#hostname-strict=true
#hostname-strict-backchannel=false

## Local TLS example (un-comment if terminating at Keycloak)
#https-certificate-file=/etc/ssl/keycloak.crt
#https-certificate-key-file=/etc/ssl/private/keycloak.key
EOF

Permissions:
chmod 640 /opt/keycloak/conf/keycloak.conf

6. Build Keycloak for PostgreSQL (optimised startup)

cd /opt/keycloak/bin
./kc.sh build --db=postgres

This creates an optimised server image under data/ so that subsequent starts are faster.

7. Override systemd unit: switch to production start & load env
   We only need a drop-in override. This clears the original ExecStart (which calls start-dev), adds the environment file, and starts Keycloak in production mode.

systemctl edit keycloak.service <<'EOF'
[Service]
ExecStart=
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
EnvironmentFile=-/etc/keycloak/keycloak.env
EOF

It is also possible for systemd to run Keycloak as a non-root service account, e.g. add User=keycloak and Group=keycloak lines here and ensure ownership of /opt/keycloak and subdirectories is correct. The upstream distribution runs fine as an unprivileged user once ports and directories are arranged appropriately.

8. Reload & start:

systemctl daemon-reload
systemctl restart keycloak.service

A quick aside on updates: the script is marked non-updateable and does not currently set up an update function, but in practice upgrading should be straightforward. Stop Keycloak, download the latest release from the upstream Git repository, unpack it over the existing installation, keep your existing configuration and environment files, run the build command again (i.e. kc.sh build --db=postgres) so the new version is optimised for quick startup, then restart the service. Keycloak will perform any required database migrations automatically on startup.