creating_static_website.md

Used plugins: Routing, Static Content

Learn how to create a static website using the Static Content plugin.

In this series of tutorials, we'll show you how to create a simple blog application in Ktor:

• First, we'll show how to host static content like images and HTML pages.
• In the next tutorial, we'll make our application interactive using the FreeMarker template engine.
• Finally, we'll add persistence to our website using the Exposed framework.

{animated="true" width="502" border-effect="rounded"}

Prerequisites {id="prerequisites"}

Create a new Ktor project {id="create_ktor_project"}

To create a base project for our application using the Ktor plugin, open IntelliJ IDEA and follow the steps below:

2. In the New Project wizard, choose Ktor from the list on the left. On the right pane, specify the following settings: {width="706" border-effect="rounded"}

• Name: Specify a project name.
• Location: Specify a directory for your project.
• Build System: Make sure that Gradle Kotlin is selected as a build system.
• Website: Leave the default example.com value as a domain used to generate a package name.
• Artifact: This field shows a generated artifact name.
• Ktor version: Choose the latest Ktor version.
• Engine: Leave the default Netty engine.
• Configuration in: Choose HOCON file to specify server parameters in a dedicated configuration file.
• Add sample code: Disable this option to skip adding sample code for plugins.

Click Next.

3. On the next page, add the Routing, Static Content, and FreeMarker plugins: {width="706" border-effect="rounded"}

   Click Create and wait until IntelliJ IDEA generates a project and installs the dependencies.

Examine the project {id="project_setup"}

To look at the structure of the generated project, let's invoke the Project view: {width="481"}

• The build.gradle.kts file contains dependencies required for a Ktor server and plugins.
• The main/resources folder includes configuration files.
• The main/kotlin folder contains the generated source code.

Dependencies {id="dependencies"}

First, let's open the build.gradle.kts file and examine added dependencies:

{src="snippets/tutorial-website-static/build.gradle.kts" lines="19-26"}

Let's briefly go through these dependencies one by one:

• ktor-server-core adds Ktor's core components to our project.
• ktor-server-netty adds the Netty engine to our project, allowing us to use server functionality without having to rely on an external application container.
• ktor-server-freemarker allows us to use the FreeMarker template engine, which we'll use to create the main page of our journal.
• logback-classic provides an implementation of SLF4J, allowing us to see nicely formatted logs in a console.
• ktor-server-test-host and kotlin-test-junit allow us to test parts of our Ktor application without having to use the whole HTTP stack in the process.

Configurations: application.conf and logback.xml {id="configurations"}

The generated project also includes the application.conf and logback.xml configuration files located in the resources folder:

• application.conf is a configuration file in HOCON format. Ktor uses this file to determine the port on which it should run, and it also defines the entry point of our application.

  {src="snippets/tutorial-website-static/src/main/resources/application.conf" style="block"}

  If you'd like to learn more about how a Ktor server is configured, check out the help topic.

• logback.xml sets up the basic logging structure for our server. If you'd like to learn more about logging in Ktor, check out the topic.

Source code {id="source_code"}

The application.conf configures the entry point of our application to be com.example.ApplicationKt.module. This corresponds to the Application.module() function in Application.kt, which is an application module:

{src="snippets/tutorial-website-static/src/main/kotlin/com/example/Application.kt" lines="6-11"}

This module, in turn, calls the following extension functions:

• configureRouting is a function defined in plugins/Routing.kt, which is currently doesn't do anything:

  fun Application.configureRouting() {
      routing {
      }
  }

• configureTemplating is a function defined in plugins/Templating.kt, which installs and configures the FreeMarker plugin:

  {src="snippets/tutorial-website-static/src/main/kotlin/com/example/plugins/Templating.kt" lines="7-11"}

  We'll show how to use FreeMarker templates in the next tutorial: .

Static files and pages {id="static_files"}

Before we dive into making a dynamic application, let's start by doing something a bit easier, but probably just as important – let's get Ktor to serve some static files. In the context of our journal, there are a number of things that we probably want to serve as static files – one example being a header image (a logo that identifies our site).

1. Create the files folder inside src/main/resources.

2. Download the ktor_logo.png image file and add it to the created files folder.

3. To serve static content, we can use a specific routing function already built into Ktor named static. The function takes two parameters: the route under which the static content should be made available, and a lambda where we can define the location from where the content should be served.

   In the plugins/Routing.kt file, let's change the implementation for Application.configureRouting() to look like this:

   {src="snippets/tutorial-website-static/src/main/kotlin/com/example/plugins/Routing.kt" lines="3-13"}

   This instructs Ktor that everything under the URL /static should be served using the files directory inside resources.

Run the application {id="run_app"}

Let's see if our application is performing as expected. We can run our application by pressing the Run button next to fun main(...) in our Application.kt:

{width="706"}

IntelliJ IDEA will start the application, and after a few seconds, we should see the confirmation that the app is running:

[main] INFO  Application - Responding at http://0.0.0.0:8080

Let's open http://localhost:8080/static/ktor_logo.png in a browser. We see that Ktor serves the static file:

{width="552"}

Add HTML page {id="html_page"}

Of course, we are not limited to images – HTML files, or CSS and JavaScript would work just as well. We can take advantage of this fact to add a small 'About me' page as the first real part of our journal application – a static page that can contain some information about us, this project, or whatever else we might fancy.

To do so, let's create a new file inside src/main/resources/files/ called aboutme.html, and fill it with the following contents:

{src="snippets/tutorial-website-static/src/main/resources/files/aboutme.html"}

If we re-run the application and navigate to http://localhost:8080/static/aboutme.html, we can see our first page in all its glory. As you can see, we can even reference other static files – like ktor.png – inside this HTML.

{width="552"}

Of course, we could also organize our files in subdirectories inside files; Ktor will automatically take care of mapping these paths to the correct URLs.

However, a static page that contains a few paragraphs can hardly be called a journal yet. Let's move on and learn about how templates can help us in writing pages that contain dynamic content, and how to control them from within our application: .

You can find the resulting project for this tutorial here: tutorial-website-static.