DEV Community: Milan Wittpohl

Share your SpriteKit experiences...

Milan Wittpohl — Fri, 10 Jul 2020 20:34:20 +0000

I build a 2D game a few years back using SpriteKit. Back then SpriteKit was just released and not very stable. I plan to rebuild the game towards the end of the year and wonder if I should stick with spritekit. Does anyone have recent experience with the framework? Highly appreciate any kind of discussion.
Cheers

I built a tool that lets you see which servers you communicate with every time you open a webpage.

Milan Wittpohl — Thu, 30 Jan 2020 14:04:17 +0000

Website Roots

Every time you open a website, you communicate with at least one server to load the site. Which servers you interact with depends on the webpage you load. While some of the servers are used to load the content, some are used to keep track of you through the web. Furthermore, it is not at all or difficult to find out which information are shared with the respective servers. Shouldn't a website tell you which information it shares with what companies in a transparent and understandable way? I built a tool that lets you easily see which servers you communicate with every time you open a webpage.

Check it out. → https://milanwittpohl.com/projects/website-roots/

Part V: Automating The Build- And Deployment-Process using GitLab CI/CD

Milan Wittpohl — Sun, 26 Jan 2020 14:30:00 +0000

In-Depth Tutorial: Building a Modern, Full-Stack Web App

In this series, I want to build a modern, extensible, yet simple set up that allows me to quickly build and deploy a web-frontend, -backend and database. While this project functions as a template for future projects, we still need some sort of goal. This is why we will create the simplest todo-app ever. Todo-apps are a good use case as it is simple but still covers most aspects of a modern application. We will have to:

connect a database to store todos
work with that database by reading, creating, updating and deleting entries
create a backend that exposes a REST-API for our frontend
secure our backend properly
build a frontend that works well with data from an API

There are several ways to build this modern web-application. I chose the following frameworks, each of which is covered in one tutorial:

Prerequisite

Good knowledge of object-oriented programming and java
Good knowledge of javascript
Basic knowledge of the terminal
A mac - While all of this should also work on windows I did not spend any time to check for or provide solutions for windows

Automating The Build- And Deployment-Process

Okay, at this point we already achieved a lot. Now, we are just showing off. Wouldn't it be great if you wouldn't have to build and deploy your application? If it would just magically do it all automatically. We can achieve this using GitLab and CI. It is common to manage code using a git repository. After this tutorial, our applications will automatically build and deploy whenever we make a commit to the master branch. I will not cover the basics of git here, for that I recommend this series by atlassian. To complete this tutorial you will need a GitLab account and push this project into a new repository. Again, we could achieve the same by using bitbucket or GitHub. GitLab is just my personal preference.

After setting up your GitLab project you will find a CI/CD tab on the left sidebar. This basically enables us to run a script that, if it succeeds deploys our app. If you want to lear more about CI and CD have a look here.

