Running SpringBot

SpringBot has two parts:

• Server-side
• Client-side

These can be run separately or together, depending on your needs. Both client and server have the option to run in their development modes or build to create artifacts.

This article assumes you have already setup your development environment, as outlined in SpringBot Development Environment: Source Code. Your application can be cloned into any directory, but for the sake of this article, we will make a common directory for all our future applications.

For this guide, we assume Windows users are using Powershell and Linux/Mac users are using Bash as their shell.

First time setup

Configuration

You configure your database credentials by setting environment variables. There are two ways to do this:

• Setting the environment variables for the current session. They will be removed upon exit of the shell or a restart of your system, or
• Setting the environment variables to persist.

Current session only

Windows

$env:DATA_SOURCE_PASSWORD="bots"     
$env:DATA_SOURCE_USERNAME="codebots"  
$env:DATA_SOURCE_URL="jdbc:postgresql://localhost:5432/codebots"

To test, run each of the following commands and you should see the values printed to your screen,

$env:DATA_SOURCE_PASSWORD    
$env:DATA_SOURCE_USERNAME
$env:DATA_SOURCE_URL

You should see something like the following,

PS > $env:DATA_SOURCE_PASSWORD
bots
PS > $env:DATA_SOURCE_USERNAME
codebots
PS > $env:DATA_SOURCE_URL
jdbc:postgresql://localhost:5432/codebots

Linux/Mac

export DATA_SOURCE_PASSWORD=bots
export DATA_SOURCE_USERNAME=codebots
export DATA_SOURCE_URL=jdbc:postgresql://localhost:5432/codebots

To test, run each of the following commands and you should see the values printed to your screen,

echo $DATA_SOURCE_PASSWORD    
echo $DATA_SOURCE_USERNAME
echo $DATA_SOURCE_URL

You should see something like the following,

$ > echo $DATA_SOURCE_PASSWORD
bots
$ > echo $DATA_SOURCE_USERNAME
codebots
$ > echo $DATA_SOURCE_URL
jdbc:postgresql://localhost:5432/codebots

Persistent variables

To persist them, add them to your application-dev.properties file. You can read more about your application properties in the Advanced SpringBot lesson.

Navigate to your projects serverside directory. e.g.

cd /data/repository/[projectname]/serverside/

Edit the application properties file for the development environment. This can be found at src/main/resources/application-dev.properties.

Update the properties and switch the flag for the protected region on:

# % protected region % [Customise your connection details here] on begin
spring.datasource.url=${DATA_SOURCE_URL:jdbc:postgresql://localhost:5432/codebots}
spring.datasource.username=${DATA_SOURCE_USERNAME:codebots}
spring.datasource.password=${DATA_SOURCE_PASSWORD:bots}
 ...

Make sure you turn on the protected region by changing # % protected region % [Customise your connection details here] off begin to # % protected region % [Customise your connection details here] on begin (off to on)

Gradle wrapper

Within the serverside directory of your project, seed the gradle wrapper.

cd /data/repository/[projectname]/serverside
gradle wrapper

This should take a while as it is downloading and compiling dependencies for faster future builds. Please be patient.

Server-Side

The following instructions assume you are inside of the serverside directory of your target project.

Being a Java framework, Spring, gives us many options when it comes to build tools. Within SpringBot we have chosen to use Gradle as our build automation weapon of choice.

We use Gradle for all tasks from dependency management to building for production.

A good introduction to Gradle get be found in the Gradle Getting Started guide.

Running for Development

For Windows, use gradlew.bat in place of gradlewin all commands, .

Pull dependencies and run. As mentioned above, running the second ./gradlew option with the profile parameter passed through will set the dev environment profile.

Navigate to your projects serverside directory. e.g.

cd /data/repository/[projectname]/serverside/

Run the gradle wrapper with a argument setting the current application profile to dev

Windows

./gradlew.bat bootRun -P profile=dev

Linux/Mac

./gradlew bootRun -P profile=dev

You can also set the following environment variables to ensure you run using the development profile.

Copy and paste in the following:

Windows

$env:SPRING_PROFILES_ACTIVE="dev"

Linux/Mac

export SPRING_PROFILES_ACTIVE=dev

Run the gradle wrapper with no arguments:

Windows

./gradlew.bat bootRun

Linux/Mac

./gradlew bootRun

1. The first time this runs will take a while as the dependencies are setup.
2. The progress bar will only reach 75%. It will never reach 100% as it is a Java application and will only reach 100% when the application has finished running. The bootstrapping should take one to two minutes to run, depending on your available system resources. You should see something like this:

3. Your server is now available on http://192.168.56.101:8080/swagger-ui.html or http://localhost:8080/swagger-ui.html if you are running locally. To test this, you can put the URL into your host machines browser address bar. Once loaded you should see a white label error:

   

4. You also have Swagger definitions available through your application on http://192.168.56.101:8080/swagger-ui.html or if you are running locally http://localhost:8080/swagger-ui.html.

   

Client-Side

Running for Development

While it is not strictly necessary, it is recommended that you run your client with your server as the client does require the necessary APIs to operate.

If you used the Ubuntu 18.04 Virtual Machine Setup the please skip to the Virtual Machine Development Environment Setup section.

Local Machine Development Environment

1. Navigate to your projects clientside directory by entering cd /data/local/[projectname]/clientside
2. To install dependencies, enter: yarn install.
3. Once this process is finished, you should see something like this:
4. To run the development server, enter yarn start
5. Once your clientside code has finished compiling, you should see something like this:
6. You will now be able to access your client-side application from the host machine at http://localhost:4200, and you should see a login screen:

You will not be able to log in unless you have setup your server to run. The client-side in dev mode expects the server to be accessible on the same host as the client and on port 8080.

Virtual Machine Development Environment Setup

1. Navigate to your projects clientside directory, enter: cd /data/repository/[projectname]/clientside

2. Update the environment variables for the development environment

    sudo nano src/environments/environment.ts
   

3. Update the API_URL to point to the IP of your virtual machine. Update the API_URL in the environment config file to look like this:

    export const environment = {
        production: false,
        API_URL: 'http://192.168.56.101:8080',
        // % protected region % [Add any additional environment properties here] off begin
        // % protected region % [Add any additional environment properties here] end
    };
   

4. Press Ctrl + X to exit, type “Y” then hit Enter to save the file and exit the editor
5. To install dependencies, enter: yarn install.
6. Once this process is finished you should see something like this:
7. To run your development server, enter: yarn start
8. Once your clientside code has finished compiling, you should see something like this:

You will now be able to access your client-side application from the host machine at http://192.168.56.101:4200 and you should see a login screen:

This should be the IP address of your virtual machine . It is worth noting that you will not be able to log in unless you have setup your server to run. The client-side in dev mode expects the server to be accessible on the same host as the client and on port 8080.

Logging In

If your serverside is running and you have created an entity in your Entity Diagram that has the User Extension Overview, then there should be a test user setup available within the development environment. For example, if you have a Staff entity with a User Extension, you should be able to log in with the credentials:

Username: staff@example.com
Password: password

These credentials are only available when running the dev profile (see above).

After logging into the application, you should now see your home page:

Building

Instructions on building and deploying your application can be found at the Building and Deploying SpringBot article.