Setup development environment

August 17, 2023 · View on GitHub

Let's get started setting up your development environment.

NOTE The instructions will work better on Linux/Mac, there could be some details that do not work on Windows (help wanted).

There are demo videos while configuring a local environment in Ubuntu 22.04, covering everything, from the JDK install step until the application runs: http://onboarding.wiringbits.net

Table of Contents

Compile-time dependencies
Runtime dependencies
Test dependencies
Deployment setup

Compile-time dependencies

Clone the repository

git clone git@github.com:wiringbits/scala-webapp-template.git

JDK setup, we highly recommend SDKMAN due to its simplicity to switch between different jdk versions, run sdk env to pick the project's suggested jdk or edit sdkman config (~/.sdkman/etc/config) to set sdkman_auto_env=true which picks the project's jdk automatically:

# sdkman_auto_env=true would pick the right jdk when moving into the project's directory
$ cd scala-webapp-template

Using java version 11.0.16-tem in this shell.

# otherwise, you can set the jdk manually with `sdk env`
$ sdk env

Using java version 11.0.16-tem in this shell.

# verify your version
$ java -version
openjdk version "11.0.16" 2022-07-19
OpenJDK Runtime Environment Temurin-11.0.16+8 (build 11.0.16+8)
OpenJDK 64-Bit Server VM Temurin-11.0.16+8 (build 11.0.16+8, mixed mode)

Hint: .sdkmanrc defines our suggested jdk.

Install sbt, run sdk install sbt or follow the official instructions.

Node setup, we highly recommend nvm due to its simplicity to switch between different node versions, run nvm use to pick the project's suggested node version, or follow nvm-instructions to pick the right version automatically:

# nvm can pick the right node version when moving into the project's directory
$ cd scala-webapp-template
Found '~/scala-webapp-template/.nvmrc' with version <16.7.0>
Now using node v16.7.0 (npm v7.20.3)

# otherwise, you can set the node version manually with `nvm use`
$ nvm use
Found '~/scala-webapp-template/.nvmrc' with version <16.7.0>
Now using node v16.7.0 (npm v7.20.3)

# verify your version
$ node --version
v16.7.0

Hint: .nvmrc defines our suggested node version.

Install yarn, most times, npm install --global yarn should be enough (we have tested this with yarn v1), be aware that this must installed at the node version you set in the previous step:
```
# yarn -version
1.22.11
```

That's it, now just run sbt compile to compile the project (the first time it could take several minutes).

Runtime dependencies

Postgres

PostgreSQL is the only required runtime dependency, it can be installed by following the official docs, it can also be run with docker.

What matters is that you can connect to it with psql -U postgres -h 127.0.0.1 (postgres is the default username, if you changed it, you must update the command too).

Hint: We use 127.0.0.1 to force psql to use a TCP connection instead of a unix socket which (localhost), this happens because the app connects to postgres through TCP.

Once you are connected into postgres, we'll create a database for our app, and, any necessary dependencies:

-- create a database for the app
CREATE DATABASE wiringbits_db;

-- connect to it
\c wiringbits_db;

-- create an extension used by the app
CREATE EXTENSION IF NOT EXISTS CITEXT;

AWS Email Service

We are using SES to send emails (like the account verification email, password recovery, etc), what matters is to get AWS keys with access to SES.

This is an optional requirement, if you decide to ignore it, everything should work fine.

direnv

direnv is super handy to define your custom app settings without modifying any of the application files tracked by git (sorry windows). It is optional but highly recommended.

In short, it will allow you to create a .envrc file with all your custom settings, which will be loaded when moving into the project's directory (don't forget the hook)

Custom config

It is very likely that the default settings won't work for you, at least, you will be expected to update the settings to match your postgres credentials (and SES if used).

There are two ways:

Update application.conf Update application.conf to set your environment specific values (just avoid committing these).

Use direnv, create .envrc to export environment variables for your custom settings (don't forget to run direnv allow after that), get inspired by this example, it is unlikely that you will need to change any other settings:

# postgres settings
export POSTGRES_HOST="127.0.0.1"
export POSTGRES_DATABASE="wiringbits_db"
export POSTGRES_USERNAME="postgres"
export POSTGRES_PASSWORD="postgres"

# emails
export EMAIL_SENDER_ADDRESS="test@wiringbits.net"
export EMAIL_PROVIDER=none

# aws, required only if the email provider is AWS
export AWS_REGION="us-west-2"
export AWS_ACCESS_KEY_ID="REPLACE_ME"
export AWS_SECRET_ACCESS_KEY="REPLACE_ME"

Run

Time to run the app:

sbt server/run launches the backend, which is started once you launch a request (like curl localhost:9000), swagger-ui available at http://localhost:9000/docs/index.html.
sbt dev-web launches the main web app at localhost:8080

Hints:

All these apps are automatically reloaded on code changes.
The server app prints the settings after starting, double check that they match your custom settings.
By default, outgoing emails are logged, be sure to check those to look for the email verification links.

Test dependencies

Docker is the only required dependency to run the integration tests.

Each integration test mounts its own clean database through docker, which removes the need to worry about tests polluting data.

Check the official docs to get it installed, it is ideal that docker can be executed without sudo, when this command works, tests must run too: docker run hello-world

Commands:

sbt test runs all the tests.
sbt server/test runs the server tests only.

Hint IntelliJ allows running all tests in a file, or a single test through its UI, which is very handy.

Deployment setup

Check the infra project.