GitLab automatically looks for a .gitlab-ci.yml file in the project root directory. If present it will run a pipeline. Create this file and add the following code, make sure to replace all placeholders.

    variables:
      APP_NAME_FRONTEND: "<YOUR FRONTEND APP NAME>"
      APP_NAME_BACKEND: "<YOUR BACKEND APP NAME>"

    stages:
      - build
      - deploy

    Build-Deploy-Frontend-to-Heroku:
      stage: build
      image: docker:latest
      services:
        - docker:dind
      only:
        - master
      script:
        - echo "Deploying Frontend..."
        - docker login -u _ -p $HEROKU_API_KEY registry.heroku.com
        - docker build --file=frontend/frontend.dockerfile --rm=true -t registry.heroku.com/$APP_NAME_FRONTEND/web .
        - docker push registry.heroku.com/$APP_NAME_FRONTEND/web
        - docker run -e HEROKU_API_KEY=$HEROKU_API_KEY wingrunr21/alpine-heroku-cli:latest container:release web -a $APP_NAME_FRONTEND
        - echo "Frontend Deployment Complete!"

    Build-Backend:
      stage: build
      image: gradle:6.0.1-jdk13
      before_script:
        - export GRADLE_USER_HOME=`pwd`/backend/.gradle
      script:
        - echo "Building Backend..."
        - cd ./backend
        - gradle build
        - echo "Backend Build Complete!"
      cache:
        key: "$CI_COMMIT_SHA"
        policy: push
        paths:
          - backend/build
      artifacts:
        paths:
          - backend/build/libs/*.jar
        expire_in: 1 week
      only:
        - master

    Deploy-Backend-to-Heroku:
      stage: deploy
      image: docker:latest
      services:
        - docker:dind
      only:
        - master
      script:
        - echo "Deploying Backend..."
        - docker login -u _ -p $HEROKU_API_KEY registry.heroku.com
        - docker build --file=backend/backend.dockerfile --rm=true -t registry.heroku.com/$APP_NAME_BACKEND/web .
        - docker push registry.heroku.com/$APP_NAME_BACKEND/web
        - docker run -e HEROKU_API_KEY=$HEROKU_API_KEY wingrunr21/alpine-heroku-cli:latest container:release web -a $APP_NAME_BACKEND
        - echo "Backend Deployment Complete!"

Let's go through each part of the file.

Variables

These variables will be used in the other parts.

Stages

Each block below stages (Build & Deploy Frontend to Heroku, Build Backend, Deploy Backend to Heroku) is a job to GitLab. Each job belongs to one of the following stages

build → this is run in parallel by GitLab and should be used to build the front- and backend
test → test the application, we don't do this here
deploy → If all jobs passed the deploy stage to deploy our app is executed

We have only the two stages build and deploy here.

Build & Deploy Frontend to Heroku

This job builds and deploys our frontend to Heroku. It would be cleaner to have two separate jobs to build and deploy the frontend. However, I' satisfied with it being this way for now.

As the job does both it doesn't really matter if we set the stage to build or deploy
As we will execute docker commands we use the docker image as a base for or job with the docker in docker (dind) service
The job should only be executed on the master branch
The script contains
- The login to our Heroku account - as we did in the last tutorial
- Building the docker image (remember the build process of the frontend is part of the dockerfile) - as we did in the last tutorial
- Pushing the image to Heroku - as we did in the last tutorial
- Lastly we release the app. What's new here is that we use a predefined image as we need the heroku cli.

Build Backend

This job builds our backend to Heroku.

As the job build the backend, the stage is set to build
We will need gradle, so we select the image needed
Next we need to tell gradle where its home directory is
The script contains
- Navigating into the backend folder
- Building the app using gradle
Since we are building a .jar file, we declare it as artefact so we could download it from gitlab if needed. We also set it to expire in one week
We also cache the artifact
Lastly, we specify that the job should only be executed on the master branch

Deploy Backend to Heroku

This is where we depoy the backend
This is basically the same procedure as for the frontend

Setting the Heroku API Key

In our gitlab-ci file we reference to the heroku API key. We wouldn't want to store this in our file for security reasons. That is why we store it as a gitlab variable. Go to settings → CI /CD and then to variables to create a new one.

If you commit this file to your gitlab repository you will see a new pipeline running your jobs. After there are all done your application was deployed successfully to heroku. From now on you can develop locally using and then build and deploy your app by simply committing your changes to the master branch.

This was the final part of this tutorial series. I would really like to hear your feedback.
You can find me on twitter, instagram or send me an email.

This tutorial was originally published on my personal website.

Part IV: Deploying Our Front- & Backend In The Cloud

Milan Wittpohl — Sun, 26 Jan 2020 14:29:52 +0000

In-Depth Tutorial: Building a Modern, Full-Stack Web App

connect a database to store todos
work with that database by reading, creating, updating and deleting entries
create a backend that exposes a REST-API for our frontend
secure our backend properly
build a frontend that works well with data from an API

There are several ways to build this modern web-application. I chose the following frameworks, each of which is covered in one tutorial:

Prerequisite

Good knowledge of object-oriented programming and java
Good knowledge of javascript
Basic knowledge of the terminal
A mac - While all of this should also work on windows I did not spend any time to check for or provide solutions for windows

Deploying Our Front- & Backend In The Cloud

After the first three parts all the hard work is done. We covered a lot, great job! The goal of this and the next part is that we want to deploy our web application in the cloud. This can be helpful early on to test your idea or to deploy your application later on when it's already more progressed. As with everything else, there are a million ways to do this. I wanted to specifically find a way to run the application in the cloud for free (for a limited number of hours each month). Heroku offers exactly this and makes it easy to deploy our docker containers.

If you want to get started with Heroku I suggest you quickly skim through their website and docs. To complete this and the next tutorial you will need a free Heroku account.

I will quickly go over the basics of how Heroku works:

An app runs on Dynos
There three dyno configurations
- Web → "Web dynos are dynos of the “web” process type that is defined in your Procfile. Only web dynos receive HTTP traffic from the routers."
- Worker → "Worker dynos can be of any process type declared in your Procfile, other than “web”. Worker dynos are typically used for background jobs, queueing systems, and timed jobs. You can have multiple kinds of worker dynos in your application. For example, one for urgent jobs and another for long-running jobs. For more information, see Worker Dynos, Background Jobs and Queueing."
- One-off → One-off dynos are temporary dynos that can run detached, or with their input/output attached to your local terminal. They’re loaded with your latest release. They can be used to handle administrative tasks, such as database migrations and console sessions. They can also be used to run occasional background work, as with Heroku Scheduler. For more information, see One-Off Dynos.
While each app can have multiple dynos, they all run the same program within each configuration. If you have more than one web dyno, heroku will distribute the requests between them
With a free account you can run dynos for 450 hours for free (additional 550 hours if you add your credit card, without being charged)
Free dynos will (with the exception of workers) will also fall asleep after being idle for 30 minutes, this way you don't have to worry about your free dyno hours

Heroku Set-Up

If you look into the docker-compose.yml file we created in the last tutorial, you will see that we have three apps/services.

A database
The backend
The frontend

To run our application on heroku we will

create an heroku application for our backend, that will run a web dyno (as it receives http requests)
add a mongodb to our backend app
create a heroku application for our frontend, that will run a web dyno (as it receives http requests)

Create the Heroku Frontend & Backend Application

After you created your account, go to the heroku dashboard and click on "new" and create new application. Give your application a unique name for the frontend, choose a region and create the app. For the backend, again go to the heroku dashboard and click on "new" and create new application.

For our backend we will also need a mongodb. Click on "configure add-ons" and type in the search bar. Select "mLab MongoDB" and the free sandbox plan. Thats it.

Build & Deploy Apps

To build and deploy the apps navigate to your projects root folder in the terminal and execute the following commands.

    # Login to heroku
    # Your heroku api key can be found in your account settings
    docker login -u _ -p <YOUR HEROKU API KEY> registry.heroku.com

    # Build the applications and tag them accordingly
    docker build --file=frontend.dockerfile --rm=true -t registry.heroku.com/<NAME OF YOUR FRONTEND APP>/web .
    docker build --file=backend.dockerfile --rm=true -t registry.heroku.com/<NAME OF YOUR BACKEND APP>/web .

    # Push the images to heroku
    docker push registry.heroku.com/<NAME OF YOUR FRONTEND APP>/web
    docker push registry.heroku.com/<NAME OF YOUR BACKEND APP>/web

    # Release/Run the apps
    heroku container:release web -a <NAME OF YOUR FRONTEND APP>
    heroku container:release web -a <NAME OF YOUR BACKEND APP>

That was it. Amazing, right? Open your frontend application in the browser with /login and you should find your login page.

Congratulations for completing this tutorial!!!

As this is my first tutorial series, I would really appreciate feedback. You can find me on twitter, instagram or send me an email.

This tutorial was originally published on my personal website.

Part III: Dockerizing Our Front- & Backend

Milan Wittpohl — Sun, 26 Jan 2020 14:29:37 +0000

In-Depth Tutorial: Building a Modern, Full-Stack Web App

connect a database to store todos
work with that database by reading, creating, updating and deleting entries
create a backend that exposes a REST-API for our frontend
secure our backend properly
build a frontend that works well with data from an API

There are several ways to build this modern web-application. I chose the following frameworks, each of which is covered in one tutorial:

Prerequisite

Good knowledge of object-oriented programming and java
Good knowledge of javascript
Basic knowledge of the terminal
A mac - While all of this should also work on windows I did not spend any time to check for or provide solutions for windows

Dockerizing Our Front- & Backend

At this point we have a front- and backend that runs perfectly on our local machine. While this tutorial will make more sense if you completed the previous parts, it can also be helpful in general. The goal of this part is that we want to prepare our web-apps for easy and modern deployment. We want to be able to quickly run our front- and backend on any machine and have the ability to scale the application if needed. As with everything else there are plenty of ways to accomplish it. For this series we will work with Docker as it has gained incredible popularity over the past years. This tutorial is split into four subparts:

What is Docker?
Dockerizing the frontend
Dockerizing the backend
Running it all at once

What is Docker?

There are millions of explanations on what docker is all over the internet. I want to touch the most important parts but I won't go into details here. My main points were taken from this video.

Lets say we built our backend as jar-file and tested it locally. Now we need to find a place in the cloud to run it. The first challenge that we encounter now is that we can not guarantee that our backend runs in the cloud just like it does locally. Only if the cloud environment is the same as our local environment, we could make such a promise. To get the gap between our local and the cloud environment as small as possible we need to tell our cloud-provider what we need. However, as a cloud provider you can not have a million developers tell you how their individual cloud setup should look like. That is why cloud-providers offer different packages. They vary between providing a (virtual) machine and providing us with a static environment to run our application in. In case of an individual machine it is now up to us, the developer, to make sure the machine behaves as our local machine. That costs too much time and is also expensive as we don't really need an entire machine. We just need a place to run our jar-file. In case of providing us with a static environment we would now have to make sure that our local environment behaves the same. This isn't useful either. Exactly here becomes docker useful.

Docker provides a common ground and is literally comparable with real-life-shipping-containers. A banana-company only worries about how to get their bananas into the container. Once it is closed it does't matter what is in there. It is basically treated like every other container and the shipping-companies know how to work with it. Docker provides a standard that is flexible enough but also makes sure the software runs in the cloud the same way it does locally.

We use docker to create a docker-image of our app. Just image we would burn it on a CD. That image is build using a dockerfile that defines how the docker-image should be built. That image can then be used inside a docker-container.

Docker is a powerful tool and provides more useful features (e.g. scaling). However this is not as relevant here.

Dockerizing the frontend

To dockerize the frontend please make sure that you have docker installed. Additionally we have to look at our base url in config.nuxt.js. You see, if we would deploy our app in the cloud as it is, it would always think our backend is reachable at localhost:8080. That is why we have to extract every environment specific variable.

Extracting environment specific variables

In our frontend we basically have one environment specific variable and that is the URL of our backend.

You may recall that we useed the proxy module in the nuxt.config.js file. All we have to do here is add the environment variables. If no value is present we set it to a default value (http://localhost:8080/)

    proxy: {
        '/api/': process.env.PROXY_API || 'http://localhost:8080/'
    },

Creating the dockerfile

Next we will create a dockerfile in our frontend folder called frontend.dockerfile. Our docker file contains the following code.

    # We don't want to start from scratch.
    # That is why we tell node here to use the current node image as base.
    FROM node:alpine3.11

    # Create an application directory
    RUN mkdir -p /app

    # The /app directory should act as the main application directory
    WORKDIR /app

    # Copy the app package and package-lock.json file
    COPY frontend/package*.json ./

    # Install node packages
    RUN npm install

    # Copy or project directory (locally) in the current directory of our docker image (/app)
    COPY frontend/ .

    # Build the app
    RUN npm run build

    # Expose $PORT on container.
    # We use a varibale here as the port is something that can differ on the environment.
    EXPOSE $PORT

    # Set host to localhost / the docker image
    ENV NUXT_HOST=0.0.0.0

    # Set app port
    ENV NUXT_PORT=$PORT

    # Set the base url
    ENV PROXY_API=$PROXY_API

    # Set the browser base url
    ENV PROXY_LOGIN=$PROXY_LOGIN

    # Start the app
    CMD [ "npm", "start" ]

Hopefully, the comments on each line explain what's going on. To build the image we simply execute this command on the terminal. Make sure to run it from your projects root directory!

    docker build --file=frontend/frontend.dockerfile  -t playground-web-frontend .

—file → The file to use for the build
-t → To identify our image we tag it
. → The location of the build context (the app). In our case the current directory, referenced as .

Dockerizing the backend

Similar to our frontend we have to extract every environment specific variable before we can dockerize or backend.

Extracting environment specific variables

We have two environment specific variables in our backend. The url of or frontend and the url of our database.

All environment specific variables are set in the application.properties file under resources. Each line contains the key and the value. For the value we will set it to an environment variable (that we will provide through docker) or a default value. Insert the following code.

    spring.data.mongodb.uri=${MONGODB_URI:mongodb://localhost:27017/todo}
    server.port=${PORT:8080}

You may wonder why we haven't set the URI for mogoDB before. That is because spring per default assumed to find the mongoDB under that URI. However, that will change once we deploy it. That is why we extract it. The server port will be used in the next part of the tutorial by heroku.

Creating the dockerfile

Next we will create a dockerfile in our backend folder called backend.dockerfile. Our docker file contains the following code.

    # We don't want to start from scratch.
    # That is why we tell node here to use the openjdk image with java 12 as base.
    FROM openjdk:13

    # Create an application directory
    RUN mkdir -p /app

    # The /app directory should act as the main application directory
    WORKDIR /app

    # Copy or project directory (locally) in the current directory of our docker image (/app)
    COPY backend/build/libs/*.jar ./app.jar

    # Expose $PORT on container.
    # We use a varibale here as the port is something that can differ on the environment.
    EXPOSE $PORT

    # Start the app
    CMD [ "java", "-jar", "./app.jar" ]

Hopefully, the comments on each line explain what's going on.

There is one big difference between the frontend- and the backend-dockerfile. The former contains code to build the application. If we make changes to the backend, we will need to build it first using this command.

    gradle build

To build the image we simply execute this command on the terminal. Again, make sure to run it from your projects root directory!

    docker build --file=backend/backend.dockerfile  -t playground-web-backend .

—file → The file to use for the build
-t → To identify our image we tag it
. → The location of the build context (the app). In our case the current directory, referenced as .

Running it all at once

Now that we have everything we need we will use docker-compose to fire everything up. The docker compose tells docker which services (with which images) to start and also sets the environment variables. Create a new file docker-compose.yml in your project's root folder.

    version: '3'
    services:
      playground-web-db:
        image: mongo:latest
        environment:
          MONGO_INITDB_DATABASE: playground-web
        ports:
          - 27017:27017
      playground-web-frontend:
        image: playground-web-frontend:latest
        environment:
          PORT: 3000
          PROXY_API: http://playground-web-backend:8080/
        ports:
          - 3000:3000
      playground-web-backend:
        image: playground-web-backend:latest
        environment:
          MONGODB_URI: mongodb://playground-web-db:27017/playground-web
        ports:
          - 8080:8080

To run the app execute

    docker-compose -f docker-compose.yml up

Your application should start and run successfully.

Congratulations for completing this tutorial!!!

As this is my first tutorial series, I would really appreciate feedback. You can find me on twitter, instagram or send me an email.

This tutorial was originally published on my personal website.

Part II: The Frontend Using VueJS And NUXTJS

Milan Wittpohl — Sun, 26 Jan 2020 14:29:17 +0000

In-Depth Tutorial: Building a Modern, Full-Stack Web App

connect a database to store todos
work with that database by reading, creating, updating and deleting entries
create a backend that exposes a REST-API for our frontend
secure our backend properly
build a frontend that works well with data from an API

There are several ways to build this modern web-application. I chose the following frameworks, each of which is covered in one tutorial:

Prerequisite

Good knowledge of object-oriented programming and java
Good knowledge of javascript
Basic knowledge of the terminal
A mac - While all of this should also work on windows I did not spend any time to check for or provide solutions for windows

The Frontend Using VueJS And NUXTJS

In this part we will initialise and program our web frontend. As with the backend, this part is divided into four subparts:

Choosing the framework
Initialising a NUXTJS project
Programming the frontend with additional changes to our backend
Building the frontend

Choosing the framework

Similar to the backend there are hundreds of ways to accomplish what we set out to do. I worked with angularjs and a little with angular before but in general I don't have any experience with modern js-frontend-frameworks at this point. If we look at the three main frameworks angular, vuejs and react one might argue which is better but I think it is commonly agreed on that they are all good, modern frameworks. For this series I went with vuejs just because I liked the fact that is completely community driven.

However, before we start lets take a step back. In general frontend frameworks, especially Java-Script-Frameworks gained significant popularity over the last couple of years. However, most of them rely heavily on the client, as the side is build dynamically using javascript. This has two main disadvantages:

The side is not SEO friendly
The performance of the side depends on the performance of the client

The solution to this is to create most of the html, css and js on the server. These applications are known as server-side-rendered (SSR) applications. Most of the modern js-frameworks offer ways for SSR.

For vuejs there is a framework called NUXTJS for SSR.

Initalising a NUXTJS project

NUXTJS uses nodejs to run javascript on the server. It also uses nodes package manger npm for dependecy manger. Please note, that you can also use yarn but we will go with npm here. To initialise a NUXTJS project, make sure you have installed a recent nodejs version and run the following command on the terminal (in your projects root folder):

npx create-nuxt-app frontend

This initialiser will then ask us a couple of questions. As before the point of this series is to keep everything as simple as possible. We will select:

frontend as the project name
whatever description you like
your name as author
NPM as package manager
No UI Framework
No custom server framework
Axios as module for network requests (use the spacebar to select)
ESLint to help us with formatting or code (we will look into that in a bit - again select using the spacebar)
No test framework
SSR for rendering
Select jsconfig.json (using the spacebar) if you are using vs code (like I do)

Programming the frontend

Now that we have initialised or project, lets program the frontend. We will do that in four steps.

Understanding what was generated
Preparing our setup for development
Implementing the interface
Connecting our components to our backend
The login page

Understanding what was generated

Let's open the project in our favourite code editor. For me that Visual Studio Code. Lets have a look what was generated. As with the backend we will look at every folder and file in the root directory. There is actually a really good documentation about the folder and what they should be used for. That's why I will just go very briefly into it here.

Assets → Any kind of files that should be compiled and are needed in our project (e.g. stylesheets, fonts)
Components → That's where we store our vuejs components. A component is a reusable vue instance (e.g. footer, navigation, todo-item).
Layouts → Layouts are used to customise the look and feel of our pages. We will only use the default layout in this tutorial.
Middleware → Here we can define function that run before pages are rendered. We will not use middlewares in this tutorial.
node_modules → All of our dependencies (see package.json) are stored here
Pages → The pages of our application.
Plugins → Here we can and will define plugins that are run before initialising our vuejs application.
Static → Place for static files, which we will not have.
Store → If we were to use vuex store, the files would go here
.editorconfig → This files just provides some settings for our code editor, such as that trailing whitespaces should be deleted
.eslintrc.js → This is where we configure ESLint. So what is ESLint?
- ESLint basically looks at your code and checks if it conforms to predefined rules in terms of formatting and code style
- Our eslint config file contains five blocks
  - Root → This tells eslint that the config file is located in the root directory of the project. Parent files and directories are not considered. Further documentation can be found here.
  - Env → Here we define the environment of the project. In our case our project is for the browser and uses node
  - ParserOptions → Here we set the parser for eslint. As NUXTJS is using babel under the hood to build our application, we use the babel-parser here.
  - Extends → Here we define sets of rules that our project uses
  - Rules → Here we could define additional rules
.gitignore → Files and folders to be ignored by git
jsconfig.json → Settings for VS Code
nuxt.config.js → Here we configure nuxt. As this is documented pretty good with inline-comments, I won't go into it.
package.json → Here we configure our nodejs-application. We set basic attributes such as name, version. Additionally we define scripts, dependencies and devDependencies.
- Scripts can be executed via npm run and execute the command respectively
- Dependencies are the modules that we need to run our app. They are then pulled from the npm-registry and stored in node_modules. The version can be defined using special syntax, documented here.
- devDependencies behave just like dependencies, only that there are not needed to run the app, only to develop it. More on that here.
package-lock.json → This file contains every single dependency and the exact version number used. That way you can rebuild a project and reproduce errors someone else might have gotten more reliable.
README.md → The readme file.

After we run our app at least once there will also be

A .nuxt directory that contains to compiled output

Preparing our setup for development

Before we start to program our application, we will do further configuration to ensure a smooth development workflow.

ESLint auto-fix on save

When I first started programming the app I found the ESLint errors immensely annoying, as you can't use your application unless all the errors are fixed. However, there is a way to automatically fix all ESLint errors on save. All we have to do is go to our nuxt.config.js file and replace the current extend method by the following.

    extend(config, ctx) {
      if (ctx.isDev && ctx.isClient) {
        config.module.rules.push({
          enforce: 'pre',
          test: /\.(js|vue)$/,
          loader: 'eslint-loader',
          exclude: /(node_modules)/,
          options: {
            fix: true
          }
        })
      }
    }

Styling using Sass

In this tutorial I will not explain the css we use. To ensure your app looks and feels the same, I will provide you with the complete stylesheet every time we create a new layout, page or component. We could just use plain css but I prefer Sass, as it is more powerful, thanks to variables, nesting and so on. As Sass has to be compiled (converted into plain css) we have to add a dependency for development. Do so by running the following command in your terminal inside the frontend project folder:

    npm install sass-loader node-sass --save-dev

Running our application

We can run our application in development mode by executing the following command on our terminal inside the frontend folder. The frontend is then accessible from the browser at http://localhost:3000

    npm run dev

Cleaning up

Nuxt provided us with a base setup, which is nice but we will just get mostly rid of it.

Delete default.vue in layouts
delete index.vue in pages
delete logo.vue in components

Congrats, our application is now broken :)

Implementing the interface

To work with our backend we want to have a login page, as well as an interface to list, create, delete and complete todos. This tutorial does not aim to build a perfect todo app. The purpose is to have a base set up that can easily be used for other projects. That's why our focus is to work with data from our api.

We will have

one layout for the entire app
one page for the login → we will do this at the very end, when connecting our backend
one page to work with todos
three componets
- one to create todos
- one that acts as a container for existing todos and provides us with an interface to create todos
- one for every single todo

The layout - default.vue

Nuxt uses vues single file components. In every .vue file we have a template section (our html) an optional script section (our javascript) an optional style section (our css).

Create a new layout called default.vue in the layout folder and insert the following code:

    <template>
      <div>
        <nuxt />
      </div>
    </template>

    <style>
    html {
      font-family: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, 'Segoe UI',
        Roboto, 'Helvetica Neue', Arial, sans-serif;
      font-size: 16px;
      word-spacing: 1px;
      -ms-text-size-adjust: 100%;
      -webkit-text-size-adjust: 100%;
      -moz-osx-font-smoothing: grayscale;
      -webkit-font-smoothing: antialiased;
      box-sizing: border-box;
    }

    *,
    *:before,
    *:after {
      box-sizing: border-box;
      margin: 0;
    }

    .container {
      margin: 0 auto;
      min-height: 100vh;
    }

    .title {
      font-family: "Quicksand", "Source Sans Pro", -apple-system, BlinkMacSystemFont,
        "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
      display: block;
      font-weight: 300;
      font-size: 64px;
      color: #35495e;
      letter-spacing: 1px;
      margin-top: 20px;
      text-align: center;
    }

    </style>

As I said I will not talk about styling. Our template section is really straight forward as we just define a div element where our NUXTJS app is rendered into.

The todo page - todo.vue

Create a new file called todo.vue in the pages folder and insert the following code:

    <template>
      <div class="container">
        <h1 class="title">
          My To Do List
        </h1>
      </div>
    </template>

    <script>

    export default {
      data () {
        return {
          todos: {
            type: Array
          }
        }
      },
      asyncData (ctx) {
        return {
          todos: [
            {
              'id': '1',
              'title': 'A',
              'completed': false
            },
            {
              'id': '2',
              'title': 'B',
              'completed': true
            }
          ]
        }
      }
    }
    </script>

Let's go through the template and script section.

There is nothing really happening here, besides a wrapper and a headline.

The data function returns an object that we can use in our template. We will need to work with an array to store our todos. We can not make any http request here.
The asyncData function is used to fetch data, which will then replace the corresponding variable in the data block. For now we will use dummy data but instead of a static array, this is where we are going to call our api. AsyncData is called whenever a page is loaded.

If we open our application in the browser we will just see our headline.

However, if we download and open the vue extension for chrome we can see that the asyncData method injected the objects in our todo array.

Now lets create our first component to work with our todos.

Component I - ToDoList.vue

This component is responsible for managing our todos.

It will be provided with the initial todos from the backend
It will display all todos using another component
It will handle the creation of new todos

Create a new file called ToDoList.vue in components and insert the following code.

    <template>
      <div class="to-do-container">
        <div class="create-container">
          <input v-model="titleOfNewToDo" type="text">
          <button @click="create">
            Add
          </button>
        </div>
        <div class="to-do-list-container">
        </div>
      </div>
    </template>

    <script>

    export default {
      props: {
        todos: {
          type: Array,
          default () {
            return []
          }
        }
      },
      data () {
        return {
          titleOfNewToDo: ''
        }
      }
    }
    </script>

    <style lang="scss">
    .to-do-container {
      width: 400px;
      margin: auto;
      margin-top: 50px;
      display: block;

      .create-container {
        width: 100%;
        height: 50px;
        box-shadow: 0px 10px 20px rgba(0, 0, 0, 0.1);

        input {
          height: 50px;
          width: 250px;
          border: none;
          padding-left: 10px;
          font-family: "Quicksand", "Source Sans Pro", -apple-system,
            BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial,
            sans-serif;
          font-size: 18px;
          &:focus {
            outline: none;
          }
        }

        button {
          height: 45px;
          width: 145px;
          border: none;
          cursor: pointer;
          text-align: right;
          padding-right: 20px;
          font-size: 18px;
          &:focus {
            outline: none;
          }
        }
      }
    }
    .to-do-list-container {
      width: 400px;
      margin: auto;
      margin-top: 50px;
      display: block;
      box-shadow: 0px 10px 20px rgba(0, 0, 0, 0.1);
    }
    </style>

Lets see what is happening here.

Besides a few containers there are only two elements worth mentioning.

The input
- The input element is used to give new todos a title
- To store and access the typed title we link the input to a property of our data object called titleOfNewToDo
The button
- The button is used to actually create the todo
- We want vue to trigger a method (called create) when this button is clicked
The input
- The input element is used to give new todos a title
- To store and access the typed title we link the input to a property of our data object called titleOfNewToDo
The button
- The button is used to actually create the todo
- We want vue to trigger a method (called create) when this button is clicked

Components work a little different than pages. We can not fetch any data here using asyncData. If we want to provide our components with inital data, we have to pass it using properties (props). In our case we need a property for our todo of type array. If our component is not provided with an array we default to an empty array. The title of a new todo is stored in the returned object of our data function.

So far we have created our new component but we are not using it. Lets go back to our todo.vue page and add the component. To do so we need to register the component in our script section.

    <script>
    import ToDoList from '~/components/ToDoList.vue'
    export default {
      components: {
        ToDoList
      },
      data () {
    ...

We can then use the component in our html and pass the todos array as property to the component.

    <div class="container">
      <h1 class="title">
        My To Do List
      </h1>
      <to-do-list :todos="todos" />
    </div>

If we refresh our app in the browser we can see the input field to create new todos. It isn't working yet but it is there.

Also there aren't any todos. So let's create a new component.

Component II - ToDoListItem.vue

This component is responsible for handling a single todo.

It will display a single todo
It will handle the completion of this todo
It will handle the deletion of this todo

Create a new file called ToDoListItem.vue in components and insert the following code.

    <template>
      <div class="to-do-item" :class="{ completed: todo.completed }">
        <span>{{ todo.title }}</span>
        <div class="controls">
          <span @click="deleteItem">🗑</span>
          <span @click="completeItem">✓</span>
        </div>
      </div>
    </template>

    <script>

    export default {
      props: {
        todo: {
          type: Object,
          default () {
            return {}
          }
        }
      }
    }
    </script>

    <style lang="scss">
    .to-do-item {
      width: 100%;
      display: block;
      height: 50px;
      &.completed {
        opacity: 0.2;
      }
      span {
        height: 50px;
        padding-left: 20px;
        line-height: 50px;
        width: 300px;
        display: inline-block;
      }
      .controls {
        display: inline-block;
        height: 50px;
        line-height: 50px;
        span {
          line-height: 50px;
          height: 50px;
          display: inline-block;
          width: 45px;
          text-align: center;
          padding: 0;
          cursor: pointer;
        }
      }
    }
    </style>

Lets go through this.

There are three things worth point out here.

Our wrapper div will be given the class completed if the property completed of our todo is set
We can display properties of our todo by using curly brackets and our todo object (e.g. todo.title)
Analog to our create method we bind two functions to a span element in the event of a click

Analog to our todo-list-component we declare a property of type object to store our todo.

Lets go back to our ToDoList component to actually use our new component. For the script section we make the following changes.

    <script>
    import ToDoListItem from '~/components/ToDoListItem.vue'

    export default {
      components: {
        ToDoListItem
      },
      props: {
    ...

In our template section we add the component link this

    </button>
    </div>
    <div class="to-do-list-container">
      <to-do-list-item v-for="todo in todos" :key="todo.id" :todo="todo" v-on:delete="deleteItem" />
    </div>
    </div>

Our component has three attributes

We use the v-for declaration to create this component for each todo in our todos array
The :key attribute lets vue know which property of our todo uniquely defines it (this is not mandatory but considered best practise)
The :todo attribute sets the todo property in our ToDoListItem component to the corresponding todo
The v-on:delete attribute tells the component to call its deleteItem method if the child component (to-do-list-item) raises the event "delete" → We will talk more about this in a second

If we refresh our app we can actually see our todos. However, we can not create, complete or delete todos.

Creating new todos

To create new to dos we have to implement the create function in our ToDoList component. We do this in the script section.

    data() {
        return {
          titleOfNewToDo: ''
        }
      },
    methods: {
       create() {
         this.todos.push({ id: this.titleOfNewToDo, title: this.titleOfNewToDo, completed: false })
         this.titleOfNewToDo = ''
       }
    }

As with data, we create a new object for methods and define the functions in there. For now our create function we add to lines. We will change that once we connected our backend. At this point it is just a proof of concept.

Our create method adds a new object to our todos array. Id and title are the current value of our input field. Completed is false.
We then reset the input field.

We are now able to create new todos, locally at least.

Completing and deleting todos

To complete and delete todos we need to make changes in our ToDoListItem component.

    methods: {
        completeItem () {
          this.todo.completed = true
        },
        deleteItem () {
          this.$emit('delete', this.todo)
        }
    }

Completing a todo
- To complete a todo we simply set the completed-property to true
- Vue will then automatically assign the completed css class to the element since the property has changed
Deleting a todo
- We could just delete the item by removing the element, however this is not good practice as we want our data object (the array of todos) to be consistent. We therefore want to remove the todo from the array. Vue will notice that the item no longer exsists and remove it.
- Our ToDoListItem component does not have access to the array of all the todos. To remove the item, we have to communicate with the parent component. By calling the $emit method, we do exactly that. We trigger the event "delete" and pass the todo object to it.
- In our ToDoList component we add a method block in the script section.
- As you may recall we added a v-on attribute to the component stating that whenever the event "delete" is called, we want to trigger the "deleteItem" method.
- The method simply removes the item from the array

    methods: {
      deleteItem (item) {
        this.todos.splice(this.todos.indexOf(item), 1)
      }
    }

When we reload the app in the browser we now find our interface fully working.

Refactoring the to do item creation

Now that we know how to use components and how to communicate between them, it seems wise to also move the creation of todos to a seperate component.

Create a new component by the name ToDoItemCreate.vue and insert the following code:

    <template>
      <div class="create-container">
        <input v-model="titleOfNewToDo" type="text">
        <button @click="create">
          Add
        </button>
      </div>
    </template>

    <script>

    export default {
      data () {
        return {
          titleOfNewToDo: ''
        }
      },
      methods: {
        create () {
          this.$emit('create', this.titleOfNewToDo)
          this.titleOfNewToDo = ''
        }
      }
    }
    </script>

The template is the same as before in our ToDoList-component. In the script section we have the titleOfNewToDo as data attribute and similar to the deletion of todos we call the event create in our parent component.

Therefore we have the following changes in our ToDoList component.

In the template section we replace the div "create-container" with the component.

    <to-do-item-create v-on:create="createItem" />

In the script sections we refactor accordingly:

    import ToDoItemCreate from '~/components/ToDoItemCreate.vue'
    import ToDoListItem from '~/components/ToDoListItem.vue'

    export default {
      components: {
        ToDoItemCreate,
        ToDoListItem
      },
      props: {
        todos: {
          type: Array,
          default () {
            return []
          }
        }
      },
      methods: {
        createItem (item) {
          this.todos.push(item)
        },
        deleteItem (item) {
          this.todos.splice(this.todos.indexOf(item), 1)
        }
      }
    }

Now our app is even cleaner and should still work as well as beofre.

Connecting our components to our backend

So far our frontend works but it is isolated and resets on every reload. We now want to connect our frontend to our backend.

Configuring the backend

Wait, why do we need to make changes to our backend? This is because we made our backend super secure. That is why we have to talk about Cross Site Request Forgery (CSRF) for a second.

I will only cover the basics here so you know why we have to make changes to our backend. If you want to go into more detail I would recommend these links: What is CORS?, What is CSFR, Cross Site Request Forgery (CSRF), Is CORS helping in anyway against Cross-Site Forgery?.

We want to make it as hard as possible for hackers to mask as actual users. We try to ensure that by making sure that every request to the backend must contain an unique token inside the header. This token is set by vue using the cookie-to-header method. In our current set up this will not protect us as soon as or cors setup fails as the token is transmitted via a cookie. It does however add an extra layer of protection.

CSRF-Configuration in the backend

In our WebSecurityConfiguration we add an additional line to our configure method.

        @Override
        protected void configure(HttpSecurity http) throws Exception {
        ...
           http.csrf().ignoringAntMatchers("/api/login").csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse());
        }

We configure

that csrf protection should not be applied to our login endpoint, as this is where the user gets the token
that csfr prrotection should be used with a standard cookie-csrf-token-repository
that this repository should set httponly to false so that our frontend can use the cookie-to-header-method

Before we switch back to the frontend make sure that your MonogDB and your backend is running as we will now try to access it.

Implementing the API

Now we can switch back to the frontend. We will use axios for making web request to our backend. We also need the proxy module. Install it as npm dependecy using

    npm install @nuxtjs/proxy

Let's start by configuring the url of our backend in axios. Open the nuxt.config.js file and replace the axios part as followed.

    /*
      ** Axios module configuration
      ** See https://axios.nuxtjs.org/options
      */
      axios: {
        proxy: true,
        host: 'localhost',
        prefix: '/api/'
      },
      proxy: {
        '/api/': 'http://localhost:8080/'
      },

