In this section, we outline the steps to setup your computer for developing and running the Nine-Cards-Back-End (NCBE) application.
Scala Development Tools
- Java SE 8 Development Kit: you can use OpenJDK.
In Ubuntu/Debian, if you have several versions of the JDK installed, you may need to use the
- Scala 2.11.8.
- SBT version 0.13.8 or later.
If you have an older version of SBT, or Scala,
sbt can often bootstrap itself to newer versions.
You should ensure that the
PATH environment variable contains the directories in which the programs
sbt are located.
Postgres Database Setup
The NCBE stores its information in a database, using the [[postgresql]] database system.
It uses a database called
ninecards. To write, run, and test NCBE in your machine, you can create
ninecards_user, with password
In a Debian-based Linux distribution, you can use the
apt-get command to install the packages:
sudo apt-get install postgresql postgresql-contrib postgresql-client pgadmin3
For OS-X users, you can use any of the tools mentioned here.
Setting Client authentication
In PostgreSQL, the “Client Authentication” method used for opening a client’s session, can be set differently for each user, database, or connection.
This configuration is kept in a file called
- In Debian-based distributions, it is located in the directory
- In OS-X, you can find it using the command
locate pg_hba.conf, or following these instructions.
To run and test the NCBE on our local host using the
ninecards_user user, we need to open channels for the command line and for the JDBC driver.
The JDBC used by the NCBE enters the database through a local IPv4 connection. The following line should be in
pg_hba.confto allow this to happen:
host ninecards all 127.0.0.1/32 md5
For setting up the database for tests, we want to enter the database from a shell terminal, using the command
ninecards_user. To allow this, you should have the following line in
local ninecards ninecards_user md5
You need to restart the Postgres server for the changes to take effect. To do this, run the following command in a terminal:sudo service postgresql restart
Setting user and password for local development:
To create the
ninecards database and the
ninecards_user we need to open a session as the PostgreSQL-server administrator.
The administrator is the DBMS user called
postgres, and by default it is configured to use
Under this method, you can only open a DBMS session from a OS user with the same name.
Thus, you need to follow these steps:
Startsudo -u postgres psql
psql, the PostgreSQL command-line client, as the
psql, create the database, the user, the permissions, and exit:
create database ninecards ; create user ninecards_user PASSWORD 'ninecards_pass'; GRANT ALL ON DATABASE ninecards TO ninecards_user; \q
From your own OS user, you should now be able to open a postgres-client session using the following command:
psql --username=ninecards_user ninecards --password
Database Schema Migrations
The evolutions for the data schema of the
ninecards database are managed by
sbt, the build system, using the flyway SBT plugin.
Flyway needs a few configuration parameters to access the database.
An overview on how to pass these settings is given in the Database Connection Configuration section.
Suffice it to say that, to run the migrations on your local database, you can use the configuration values written in the
You can pass this file to
sbt, by opening a shell session in the
nine-cards-backend root directory and executing the following command:
This should open an interactive
sbt session. Inside this session,
you can clear the database with the command
flywayClean, or perform the database migrations with
flyway connects to the database through JDBC, you would need to configure the PostgreSQL authentication file
pg_hba.conf, as explained in a previous section.
Running and testing the application
From a command line, within the root directory of the project, run the following:
$ sbt -Dconfig.file="modules/api/src/main/resources/localhost.conf" > project api > run
To check that the application has started correctly, you can try accessing the Swagger apidocs in the
Database Connection Configuration
The configuration is managed using Lightbend’s configuration library.
The default configuration is at the
modules/api/src/main/resources/application.conf file, which
loads the values for some configuration settings from the environment. This gives you several ways to
define your configuration settings:
sbt passing the configuration settings, each setting having the form
For example, to run the application in your local host, you would pass the database configuration as follows:
sbt -Ddb.default.driver="org.postgresql.Driver" -Ddb.default.url="jdbc:postgresql://localhost/ninecards" -Ddb.default.user="ninecards" -Ddb.default.password="ninecards_pass"
b. Write a configuration file with your settings, and pass that file to
sbt using the
For example, to run the application in your local host, you can pass the
localhost.conf file, as follows:
c. Set the shell environment variables used by the default configuration file.
bash, this is done with the command
export VAR=[VALUE], without spaces.
For instance, to initialize the environment variables related to the database configuration, and set them for local execution, you would run the following:
export DB_DEFAULT_DRIVER="org.postgresql.Driver" export DB_DEFAULT_URL="jdbc:postgresql://localhost/ninecards" export DB_DEFAULT_USER="ninecards" export DB_DEFAULT_PASSWORD="ninecards_pass" Note that there should be no whitespace around the `=` sign. Note also that the settings only remain for the bash session. You can write such settings in the `.bashrc` file, or in a executable shell script.
Testing and running the endpoints with Postman
Once the application is running and bound to the chosen port, you can run the endpoints by issuing HTTP
requests with any HTTP client, like
In particular, we use the Postman graphic client.
Postman allows us to write a collection of HTTP requests and store it as a text file.
These requests can depend on variables read from an environment that is also stored as a text file.
Deployment - Preparing the Application
The NCBE is a server-side application, and it should be deployed as a
Infrastracture as a Service (IaaS)
or Platform as a Service (PaaS).
To do this, we need to pack the application’s source code, the binary classes, its transitive dependencies,
and the configuration values into a self-contained executable file (or fat-JAR).
This is done with the
This plugin was originally ported from codahale’s assembly-sbt and may have been inspired by Maven’s assembly plugin.
Its goal is to build a fat JAR of your project with all of its dependencies.
To execute the plugin, you should open a shell session at the project’s root directory and run the following command:
$ sbt "project api" assembly
Note that you should provide the database configuration variables to the
sbt command, using any of the methods described above.
sbt fails due to the
By default, the fat jar will be created in the
Running SQL evolutions in Heroku
This task should be done manually, as follows:
$ heroku pg:psql --app nine-cards < /path/to/file.sql