# Keycloak Generated on 15 Apr 2025 from [the Keycloak catalog page](https://marketplace.digitalocean.com/apps/keycloak) Keycloak is a single sign-on solution for web apps and RESTful web services. Keycloak aims to simplify security so that it is easy for application developers to secure the apps and services they have deployed in their organization. Security features that developers normally have to write for themselves are provided out of the box and are easily tailored to the individual requirements of your organization. Keycloak provides customizable user interfaces for login, registration, administration, and account management. **Keycloak requires 2GB of RAM and 2CPU cores, AT MINIMUM.** ## Software Included | Package | Version | License | |---|---|---| | Postgres | 16 | [Postgres SQL](https://opensource.org/license/postgresql) | | Nginx | 1.18 | [Custom](https://nginx.org/LICENSE) | | Certbot | 0.40 | [Apache 2](https://github.com/certbot/certbot/blob/master/LICENSE.txt) | ## Creating an App using the Control Panel Click the **Deploy to DigitalOcean** button to create a Droplet based on this 1-Click App. If you aren’t logged in, this link will prompt you to log in with your DigitalOcean account. [![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/droplets/new?image=sharklabs-keycloak) ## Creating an App using the API In addition to creating a Droplet from the Keycloak 1-Click App using the control panel, you can also use the [DigitalOcean API](https://docs.digitalocean.com/reference/api). As an example, to create a 4GB Keycloak Droplet in the SFO2 region, you can use the following `curl` command. You need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) to an environment variable or substitute it in the command below. ```shell curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer '$TOKEN'' -d \ '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"sharklabs-keycloak"}' \ "https://api.digitalocean.com/v2/droplets" ``` ## Getting Started After Deploying Keycloak After your droplet is created, you can access your Keycloak instance by typing the droplet’s IP address in your browser. Your browser is likely to show a Privacy Error, however, this is completely expected as Keycloak 1-Click uses self-signed certificates. If you get a Privacy Error, click on `Advanced` and `Proceed to...`: ![Keycloak Privacy Error](https://do-not-delete-droplet-assets.nyc3.digitaloceanspaces.com/Screenshot%202024-07-03%20at%2018.21.13.png) After this, you will be greeted by the Keycloak login page: ![Keycloak Login Page](https://do-not-delete-droplet-assets.nyc3.digitaloceanspaces.com/Screenshot%202024-07-03%20at%2018.28.22.png) *If you see the Site can’t be reached or Nginx 502 Bad Gateway, give it 2-3 minutes and reload the page. If it still does not load, you may need a larger droplet size. Minimum Requirements are 2GB Ram and 2CPUs.* ## Retrieve login credentials To retrieve login credentials, SSH into your Keycloak Droplet 1-Click: ``` $ ssh root@ ``` Now you can read the file with Keycloak passwords by using: ``` $ cat ~/.digitalocean_passwords ``` This will return 3 passwords - `KEYCLOAK_ADMIN_PASSWORD`: Use this password to log in as an `admin` user. - `KEYCLOAK_DATABASE_PASSWORD`: Password to the database used by Keycloak. - `KEYSTORE_PASSWORD`: Password to the certificates keystore. Now you can log in as an `admin` user with the `KEYCLOAK_ADMIN_PASSWORD` you just retrieved! ## Configuring Nginx After you have created your Keycloak droplet, it is highly recommended you configure an Nginx server block file for each site you plan to host. Doing so will make the default configuration the fallback, as intended, and will make it easier to manage changes when hosting multiple sites. To do so, you’ll need to create two things for each domain: a new directory in /var/www for that domain’s content, and a new server block file in /etc/nginx/sites-available for that domain’s configuration. For a detailed walkthrough, you can follow [How to Set Up Nginx Server Blocks](https://www.digitalocean.com/community/tutorials/how-to-set-up-nginx-server-blocks-virtual-hosts-on-ubuntu-16-04). ## Adding a domain name A domain name allows others to access your website with an encrypted connection. If you intend to host a website on your Keycloak Droplet 1-Click. Keycloak Droplet 1-Click comes with certbot installed, making it easier to enable HTTPS on your 1-Click. First, ensure your domain points to the new droplet IP. If your DNS is managed by DigitalOcean, it should look like this: ![Keycloak Domain Example](https://do-not-delete-droplet-assets.nyc3.digitaloceanspaces.com/Screenshot%202024-07-03%20at%2018.38.33.png) The DNS Host may be the same company you registered the domain with or another entity you designate. To connect your DNS hosting to DigitalOcean, check out [this guide](https://docs.digitalocean.com/tutorials/dns-registrars/). Once your A record is set up, you should configure nginx to host your new domain properly. Detailed instructions can be found in [this article](https://www.digitalocean.com/community/tutorials/how-to-set-up-nginx-server-blocks-virtual-hosts-on-ubuntu-16-04). After you have configured the domain and nginx, you can run certbot to acquire HTTPS certificates for your droplet: ``` $ certbot -–nginx -d ``` After you answer questions from certbot, your HTTPS setup is finished. Use your domain in the web browser to access your Keycloak Droplet. ## Droplet summary - UFW firewall allows only SSH (port 22, rate limited), Nginx (ports 443 and 80) and Keycloak (ports 8443 and 9000). - Keycloak is running under the docker container. To check logs use: ``` $ docker logs keycloak ``` - Nginx is configured to redirect requests to Keycloak, acting as a reverse proxy for the application server. - The message of the day (MOTD) shows the system and database user passwords, which are also saved in /root/.digitalocean\_passwords. - The Keycloak dockerfile can be located at `/var/digitalocean/Dockerfile`.