The reason why we use the proxy module here is that we want to be able to run front- and backend from different domains. Without the use of the proxy module this would not be possible, let me explain.

When we log in, we make a request from our browser directly to our backend. Our backend then tells the browser to use cookies for every request that goes to the backend. This is where the problem lies. Since we are rendering parts of our frontend from the server-side, we make requests to the backend that are not directly triggered by the browser. They are triggered by our frontend-server-side. These request will not carry any cookies because this is not the same host that was used when we logged in. In other words, the cookies can only be used for request directly from the browser.

To solve this problem we have to make every single requests from the server-side. Even request directly from the browser should go to our frontend-server and should then be redirected / proxied.

This is why our configuration results in the following behaviour:

All requests in our app have the prefix localhost/api/
All requests to /api/ are proxied to http://localhost:8080/api/

Right now this does not make a difference as it is always localhost. However, this will change once we deploy the application.

Now we can work with the data. Create a class in javascript for our todos. Create a folder in assets called data and a new file called ToDo.class.js with the following content.

    export default class ToDo {
      constructor (id, title, completed) {
        this.id = id
        this.title = title
        this.completed = completed
      }
    }

We could implement our api calls in every page and component where we need to. Yet, I prefer to bundle all our calls to the api in one file. That way it can be maintained and reused more easily. For that we create another folder in assets called service containing a new file called ToDoService.js with the following code.

    import ToDo from '~/assets/data/ToDo.class'

    export default class ToDoApi {
      constructor ($axios) {
        this.axios = $axios
      }

      findAll () {
        return this.axios({
          method: 'get',
          url: 'todo',
          withCredentials: true
        }).then((response) => {
          const todos = []
          response.data.forEach((todo) => {
            todos.push(new ToDo(todo.id, todo.title, todo.completed))
          })
          return todos
        })
      }

      create (title) {
        return this.axios({
          method: 'post',
          url: 'todo',
          data: {
            title,
            completed: false
          },
          withCredentials: true
        }).then((response) => {
          return response.data
        })
      }

      complete (todo) {
        return this.axios({
          method: 'put',
          url: 'todo/' + todo.id,
          data: {
            id: todo.id,
            title: todo.title,
            completed: true
          },
          withCredentials: true
        }).then((response) => {
          return response.data
        })
      }

      deleteItem (id) {
        return this.axios({
          method: 'delete',
          url: 'todo/' + id,
          withCredentials: true
        })
      }
    }

