popstellar: be2-scala branch

Proof-of-personhood, spring 2021: Scala language back-end

[TOC]

Running the project

Make sure to open be2-scala project folder as the root of your IDE workspace.

There are two main possible ways of running the project :

Option 1: Intellij / VSCode

1. Import the project using your editor
2. Modify the default Run configuration 'Server', to include the following VM option:

-Dscala.config=src/main/scala/ch/epfl/pop/config -Dscala.security=src/security (click on Modify options and tick Add VM options if VM options box does not appear initially)

3. Due to IntelliJ not executing sbt tasks on project compilation, our custom sbt tasks are not being run. Head to IntelliJ IDEA $⟹$ Preferences $⟹$ Build, Execution, Deployment $⟹$ Build Tools $⟹$ sbt and tick the option to use sbt shell for builds. Click on Build $⟹$ Rebuild Project to execute our sbt task.

Troubleshooting (IntelliJ)

Here are a few points that students often forget when setting up IntelliJ:

• make sure you have the Scala plugin installed on your IDE. You may install it directly from IntelliJ's settings (IntelliJ IDEA $⟹$ Preferences $⟹$ Plugins)
• make sure you actually have sbt on your machine
• if IntelliJ displays a banner stating "No Scala SDK in module", then make sure you actually have a version of the SDK on your machine (File $⟹$ Project Structure... $⟹$ Global Libraries). If not, simply install it using the + sign. We recommand SDK version 2.13.x

Option 2: SBT

Using sbt -Dscala.config="path/to/config/file" -Dscala.security="src/security" run.

There is a default configuration ready to use in src/main/scala/ch/epfl/pop/config which contains an application.config where the configuration lives. This can be updated if needed.

# Snapshot of application.config

ch_epfl_pop_Server {
 http {
     interface = "127.0.0.1"
     port = "8000"
     client-path = "client"
     server-path = "server"
   }
}

Consequently, from be2-scala/ folder run the following:

 sbt -Dscala.config="src/main/scala/ch/epfl/pop/config" -Dscala.security="src/security" run

---

Security keys

The scala server needs security keys to run properly. Their location must be specified using the -Dscala.security flag.

By default, the folder is src/security and the script src/security/generateKeys.sh can be used to generate fresh keys.

Go to the folder src/security and run ./generateKeys.sh, or directly run (cd ./src/security/ && ./generateKeys.sh) from the current directory.

Security keys are also needed to run the tests. The process is the same except that tests expect to find the keys in a test folder (for example src/security/test), so run the script generateKeys.sh with the argument -test to take that into account. You don't need to generate new keys every time you run the tests.

Go to the folder src/security and run ./generateKeys.sh -test, or directly run (cd ./src/security/ && ./generateKeys.sh -test) from the current directory before running the tests.

Note that the script generateKeys.sh requires openssl to be available on the system.

---

Preprocessor flags

We introduced two custom preprocessor flags, one of which you already encountered:

• Config file location (mandatory): location of the config file on the system with respect to the be2-scala folder
• Security keys location (mandatory): location of the security keys on the system with respect to the be2-scala folder
• Database auto-cleanup (optional). By adding the -Dclean flag, the database will be recreated everytime the server starts running

---

External libraries

The project relies on several sbt dependencies (external libraries) :

• websockets : akka-http for websocket server. It uses akka-streams as dependency.
• database : leveldb which relies on both snappy (for compression/decompression) and akka-persistence
• Json parser : spray-json for Json encoding/decoding
• encryption : tink to verify signatures
• encryption : kyber to encrypt and decrypt messages of an election
• testing : scalatest for unit tests
• Json schema validator : networknt for Json schema validation
• Json Web Tokens (jwt) : java-jwt to generate and sign jwt
• Qrcode : zxing to generate Qrcodes
• security keys : openssl only used in src/security/generateKeys.sh to generate a pair of RSA keys

---

Coding convention

Our coding guidelines can be found here.

Install java and sbt on linux and Mac

skdman does a pretty good job for installing the required environment:

# install sdkman
curl -s "https://get.sdkman.io" | bash
# install java temurin 17
sdk install java 17.0.8-tem
# install sbt
sdk install sbt
# check that everything went well
java -version
> openjdk 17.0.8 2023-07-18 LTS

Package and run

Build the jar with:

sbt assembly

Run by specifying the configuration file:

java -Dscala.config="src/main/scala/ch/epfl/pop/config" -jar target/scala-2.13/pop-assembly-<version>-SNAPSHOT.jar
> ch.epfl.pop.Server online at ws://127.0.0.1:8000/client