Skip to content
Walther Smulders
This guide is a work in progress and will be updated as the project evolves

Quick Start

This quick start guide assumes you have all the prerequisites installed. If you’re unsure of what you need, see the Prerequisites page for more information.

Clone the project repositories

The project is split into two repositories called canyonlands-spring-api and canyonlands-angular-app respectively.

The back-end project can be found at the following link:

canyonlands-spring-api

Back-end API

Execute the following command in your Terminal:

Clone back-end repository
git clone https://github.com/walthersmulders/canyonlands-spring-api.git

You should now have a directory called canyonlands-spring-api on your local file system.

Back-end API setup, start and test

This project makes use of Docker to run the required infrastructure locally.

In your Terminal window navigate to the root of the project directory, there is a docker-compose.yml file that contains the configuration for the project’s database and identity provider.

To bootstrap the PostgreSQL database and the Keycloak service, run the following docker-compose command in your Terminal:

Start the database and identity provider
docker compose up -d

Upon successful execution of the command, you can verify that the containers are running with the following command:

List running containers
docker ps

You should see the following output:

Output
CONTAINER ID    IMAGE                       NAMES
0804600127b8    postgres:16.2-alpine        canyonlands-db
6dd79af02937    keycloak/keycloak:24.0.2    keycloak

The NAMES column should show the names of the containers that are running.

The canyonlands-db container is the PostgreSQL database container and the keycloak container is the Keycloak identity provider container.

Before starting the back-end project, you need to configure the environment variables.

Inside the root of the project, there is a .env.template file that contains the variable names to be set. Copy the contents of the .env.template file to a new file named .env and set the values accordingly.

  • Directorysrc
    • Directorymain
      • Directoryjava
        • …
  • README.md
  • .env.template copy contents
  • .env create this
  • …

The default values for the environment variables are as follows:

KEYCLOAK_URL        =  http://localhost:8024/realms/canyonlands
POSTGRES_DATABASE   =  canyonlands
POSTGRES_HOST       =  localhost
POSTGRES_PASSWORD   =  password
POSTGRES_PORT       =  5432
POSTGRES_USER       =  admin
LOGGING_LEVEL       =  INFO

Start the back-end API

The canyonlands-spring-api project makes use of Gradle to manage the project’s dependencies and to run the development server.

To start the development server, you have a few options:

  1. IntelliJ IDEA: If you open the project in IntelliJ IDEA, you need to attach the .env file to the run configuration.

    In the Build and Run section of the run configuration, click on the Environment variables to toggle the environment variables section. Once there, click on the ... button and add the .env file found in the root of the project.

  2. Command Line: The project comes with a Gradle wrapper that can be used to start the development server. The build.gradle file contains the necessary configuration to inject the .env file into the run configuration task.

    You can start the development server by running the following command in your Terminal:

    Start the application with Gradle
    ./gradlew bootRun

To verify that the back-end API is running, check the application log output and verify that there aren’t any errors. You should look for the following lines in the log:

Log output
: Tomcat started on port 8080 (http) with context path ''
: Started Application in 3.958 seconds (process running for 4.22)

You can also execute the following cURL command in the Terminal to check the health endpoint of the API:

Check if the API is running
curl --location 'http://localhost:8080/actuator/health'

You should see the following output:

{
  "status": "UP"
}

Postman collection and environment

A Postman collection and environment export can be found in the project’s docs directory.

  • …
  • Directorydocs
    • Directoryapi
      • Local.postman_collection.json
      • Local.postman_environment.json
  • Directorysrc
    • …
  • README.md
  • …
Or you can access the files directly on GitHub

Obtain an OAuth token

In order to interact with any of the API endpoints on the back-end application (apart from the health endpoint) you will need to have a valid OAuth token attached in the request.

There’s a preloaded user in the Keycloak realm, the details for the user is as follows:

username   =  walthersmulders
password   =  walthersmulders
role       =  SYS_ADMIN

This user has a role value of SYS_ADMIN which means it can execute authenticated calls to any of the API endpoints.

  1. Perform a Login and get a token:

    Make use of the username and password combination above and execute the following cURL request:

    Terminal window
    curl --location 'http://localhost:8024/realms/canyonlands/protocol/openid-connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=canyonlands' \
    --data-urlencode 'username=walthersmulders' \
    --data-urlencode 'password=walthersmulders' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'client_secret=yWbjVxoipwXoqSmruM13IJ2GSvQHrM2K'

  2. This should provide a response like:

    {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIg........",
      "expires_in": 18000,
      "refresh_expires_in": 1800,
      "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSld........",
      "token_type": "Bearer",
      "not-before-policy": 0,
      "session_state": "0dc4ebd7-b3bd-44aa-bace-fc580c249e79",
      "scope": "profile email"
    }

  3. Copy the access_token value for use in subsequent API calls.

Perform authenticated API request

The first action to perform should be to register the user. We’ll make use of the access_token copied in the previous step to make an authenticated API call to the /register endpoint.

The access_token contains various claims within the token. These include:

  • preferred_username
  • email
  • given_name
  • family_name

These values are decrypted in the back-end application and used to insert a new user object into the database. A unique userID will be generated upon successful insertion of the new user. This “localized” userID value is used throughout the application to keep track of user specific data.

POST: User Register cURL request
curl --location 'http://localhost:8080/register' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiI..........'

Upon executing the above request you should receive a successful response with an HTTP status code of HTTP 201 Created.

If you look at the application logs you should see something like the following:

User Registration Application Logs
INFO 15687 --- [canyonlands-spring-api] [nio-8080-exec-1] c.w.service.user.RegistrationService     : User registered successfully

Extra credit — Retrieving all users

In order to retrieve a list of all users in the system make an authenticated API call to the /users endpoint.

GET: Get Users cURL request
curl --location 'http://localhost:8080/users' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiI..........'

Upon executing the above request you should receive a successful response with an HTTP status code of HTTP 200 OK and a response body like the following:

[
  {
    "userID": "1c529433-063f-40c2-8dba-4d5a8197fd5b",
    "username": "walthersmulders",
    "emailAddress": "[email protected]",
    "firstName": "Walther",
    "lastName": "Smulders"
  }
]