Okay so there is a lot going on here, don't panic. Lets go through it step by step.

First we import our newly created ToDo class
We then define a constructor that takes in the $axios object
Then we define the functions (endpoints) of our API
- findAll
  - Here we send a get request to todo
  - The option "withCredetilas" tells axios to send the tokens we acquired through the login with the request
  - We convert the array of objects to an array of todos using our class and return it
- create
  - The creation of todos is pretty similar to getting the todos
  - Instead of get we will perform a post request
  - The method body contains the title and completed (which should always be false)
- complete and delete
  - These request are similar to create
  - They differ in the request type (put and delete) and they use the id of the todo to dynamically extend the url

That wasn't that complicated, was it? Now you may ask yourself how we can access our api in our components. For that we need to expose it. We do that by creating a plugin called services.js in plugins. The new plugin contains the following code

    import ToDoService from '~/assets/service/ToDoService'

    export default (ctx, inject) => {
      const services = {
        todo: new ToDoService(ctx.$axios)
      }

      inject('services', services)
    }

We firstly import or ToDoService
In our main plugin-code we define a new object called services and add the ToDoService.
The idea is to define a service for every data type and then to simply add it here
We finally inject the services object under the name services so we can use it everywhere

We now need to register the plugin in the nuxt.config.js file in the plugin section.

    /*
      ** Plugins to load before mounting the App
      */
      plugins: [
        '~/plugins/services.js'
      ],

