Scala + http4s codebase containing real world examples (CRUD, auth, advanced patterns, etc) that adheres to the RealWorld spec and API.

This codebase was created to demonstrate a fully fledged fullstack application built with Scala + http4s including CRUD operations, authentication, routing, pagination, and more.

For more information on how to this works with other frontends/backends, head over to the RealWorld repo.

Getting started

Develop and Compile Dependencies

Ensure the following dependencies are installed and configured:

Java SDK 8 or 11 or GraalVM 21.0.x (both Java 8 and 11 variants)
sbt 1.5.x

Setup Steps

Run sbt test to run the test suite
Run sbt run to run the web application

The app is now accessible from localhost:8080.

newman Testing

To run the API spec tests with newman:

Run ./scripts/newman/run.sh to run the API spec test

Note: Node.js 8+ and globally installed newman package are required

Production Packaging (universal format)

To package and run it as an uber-jar:

Run sbt stage to package the application into a universal distribution format (at target/universal/stage/)
Run ./target/universal/stage/bin/realworld to run the web application

Production Packaging (Graal Native Image)

Ensure Graal is downloaded and its binaries folder added to PATH. The most convenient way is to use sdkman to switch between different Java SDK versions (Graal included).

Run sdk env to initialise the shell session using sdkman
Run gu install native-image to configure the native-image binary (incl. agent)

To generate assisted configuration for native image:

java \
  -agentlib:native-image-agent=config-output-dir=src/main/resources/graal/ \
  -cp "target/universal/stage/lib/*" \
  com.hhandoko.realworld.Application

To package and run it as a Graal native image:

native-image \
  --no-server \
  --class-path "target/universal/stage/lib/*" \
  com.hhandoko.realworld.Application

Run ./realworld to run the web application

Alternatively, some scripts are included in the repo to make it easy to download and create native image distribution (limited to Linux and macOS for now):

Run ./scripts/graal/bin/setup.sh to download and setup Graal.
Run ./scripts/graal/bin/dist.sh to create a native image distribution under the /dist directory.

Progress

Backend API implementation:

Please read PROGRESS for more details.

Notes

Scalameta substitutions (svm-subs) are copied over into the repository as the library has not had any updates for a while.

Issues

Native image generation sometimes fail with non-initialized charset issue error message (simply retry until succeeds)
Native image generation with jwt-scala fails (oracle/graal/#1152)
JWT token decoding in native image fails (oracle/graal/#1240)

Contributing

We follow the "feature-branch" Git workflow.

Commit changes to a branch in your fork (use snake_case convention):
- For technical chores, use chore/ prefix followed by the short description, e.g. chore/do_this_chore
- For new features, use feature/ prefix followed by the feature name, e.g. feature/feature_name
- For bug fixes, use bug/ prefix followed by the short description, e.g. bug/fix_this_bug
Rebase or merge from "upstream"
Submit a PR "upstream" to develop branch with your changes

Please read CONTRIBUTING for more details.

License

    Copyright (c) 2019-2021 Herdy Handoko

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

scala-http4s-realworld-example-app is released under the Apache Version 2.0 License. See the LICENSE file for further details.

hhandoko/scala-http4s-realworld-example-app