What about errors?

It might happen that the request to our backend fails. This can happen for a number of reasons, the most simple one is that the internet connection of the user drops. We could add a catch block to every request in our Api class. This should be done if we need to handle a specific error individually. However, it also makes sense to bundle all errors, to handle the most basic ones in one central place. We do this by using another plugin, the interceptor.js.

    export default (ctx) => {
      ctx.$axios.onError((error) => {
        const errorMsg = error.response ? error.response.data.message : 'Unknown error'
        const errorCode = error.response ? parseInt(error.response.status) : -1
        if (errorCode === 401) {
          console.log(errorCode + ' - ' + errorMsg)
          ctx.redirect('/')
        } else {
          throw new Error(error)
        }
      })
    }

We extract the status code and message of the error
If it is a 401 error we simply redirect to our login (index) page → that we still have to create
If it is any other error we just throw it. In a real application the errors should obviously be handled much better. However, as this project is about the setup, we are done.

Again, we need to register the plugin in the nuxt.config.js file.

    /*
      ** Plugins to load before mounting the App
      */
      plugins: [
        '~/plugins/services.js',
        '~/plugins/interceptor.js'
      ],

The login page

We are now at the point where we would access our backends api. However, it would not let us in, due to our security configuration. We therefore need a login page. Create a new page in pages called index.vue and insert the following code:

    <template>
      <div class="container">
        <h1 class="title">
          Login
        </h1>
        <form @submit.prevent="performLogin" action="post">
          <p>
            <input
              id="username"
              v-model="username"
              type="text"
              name="username"
              placeholder="Username"
              required
              autofocus
            >
          </p>
          <p>
            <input
              id="password"
              v-model="password"
              type="password"
              name="password"
              placeholder="Password"
              required
            >
          </p>
          <button type="submit">
            Sign in
          </button>
        </form>
      </div>
    </template>
    <script>

    export default {
      data () {
        return {
          username: '',
          password: ''
        }
      },
      methods: {
        async performLogin () {
          if (await this.$services.login.performLogin(this.username, this.password)) {
            this.$router.push('todo')
          } else {
            this.username = ''
            this.password = ''
          }
        }
      }
    }
    </script>
    <style>
    form {
      width: 200px;
      margin: auto;
      text-align: center;
    }

    input {
      width: 100%;
      border: none;
      border-bottom: 1px black solid;
      background: none;
      height: 50px;
      line-height: 50px;
      font-size: 24px;
      font-family: "Quicksand", "Source Sans Pro", -apple-system, BlinkMacSystemFont,
        "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
      font-weight: 300;
      margin-top: 20px;
      margin-bottom: 20px;
      outline: none;
    }

    button {
      width: 100%;
      height: 50px;
      border: none;
      background-color: #f0c808;
      font-family: "Quicksand", "Source Sans Pro", -apple-system, BlinkMacSystemFont,
        "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
      font-size: 18px;
      font-weight: 600;
      cursor: pointer;
      outline: none;
      margin-top: 20px;
      border-radius: 10px;
    }
    </style>

Lets start with the template section:

We create a form with to inputs
Both inputs are binded to a vue property using the v-model directive
When submitting the form we will call the performLogin method and also prevent the browser from executing any default behaviour

In the script section we added a method for the login

We call a method from a login service (which we will create in a second)
If the method returns true, we redirect to the todo page
If the method returns false, we simply reset the input fields

Next, let's create a new service in assets/service called LoginService.vue and insert the following code:

    export default class LoginService {
      constructor ($axios) {
        this.axios = $axios
      }

      performLogin (username, password) {
        const data = new FormData()
        data.append('username', username)
        data.append('password', password)
        return this.axios({
          method: 'post',
          url: 'login',
          data
        }).then(() => {
          return true
        }).catch(() => {
          return false
        })
      }
    }

This should be vrey straightforward. We perform a post request and return either true or false based on the response. As you may recall, we configured our backend to simply return 200 in case of a successful and 401 in case of an unsuccessfull login.

Lastly, we got to inject our new service, by updating our our services.js plugin.

    import ToDoService from '~/assets/service/ToDoService'
    import LoginService from '~/assets/service/LoginService'

    export default (ctx, inject) => {
      const services = {
        login: new LoginService(ctx.$axios),
        todo: new ToDoService(ctx.$axios)
      }

      inject('services', services)
    }

Go ahead, and test the login it should work fine.

Accessing the API

Okay after all the preperation it is now time to use our repository. Due to our setup this is incredibly simple.

In our todo.vue page we simply do the following to get our todos from the api.

    async asyncData (ctx) {
        return {
          todos: await ctx.app.$services.todo.findAll()
        }
      }

Our app now displays the entries from our MongoDB database using our Spring backend. Awesome!

Now lets also implement todo creation, completion and deletion.

Creation

Navigate to ToDoListCreate.vue and replace our creation method with this.

    create() {
      this.$services.todo.create(this.titleOfNewToDo).then((data) => {
        this.$emit('create', data)
        this.titleOfNewToDo = ''
      })
    }

Simple, eh?

Completion

Navigate to ToDoListItem.vue and replace our completeItem method.

    completeItem() {
      this.$services.todo.complete(this.todo).then((data) => {
        this.todo.completed = true
      })
    },

Deletion

In the same component we also change the deleteItem method.

    deleteItem() {
      this.$services.todo.deleteItem(this.todo.id).then(() => {
        this.$emit('delete', this.todo)
      })
    }

Testing the application

Open localhost:3000/todo without logging in first → you should be redirected to /login
Type in some random login credentials and hit enter → the login should fail and you should still be on /login
login with user and password → as we defined in our WebSecurityConfiguration
Add a new todo
complete the todo
delete the todo
add three more todos
Reload the page, your todos should still be there

Congratulations for completing this tutorial!!!

As this is my first tutorial series, I would really appreciate feedback. You can find me on twitter, instagram or send me an email.

This tutorial was originally published on my personal website.

Part I: The Backend Using Java With Spring

Milan Wittpohl — Sun, 26 Jan 2020 14:28:27 +0000

In-Depth Tutorial: Building a Modern, Full-Stack Web App

connect a database to store todos
work with that database by reading, creating, updating and deleting entries
create a backend that exposes a REST-API for our frontend
secure our backend properly
build a frontend that works well with data from an API

There are several ways to build this modern web-application. I chose the following frameworks, each of which is covered in one tutorial:

Prerequisite

Good knowledge of object-oriented programming and java
Good knowledge of javascript
Basic knowledge of the terminal
A mac - While all of this should also work on windows I did not spend any time to check for or provide solutions for windows

The Backend Using Java With Spring

In this part, we will initialise and develop our web backend from scratch in four subparts:

Choosing the framework
Initializing a Spring project
Programming the backend
Building the backend

Choosing the framework

There are hundreds of ways of building a web backend in various languages. There is no right or wrong, and we could use the same framework that we use for the backend for the frontend. For this series, I wanted to choose two separate frameworks that are easy to set up, modern and can be used for any project, even if this project might suddenly and rapidly grow. So we will use Java with Spring for the backend. I used Spring before and found it pretty straight forward.

Initializing a Spring project

Before we get started, let's get an understanding of what Spring actually is.

What is Spring?

Generally, Spring is a framework that enables you to decouple your program. It makes switching components or implementations easier by using dependency-injection. We will get more into that later. However, this is not the main reason why I prefer Spring for the backend. Spring offers a platform of various components ready to use that are helpful for web apps. For instance, spring security makes access-control pretty easy and robust, and spring data is useful when connecting databases.

To initialise a new spring project we can use the Spring Initializr. When we open the assistant we will have to choose:

The project
The language
The Spring boot version
Project metadata
Dependencies

Let's break them down.

The project

We have to choose between a Maven and a Gradle Project. Gradle and Maven are both tools to automate the build of your application. We tell it what dependencies we need for our project, such as Spring and it then bundles everything together (builds it). I don't know enough about either of them to give a recommendation and there is probably no right or wrong. As with Spring, we will go with Gradle, because I used it before and liked it.

The language

This is pretty self-explanatory. Let's select java.

Spring Boot

In this step, we select the Spring Boot version. We will use 2.2.4 as it is the current version. But what is spring boot and why do we need it?

Basically, we use spring to program our application and spring boot to take care of the overhead to run the application. Spring Boot looks at your application, makes checks, assumptions and provides standard configurations to make your app run. For instance, it has a server-functionalities embedded, so you don't have to worry about it. Gradle then takes all of that and builds a java application out of it, which brings us to project metadata.

Project Metadata

The first two fields describe who the software belongs to and what its name is. It is common to use the schema com.[name of organisation].[name of software]. In my case, it is com.milanwittpohl.playground-web-backend. More interesting, though are the options for packaging and java version. For the version, I would always go with the latest stable release, 13 at this time. Now let's look at packaging.

Packaging

When building a java application, we can either build a .jar or .war file. Generally speaking, a .war file is a web application archive which runs inside an application server. A .jar file is a java archive file which can also run inside an application server but can also run on a user machine. We will select .jar.

Dependencies

This allows us to define further dependencies, such as spring security or spring data. We will leave it blank for now and add the necessary dependencies later manually when we will actually need them.

Let's generate the project.

Programming the backend

Now that we have initialised or project, lets actually program the backend. We will do that in five steps.

Organising the project folder structure
Understand what was generated
Add a single endpoint to get feel for it
Add a database connection to store data
Add simple authentication to make sure that our endpoints are private

Organising the project folder structure

Throughout this entire series we will use the following folder structure:

Project folder
- backend
- frontend

Move the folder generated by the Spring intializr to the project folder and rename it to backend.

Understand what was generated

Let's open the project in our favourite Java IDE. For me that IntelliJ. If you don't have gradle already installed, make sure to do so. Also make sure you have the correct java version installed. If we run the project it will start and terminate again instantly as there is nothing to do.

Before we add anything lets just have a look at what exactly was generated and what it does.

Lets go through every folder and file in the root directory.

.gradle

This folder works as the cache for gradle. As an example, whenever gradle resolves dependencies it uses this folder to cache them.

.idea

This folder is used by IntelliJ to store project settings and is not relevant at the moment.

build

This folder is created when we run the project and contains the compiled java classes that are loaded into the JVM in order to run the project.

gradle

To actually use gradle we use the gradle-wrapper which will provide us with the gradle-build we need. You can read more about it here.

src

This where our source code goes. We will look at the generated Java file "PlaygroundWebBackendApplication.java" in a second.

.gitignore

This file list all directories and files that should be excluded from git.

build.gradle

Here we can find four sections.

Plugins

Plugins in gradle extend the capabilities of our project. As stated here plugins can

Extend gradle
Configure the project
Apply specific configurations

We have three plugins. Let's see what they do:

Spring Boot
- This plugin allows us to build Spring-Boot-Applications with gradle
- Without this plugin gradle couldn't build our project
Spring dependency management
- This plugin allows us to define dependencies in the dependency section without providing version numbers
- The plugin will then match the version of our spring boot version with the dependencies
Java
- This plugin is used to, you guessed it, build java projects with gradle

Metadata

While group and version should be self-explanatory the source compatibility defines which java version your source code is compatible with.

Repositories

Here we tell gradle where to look for those dependencies we define under dependencies.

Dependencies

Now to the juicy part. Here we tell gradle what dependencies we need and tell it to get them for us. Each dependency contains two elements. The configuration and the dependency itself. While the dependency name is pretty clear lets have a look at the configuration. A configuration tells gradle what the dependency should be used for. The configurations we use are actually provided by the java plugin. In most cases we will use implementation as the dependency is used only for the implementation of our program.

gradlew

This shell script is used to start the gradle-wrapper on macos or other unix-based systems.

gradlew.bat

This script is used to start the gradle-wrapper on windows.

HELP.md

Generated help text file by the spring Initalizr.

settings.gradle

Here we can set settings for gradle.

Before we (finally) start programming let's have a look at our one Java-Source-File: PlaygroundWebBackendApplication.java

It contains 14 lines.

    package com.milanwittpohl.playgroundwebbackend;

    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;

    @SpringBootApplication
    public class PlaygroundWebBackendApplication {

        public static void main(String[] args) {
            SpringApplication.run(PlaygroundWebBackendApplication.class, args);
        }

    }

While most of it seems pretty self-explanatory there is the one weird annotation @SpringBootApplication. Annotations likes this are used a lot in Spring and we will cover more later. Generally, in Java annotations can be used as markers that are interpreted. Spring looks through your files and applies the appropriate logic. More information on this can be found here. But lets understand what @SpringBootApplication does.

Firstly, using this annotation is the same as using these three annotations
- @EnableAutoConfiguration
- @ComponentScan
- @Configuration
@EnableAutoConfiguration → looks at your application, makes checks, assumptions and provides standard configurations to make your app run
@ComponentScan → where to look for classes with spring annotations
@Configuration → This tells Spring that this class is used for configuration

Okay, this was a lot, as stated before, we will first create a simple endpoint to get the feel for it. After that we will connect a database and the finally secure our app.

Add a single endpoint

First, we have to tell Spring that we want to develop web functionalities. To do that we just change our dependencies in our build.gradle file.

    dependencies {
        implementation 'org.springframework.boot:spring-boot-starter-web'
        testImplementation 'org.springframework.boot:spring-boot-starter-test'
    }

By adding the suffix -web we get additional libraries. After reimporting the dependencies we can start coding.

Endpoints are referred as controllers in Spring

Spring uses a MVC model, the Spring Web MVC Framework. The model is the data that our application serves up. The view could be a web page that we render using spring. The controller gets the data, by referencing the model, and provides the view with the necessary information. Since we don't use Spring to render a view, we simply don't have a view. All that we are left with is a model and a controller. Therefore our endpoint is the controller, as it provides a response to a web-request. To define a new controller we create

a new package called controller
a new java class called HelloWorldController

To define an endpoint we have to do three things.

1. Declare our new class as controller

First, we need to tell Spring that our new HelloWorldController is a controller. To do that we use a stereotype annotation. There are two annotation to define a controller. @Controller and @RestController. @Restcontroller is a specialisation of the @Controller annotation and simplifies the implementation a little for our setup, as we don't need to explicitly dd the @ResponseBody annotation to our endpoints.. It is explained in more detail here. So we just add the annotation to our class.

    @RestController
    public class HelloWorldController {}

2. Create the endpoint

To create the endpoint we simply define a method. This method could call a different class and return any kind of object. To keep it simple we just return a String.

    public String sayHelloWorld(){
        return "Hello World!";
    }

3. Define the path and request type of the endpoint

Lastly, we need to tell Spring what path and request type should be mapped to this endpoint. To keep it simple we just define it as a get request under "/sayhello". We do that, you guessed it, using an annotation.

    @GetMapping("/sayhello")
    public String sayHelloWorld(){
        return "Hello World!";
    }

Your class should look like this now

    package com.milanwittpohl.playgroundwebbackend.controller;

    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;

    @RestController
    public class HelloWorldController {

        @GetMapping("/sayhello")
        public String sayHelloWorld(){
            return "Hello World!";
        }

    }

Lets hit run! After the application started we can just open our browser and type in localhost:8080/sayhello and we get our string returned.

Working with data

Every web-backend needs to store data at one point. In order to build a Todo app, we will define a simple todo-Object and then implement endpoints to read, write, update and delete entries. Before we start coding we need to tell Spring that we want to work with data.

For the sake of simplicity we will work with MongoDB, but the setup is similar for other databases. To add the functionality we simply add another dependency called org.springframework.boot:spring-boot-starter-data-mongodb in the build.gradle file.

    implementation 'org.springframework.boot:spring-boot-starter-data-mongodb'

You also need to have a running mongoDB instance on your machine. Probably the simplest way to do that is to use a simple docker-compose file. If you dont know what docker is, don't worry. We will cover all this in part III. For now install docker and create a new file in your project root directory (not in the spring project) called docker-compose-dev.yml. Insert the following code and replace the placeholders.

    version: '3'
    services:
      playground-web-db:
        image: mongo:4.2.2
        environment:
          MONGO_INITDB_DATABASE: playground-web
        ports:
          - 27017:27017

To start the database run the following command in the terminal from your project root folder. Leave the terminal window open.

    docker-compose -f docker-compose-dev.yml up

Okay, back to spring. We should also think about the way we structure our application.

We will create a data object that describes our ToDo-Object
We will create a repository that talks to the database
We will create a service that handles additional business logic
We will create a controller to accept request to read, create, update and delete entries

Creating the data object

We start by creating a package called data. Next we create a java class called ToDo. This class characterises a single todo. To keep it simple our todo-Object has just a unique id, a title and a status. This gives us the following class.

    package com.milanwittpohl.playgroundwebbackend.data;

    public class ToDo {

        private String id;

        private String title;

        private Boolean completed;

    }

While the properties title and completed will be set by the user, the id should only be touched by the framework to ensure its integrity. Since most objects have an id spring offers a convenient annotation for that called @id . The annotation marks the field as primary key and also auto generates a value for us. For everything to work properly we also need to set up a constructor and getter methods for all of our properties.

    package com.milanwittpohl.playgroundwebbackend.data;

    import org.springframework.data.annotation.Id;

    public class ToDo {

        @Id
        private String id;

        private String title;

        private Boolean completed;

        public ToDo(String title, Boolean completed){
            this.title = title;
            this.completed = completed;
        }

        public String getId() {
            return id;
        }

        public String getTitle() {
            return title;
        }

        public Boolean getCompleted() {
            return completed;
        }

    }

Creating a repository

The repository interacts with our data base. This is where Spring really starts to shine. To interact with a mongo-database we simply create an interface that extends the MonogRepository. Let's call it ToDoRepository and put it into a new package called repository. When extending the MonogRepository we have to provide two parameters, as it uses generics. The first is the entity that we want to use, our ToDo class. The second parameter tells spring the type of the id attribute, in our case that is a string. That's it, wasn't that easy?

    package com.milanwittpohl.playgroundwebbackend.repository;

    import com.milanwittpohl.playgroundwebbackend.data.ToDo;
    import org.springframework.data.mongodb.repository.MongoRepository;

    public interface ToDoRepository extends MongoRepository<ToDo, String> {}

Creating the service

Create a new package called service. In that package we create a new java class called ToDoService. This is where our business logic is happening. Here and only here should we work with the data. Luckily, we don't have any business logic. However we need to define a few methods to read, create, update and delete entities. But it is super easy, trust me.

First, we tell Spring, that this class is a service by adding the @Service annotation to it. This adds further functionalities by spring.
Next we want to add our repository as a private property so that we can use it. This is where Springs constructor-injection comes into play. We simply add the annotation @Autowired and spring makes sure we have an instance on runtime.
Now we add methods to
- get all todos
- get a single todo by id
- save a new or existing todo
- delete a single todo by id
As we extended the MongoRepository our repository already has all the methods we need.

    package com.milanwittpohl.playgroundwebbackend.service;

    import com.milanwittpohl.playgroundwebbackend.data.ToDo;
    import com.milanwittpohl.playgroundwebbackend.exception.EntityNotFoundException;
    import com.milanwittpohl.playgroundwebbackend.repository.ToDoRepository;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.stereotype.Service;

    import java.util.List;

    @Service
    public class ToDoService {

        @Autowired
        private ToDoRepository toDoRepository;

        public List<ToDo> findAll(){
            return toDoRepository.findAll();
        }

        public ToDo findById(String id){
            return toDoRepository.findById(id).orElseThrow(EntityNotFoundException::new);
        }

        public ToDo save(ToDo toDo){
            return toDoRepository.save(toDo);
        }

        public void deleteById(String id){
            toDoRepository.deleteById(id);
        }

    }

Everything should be pretty straight-forward except maybe the findById method. If we try to look up an entity by its id it can happen, that this there isn't an entity matching the given id. That is why our repository returns an Optional of a ToDo. An optional can either contain the entity or not. To make things simple we tell our program to throw a new exception if there is no match. This exception has to be created first in a new package called Exception.

    package com.milanwittpohl.playgroundwebbackend.exception;

    public class EntityNotFoundException extends RuntimeException {}

Creating the controller

We create a new controller in our controller package and call it ToDoController. This is also pretty straight forward, so I'll just present the final code and then explain a few new and different things compared to our HelloWorldController. You might ask yourself, why we not just return the entities here and instead use the service. While this might seem reasonable right now, it becomes quiete chaotic once we have multiple data objects and controllers.

    package com.milanwittpohl.playgroundwebbackend.controller;

    import com.milanwittpohl.playgroundwebbackend.data.ToDo;
    import com.milanwittpohl.playgroundwebbackend.service.ToDoService;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.*;

    import java.util.List;

    @RestController
    @RequestMapping("/api/todo")
    public class ToDoController {

        @Autowired
        private ToDoService toDoService;

        @GetMapping
        public List<ToDo> findAll(){
            return toDoService.findAll();
        }

        @GetMapping("/{id}")
        public ToDo findById(@PathVariable String id){
            return toDoService.findById(id);
        }

        @PostMapping
        public ToDo create(@RequestBody ToDo toDo){
            return toDoService.save(toDo);
        }

        @PutMapping("/{id}")
        public ToDo update(@RequestBody ToDo toDo){
            return toDoService.save(toDo);
        }

        @DeleteMapping("/{id}")
        public void deleteById(@PathVariable String id){
            toDoService.deleteById(id);
        }

    }

First, we notice that the class has a second annotation called @RequestMapping. This way all endpoints are mapped at /api/todo.
To get a specific todo we want to pass the id via the url (e.g. localhost:8080/api/todo/5d6e53da5c88f13387cb8fa3). That's why we need to tell Spring that the url contains a variable, the id. This is done by using the curly brackets on the get mapping annotation and the @PathVariable annotation in the method header
To create or update an entity we need to transmit a json-body containing the information. We let Spring know by using @RequestBody.

    // For creation
    {
        "title":"Finish it",
        "completed":false
    }
    // For updating
    {
        "id": "5d6e54bd5c88f133b8209f34",
        "title": "Finish it",
        "completed": true
    }

Run the application and you will see that you can get, create, update and delete todos.

    // Get all
    curl -X GET http://localhost:8080/api/todo

    // Create one
    curl -X POST \
      http://localhost:8080/api/todo/ \
      -H 'Content-Type: application/json' \
      -d '{
        "title":"Finish it",
        "completed":false
    }'

    // Get one
    curl -X GET http://localhost:8080/api/todo/<ID of ToDo>

    // Update one
    curl -X PUT \
      http://localhost:8080/api/todo/<ID of ToDo> \
      -H 'Content-Type: application/json' \
      -d '{
        "id": "<ID of ToDo>",
        "title": "Finish it",
        "completed": true
    }'

    // Delete one
    curl -X DELETE http://localhost:8080/api/todo/<ID of ToDo>

Securing the Endpoints

Before we build our application and complete this tutorial we need to make sure that our endpoint is secure. We could implement a user management service, but for now we will just secure our endpoints and add one user for authentication.

We start by adding a new dependency to our gradle file called org.springframework.boot:spring-boot-starter-security. Next we need to configure spring on how to secure our application. Configuration in spring can be done using classes and annotation. Let's create a new package called configuration and a new class within that package called WebSecurityConfiguration.

To let spring know that this class is used for configuration we add the @Configuration annotation to the class
As we want to use this configuration to define the access management, our class needs to extend the WebSecurityConfigurerAdapter class

    @Configuration
    public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {}

To actually secure our endpoints we need to override the configure method of the WebSecurityConfigurerAdapter class

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
             .authorizeRequests().antMatchers("/api/**").authenticated()
             .and()
             .httpBasic()
             .and()
             .exceptionHandling()
                 .authenticationEntryPoint(restAuthenticationEntryPoint)
             .and()
             .formLogin()
                     .loginProcessingUrl("/api/login")
                 .successHandler(loginSuccessHandler)
                 .failureHandler(new SimpleUrlAuthenticationFailureHandler());
     }

Within the method we configure the HttpSecurity instance http for our application. We chain different commands together using the and-method. As there is a lot that is going on here, we will go through it line by line. Most of it is taken from this tutorial, which also provides a more in depth look.

Overall Protection

First we tell our app to secure (authorise) all request to /api/. Any http request needs to be authenticated via http-basic
An entry point used to send back a 401 Unauthorized response if a user tries to access a protected webpage
While we could send the credentials with every request, we want to have a login page where the user can login and then get a token. This way we can identify each user session more easily and we don't need to send our credentials every time
The parameter "loginProcessingUrl" tells the app the url where we send the credentials to. We will use this in our frontend.
Next we define two handlers, one if the login succeeds and one if the login fails

Login Page - Success Handler

Our success handler is a new class in our configuration package, that extends the SimpleUrlAuthenticationSuccessHandler.
Basically, we dont want our backend to return a 200 Okay response if the login was successful. The SimpleUrlAuthenticationSuccessHandler which we extend here, does that but also redirects the user to a certain URL. We don't want that, we just want to return a 200 response. To make our life easy, we simply copy the code of the SimpleUrlAuthenticationSuccessHandler and remove the logic for the redirect. Leaving us with this code:

    @Component("loginSuccessHandler")
    public class LoginSuccessHandler extends SimpleUrlAuthenticationSuccessHandler {

        private RequestCache requestCache = new HttpSessionRequestCache();

        @Override
        public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) throws ServletException, IOException {

            SavedRequest savedRequest = requestCache.getRequest(request, response);

            if (savedRequest == null) {
                clearAuthenticationAttributes(request);
                return;
            }
            String targetUrlParam = getTargetUrlParameter();
            if (isAlwaysUseDefaultTargetUrl() || (targetUrlParam != null && StringUtils.hasText(request.getParameter(targetUrlParam)))) {
                requestCache.removeRequest(request, response);
                clearAuthenticationAttributes(request);
                return;
            }

            clearAuthenticationAttributes(request);
        }

        public void setRequestCache(RequestCache requestCache) {
            this.requestCache = requestCache;
        }

    }

We will need to inject this class our WebSecurityConfigurerAdapter. That is why we need the @Component annotation to tell spring, that we want to inject this class later.

Login Page - Failure Handler

In case the login fails we simply want to return a 401 Unauthorized response
Here we dont even have to implement our own code, we simply use the SimpleUrlAuthenticationFailureHandler class.

Exception Handling - RestAuthenticationEntryPoint

In case the user tries to access a page unauthorised, we simply want to return a 401 response.
Create a new class called RestAuthenticationEntryPoint.java and insert the following code.

@Component
public final class RestAuthenticationEntryPoint
        implements AuthenticationEntryPoint {

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response, org.springframework.security.core.AuthenticationException authException) throws IOException, ServletException {
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized");
    }
}

Inject the Handler in the WebSecurityConfiguration

To use the handlers, we need to inject them into our WebSecurityConfiguration.

    @Configuration
    public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {

        @Autowired
        private LoginSuccessHandler loginSuccessHandler;

        @Override
        protected void configure(HttpSecurity http) throws Exception {
            ...

Defining Users with Credentials

If we now run the application any request to /api/todo/ will fail as we are unauthorised. However, our first endpoint /sayHello is still accessible
Now we need to configure a simple user that is allowed to access /api/todo/. To do so we add two methods in our WebSecurityConfiguration

    @Bean
    public UserDetailsService userDetailsService() {
      String password = "password";
      String username = "user";
      InMemoryUserDetailsManager manager = new InMemoryUserDetailsManager();
      String encodedPassword = passwordEncoder().encode(password);
      manager.createUser(User.withUsername(username).password(encodedPassword).roles("USER").build());
      return manager;
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
      return new BCryptPasswordEncoder();
    }

Via the first method we tell spring to store user details within the application memory and create a new user
To encode the password (because we never want to store passwords in plain text) we define a password encoder in the second method
You may have noticed that we use a new annotation on both methods called @Bean. With that annotation we tell spring to create a java bean. Without the annotation our configuration could not access those methods.
Our configuration class should now look like this

    package com.milanwittpohl.playgroundwebbackend.configuration;

    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.security.config.annotation.web.builders.HttpSecurity;
    import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
    import org.springframework.security.core.userdetails.User;
    import org.springframework.security.core.userdetails.UserDetailsService;
    import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
    import org.springframework.security.crypto.password.PasswordEncoder;
    import org.springframework.security.provisioning.InMemoryUserDetailsManager;
    import org.springframework.security.web.access.intercept.FilterSecurityInterceptor;
    import org.springframework.security.web.authentication.SimpleUrlAuthenticationFailureHandler;
    import org.springframework.security.web.csrf.CookieCsrfTokenRepository;

    @Configuration
    public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {

        @Autowired
        private RestAuthenticationEntryPoint restAuthenticationEntryPoint;

        @Autowired
        private LoginSuccessHandler loginSuccessHandler;


        @Override
        protected void configure(HttpSecurity http) throws Exception {
            http
                    .authorizeRequests().antMatchers("/api/**").authenticated()
                    .and()
                    .httpBasic()
                    .and()
                    .exceptionHandling()
                        .authenticationEntryPoint(restAuthenticationEntryPoint)
                    .and()
                    .formLogin()
                        .loginProcessingUrl("/api/login")
                        .successHandler(loginSuccessHandler)
                        .failureHandler(new SimpleUrlAuthenticationFailureHandler());
        }

       @Bean
        public UserDetailsService userDetailsService() {
            String username = "user";
            String password = "password";
            InMemoryUserDetailsManager manager = new InMemoryUserDetailsManager();
            String encodedPassword = passwordEncoder().encode(password);
            manager.createUser(User.withUsername(username).password(encodedPassword).roles("USER").build());
            return manager;
        }

        @Bean
        public PasswordEncoder passwordEncoder() {
            return new BCryptPasswordEncoder();
        }
    }

If we now run our application our todo endpoints are secure and can only be accessed using basic authentication.

Awesome, that's it. Now all we have to do is build the application.

Building the application

This is actually really easy. As you can recall we decided to use gradle for build automation. So all we need to do is open up a terminal, navigate to our project folder, and execute

    gradle build

This builds us a .jar file under ./build/libs/.

To run our application simply execute

    java -jar ./build/libs/playground-web-backend-0.0.1-SNAPSHOT.jar

Congratulations for completing this tutorial!!!

As this is my first tutorial series, I would really appreciate feedback. You can leave a comment, find me on twitter, instagram or send me an email.

This tutorial was originally published on my personal website.