First and foremost, let me just define what continuous integration or CI pipeline is for the purposes of this article.

It is specifically the process to build, test and package the software artifact in a container, so it can be ready to be deployed in any given environment.

Quarkus

Quarkus is an amazing Java stack for developing modern cloud-native applications. The example used throughout this blog is an app written in Quarkus. Take some time to explore the source code here.

GitHub Actions

Think of GitHub Actions as the CI tool, a replacement for Jenkins or Travis CI, for example. The aspect I like most about it is the fact it’s so well integrated with the GitHub repository. This can be empowering for developers who can control and get feedback from their CI pipelines in the same place where the code and pull requests are managed.

GitHub Packages

GitHub’s response to having a container registry comes with GitHub Packages. The container image produced by the pipeline featured in this blog is pushed to the ghcr.io registry. Similar to Actions, Packages are well integrated with GitHub’s repository, especially the way access control is granted to the pipeline.

Time for Actions

The CI pipeline is defined as code in what GitHub call workflows. These are yaml files contained inside the .github/workflows/ directory.

Next, I will highlight the best practices and patterns that can be found in the workflows of the Quarkus example application of this blog.

The Reuse of Existing Actions

- name: login ghcr.io
  uses: docker/login-action@v1.8.0
  with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}
      logout: true

Perhaps one of the best traits in Actions is the ability to import existing actions in order to execute even trivial tasks. The reason I say this is because pipeline code is not something that can be (at least easily) tested. Having the opportunity to delegate tasks to code that have been tried before increases the overall trust in the pipeline as well as reducing the errors and maintenance.

In the example above, I felt tempted to ignore using the action and instead just run a docker login shell command. However, that would still be prone to error (think of leaking the password); I also would not have handled the logout having coded the logic myself.

Maven Cache

- name: cache ~/.m2
  uses: actions/cache@v2
  with:
    path: ~/.m2
    key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
    restore-keys: ${{ runner.os }}-m2

Maven is famous for downloading half, if not the entire, internet. Jokes aside, it is wise to cache the dependencies as it normally happens in your local dev machine.

The level of abstraction provided by the action is great, it gives the developers flexibility and easiness to understand.

Cache invalidation will basically occur whenever the pom.xml changes.

Code Scanning

Another powerful feature is the code scanning action. Powered by CodeQL, it can be found in the Quarkus app as a separate workflow.

Security vulnerabilities are reported at the pull request level, in the code diff. A brilliant application of the shift-left security concept.

Permissions

All calls to GitHub APIs are authenticated using a GITHUB_TOKEN which is present by default in the workflow. The permissions assigned to this token can be configured as code inside the workflow definition.

permissions:
  packages: write
  security-events: write

Following the least privilege security principle, I set everything to read-only at the repository level and then explicitly grant the required permissions as displayed above.

Container Builds with JIB

In the obsession to find the most efficient way to build container images, I found JIB for Quarkus. Next is an extract straight from the docs:

The extension quarkus-container-image-jib is powered by Jib for performing container image builds. The major benefit of using Jib with Quarkus is that all the dependencies (everything found under target/lib) are cached in a different layer than the actual application making rebuilds really fast and small (when it comes to pushing). Another important benefit of using this extension is that it provides the ability to create a container image without having to have any dedicated client side tooling (like Docker) or running daemon processes (like the Docker daemon) when all that is needed is the ability to push to a container image registry.

To use it with Quarkus simply add the dependency:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-container-image-jib</artifactId>
</dependency>

Then add the following argument to the Maven build.

$ mvn package -Dquarkus.container-image.push=true

Image Labels

Container image labels are relevant. In the example I give, a label is used to trace back to the git commit where that image was built from. With Quarkus, JIB and GitHub Actions, this is done by adding the following argument to the Maven build:

• ‘-Dquarkus.jib.labels.”org.opencontainers.image.revision”=’$GITHUB_SHA

Pay attention to the use of single and double quotes as it makes a difference in the command line.

Also, it is worth mentioning the label name was not chosen arbitrarily, but based on standards from the Open Container Initiative.

Conclusion

You have seen a little bit of how to do continuous integration using modern frameworks. Despite the tools, what really matters is how close to the developers the process can get. With GitHub Actions and a modern language like Quarkus, people who get to write the code can now feel more than empowered to build and ship code fast. After all, that is the point of disciplines like DevOps and Continuous Delivery.

There is way more you can learn by going through the source code at:

• https://github.com/juliaaano/quarkus

Bonus: worth checking there how the pipeline handles build and testing in Quarkus NATIVE mode.

Get Started

First of all, I acknowledge we are past another decade, where popular frameworks such as Spring Boot and Quarkus have taken over the Java development landscape. The examples shown here have been intentionally created to be independent of these frameworks.

Robert C. Martin has once said software teams get excessively bound to frameworks to the point the control over the software architecture is lost. There’s no doubt this resonates with his work on the SOLID software design principles. Remember, higher-level policies of systems (business domain) should not depend on lower-level ones (frameworks).

Enough said, I rest my case and give you here my list of five essential microservices capabilities:

1. API

The most common way to reach a service from the “outside” is via an HTTP API. The majority of software backend applications nowadays implement some sort of REST API.

Spark Java is a simple, yet powerful micro-framework that provides a DSL for rapid development of HTTP endpoints. It is less invasive compared to other web frameworks, but still offers a lot of power and flexibility.

import static spark.Spark.*;

public class HelloWorld {
    public static void main(String[] args) {
        get("/hello", (req, res) -> "Hello World");
    }
}

I wrote a blog post in the past about Spark Java here.

2. Testing

Seeing that REST APIs are everywhere, we must think about how to test them.

Rest Assured is a great option. It has been out there for a while, so chances are you have heard about it. In short, it’s a Java DSL for testing of REST services.

@Test
void greet_john() {

    final String jsonBody = format("{\"name\":\"%s\",\"surname\":\"%s\"}", "John", "Smith");

    given()
        .accept(JSON)
        .contentType(JSON)
        .body(jsonBody)
    .when()
        .post("/greeting")
    .then()
        .statusCode(200)
        .contentType(JSON)
        .body("greeting", not(nullValue()))
        .body("greeting", equalTo("Hello, John Smith!"));
}

Full example can be found in my GitHub.

3. Logging

Logging, in general, certainly deserves its own topic. Here I’ll discuss specifically two related aspects of application logging: correlation ID and log filter.

3.1. Correlation ID

In a world of distributed microservices, it’s imperative to be able to trace requests that travel from one service to another.

For this reason, it is recommended that every logging statement should include a correlation identifier to the request that it belongs to.

In Java, a popular solution is to use a logging framework that supports MDC - Mapped Diagnostic Context. With MDC, you are given access to store information in the context of a thread. This allows for an elegant solution where a “Request ID” is set to MDC and later read and written by the logging framework.

The Request ID should originate from the incoming request and always propagate through by each service. A common approach is to use HTTP Headers to carry this information. The header names should be standardized, X-Request-ID being a usual example of a name.

If the incoming request does not bring the expected X-Request-ID header, the app should create one and be the originator of that request.

Here is an example of generating an X-Request-ID and assigning it to the MDC:

// APP-YEAR-DAYOFYEAR-randomUUID: APP-2020-150-194a89c21ffa
String correlationId = "APP-".concat(now().format(ISO_ORDINAL_DATE)).concat(randomUUID().toString().substring(23, 36));
MDC.put("X-Request-ID", correlationId);

And finally, an example of how to use X-Request-ID in Logback:

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
  <encoder>
    <pattern>%date [%thread] %-5level %logger{15} [%X{X-Request-ID}] - %msg%n</pattern>
  </encoder>
</appender>

Checkout working example from here.

3.2. Log Filter

Recently, I have written a full post about log filters. You can jump straight there in case you’re interested.

I recommend setting up log filters to enable the use case of adjusting the log level on a per HTTP request basis. In practice, it could let you access the DEBUG logging of a service in production, without having to restart for configuration updates.

4. Container

When it’s time to ship your application there’s nothing better than packaging in a container.

In the example I’ll show you, Docker is used to build and run the Java app, making the process portable and transparent regardless where it is executed.

### BUILDER IMAGE ###
FROM maven:3-jdk-11-slim as builder

COPY pom.xml /build/

RUN mvn --file build/pom.xml --batch-mode dependency:go-offline

COPY src /build/src/

RUN mvn --file build/pom.xml --batch-mode --offline package -DskipTests \
	&& mkdir app \
	&& mv build/target/app-*.jar app/app.jar

### PRODUCTION IMAGE ###
FROM openjdk:11-jre-slim

COPY --from=builder app/app.jar app/app.jar

WORKDIR /app

CMD ["java", "-jar", "app.jar"]

The code comes from this repo, where you also find samples to configure Kubernetes and Istio.

5. Pipeline

An application deployment pipeline should be set early on in the project. At least something to test and build the artifacts should be in place from the beginning.

Here’s a proof of concept pipeline built for Travis CI. The idea is to showcase the implementation of multiple stages where Java, Docker and Github releases are featured.

More on this topic to be seen in a previous post in this very same blog!

Wrap up

Thanks for coming all the way here.

Everything you’ve seen is available and ready to be used in the format of Maven archetypes. To install them, visit https://github.com/juliaaano/archetypes/.

TL;DR

The goal is for anyone to encrypt a message from anywhere addressed to a recipient (in this case myself):

echo "send me a secret" | docker run -i juliaaano/encrypt

Show me how

The intent is to provide a good experience by abstracting the use of GPG with Docker Linux containers.

The container image that I use is lightweight, has GPG installed and imports my public PGP key.

FROM debian:stable-slim

RUN apt-get update && apt-get install -y gnupg2 curl

RUN curl -sSL https://www.juliaaano.com/key.asc | gpg --import -

ENTRYPOINT ["gpg", "--trust-model", "always", "--encrypt", "--armor", "--output", "-", "--recipient", "juliaaano"]

About PGP/GPG

So far it has been assumed a PGP key pair exists so you have a public key for encryption and “hopefully” its private counterpart for decryption.

Creating a key pair with GPG is easy, and there are several resources available.

Once you’ve got your keys, you can build and distribute your container image so anyone can send encrypted messages to you. You still need to deal with GPG to decrypt them yourself.

Usage examples

1. Encrypt a text message or a text file:

   echo "send me a secret" | docker run -i juliaaano/encrypt
   cat my-sample-file.txt | docker run -i juliaaano/encrypt

2. Save encrypted output to a file:

   echo "send me a secret" | docker run -i juliaaano/encrypt > secret.txt.asc

3. Copy encrypted output to the clipboard (MacOS only):

   cat my-sample-file.txt | docker run -i juliaaano/encrypt | pbcopy

4. Encrypt binary (non-text) files:

   docker run -v $(pwd):/tmp juliaaano/encrypt /tmp/myfile.zip > myfile.zip.asc

5. Use Podman containers instead of Docker:

   echo "send me a secret" | podman run -i juliaaano/encrypt
   cat my-sample-file.txt | podman run -i juliaaano/encrypt

Summary

The source code for this project can be found at juliaaano/encrypt.

If you like it, comment with an encrypted message down below :-)

In a nutshell, a request like this:

curl -H "X-Log-Level: DEBUG" http://localhost:8000/hello

Would result in logs set to the DEBUG level, only for that request, in the hello service logs.

Advantages:

• Easy troubleshooting in production.
• No need to restart the service.
• Delegate control to the client.

Time for action. Getting this to work is mostly a matter of configuring properly the logger framework.

Both Java logging frameworks Logback and Log4j have a capability called Filters. They allow log events to be evaluated to determine if or how they should be published. A developer can write a custom implementation of a Filter, however many implementations are already provided. One of them is the DynamicThresholdFilter.

The DynamicThresholdFilter allows filtering by log level based on specific attributes which are present in the MDC.

The MDC (Mapped Diagnosed Context) is a key piece here because it needs to be used to signal which log level to use in the thread context initiated by the HTTP request.

Assigning a value to the MDC is simple and can be done with SLF4J:

org.slf4j.MDC.put("X-Log-Level", "DEBUG");

The idea is to set the log level in the MDC right after the request comes in, using a Servlet Request Filter, for example.

Logback configuration

The DynamicThresholdFilter in Logback is quite powerful, but a bit more difficult to distil.

A thoroughly reading of the official docs is recommended.

Following is an example that achieves the desired outcome. Notice the need to set the root logger to DEBUG. This is required as it will be the lowest log level you will be able to configure as per request. If INFO would be set there, you wouldn’t be able to go any lower than that (DEBUG being the lowest, ERROR the highest).

However, the default log level is still INFO, as it is enforced by the DefaultThreshold attribute of the Filter.

<root level="DEBUG">
  <appender-ref ref="STDOUT"/>
</root>
<turboFilter class="ch.qos.logback.classic.turbo.DynamicThresholdFilter">
  <Key>X-Log-Level</Key>
  <DefaultThreshold>${LOG_LEVEL:-INFO}</DefaultThreshold>
  <MDCValueLevelPair>
    <value>ERROR</value>
    <level>ERROR</level>
  </MDCValueLevelPair>
  <MDCValueLevelPair>
    <value>WARN</value>
    <level>WARN</level>
  </MDCValueLevelPair>
  <MDCValueLevelPair>
    <value>DEBUG</value>
    <level>DEBUG</level>
  </MDCValueLevelPair>
</turboFilter>

Log4j 2 configuration

In Log4j 2 the solution is a bit more straightforward to understand. Consider the value of X-Log-Level present in MDC.

1. If the value is either TRACE or DEBUG, log events at that level will also be accepted.
2. If the value is something else (does not match any of keyValuePair list), INFO is assumed.
3. If there is no X-Log-Level at all, onMismatch ensures the filter is neutral, behaviour doesn’t change.

Look for DynamicThresholdFilter in Log4j’s Filters documentation.

DynamicThresholdFilter:
key: X-Log-Level
onMatch: ACCEPT
onMismatch: NEUTRAL
defaultThreshold: INFO
keyValuePair:
  -
  key: TRACE
  value: TRACE
  -
  key: DEBUG
  value: DEBUG

Don’t believe what you see?

See those logging filters running. Checkout this project in GitHub. It’s a Maven archetype that will generate a project with many interesting features. The per-request log level filter is one of them.

What we want to do is to copy the pom.xml and the app sources in two separate steps.

FROM maven:3

COPY pom.xml /build/

RUN mvn --file build/pom.xml --batch-mode package

COPY src /build/src/

RUN mvn --file build/pom.xml --batch-mode --offline package \
	&& mkdir app \
	&& mv build/target/app-*.jar app/app.jar \
	&& rm -rf build

The two most important things in this example are running Maven with the pom.xml in isolation and once the sources are added, running Maven again with the –offline option set.

This is only possible thanks to Docker’s built-in cache. Before you ask, yes, if you make any changes to the pom.xml you will invalidate the subsequent cached instructions and you will download half of the internet again. It only works under the assumption that application code is changed more often than the dependency management configuration.

Multi-stage builds

The previous example alone doesn’t provide much context. After all, what do you do with that Dockerfile?

I hope you have heard about Docker multi-stage builds. It has been introduced to encourage the use of docker as a builder engine.

### BUILDER IMAGE ###
FROM maven:3 as builder

COPY pom.xml /build/

RUN mvn --file build/pom.xml --batch-mode package

COPY src /build/src/

RUN mvn --file build/pom.xml --batch-mode --offline package \
	&& mkdir app \
	&& mv build/target/app-*.jar app/app.jar \
	&& rm -rf build

### PRODUCTION IMAGE ###
FROM openjdk:8-jre-alpine

COPY --from=builder app/app.jar app/app.jar

CMD ["java", "-jar", "app.jar"]

The idea is to show how easy Docker can be used to both build and run your software. Ultimately, entire pipelines could be created with just a Dockerfile and multi-stage builds. That would be a very comfortable position for the developer who would be able to execute all these stages locally exactly the same as the CI agent.

More information at https://github.com/juliaaano/archetypes

<dependency>
  <groupId>com.juliaaano</groupId>
  <artifactId>payload</artifactId>
  <version>${check.latest}</version>
</dependency>

// Serialization
Payload<MyObject> payload = 
	JSON.payload().newInstance(new MyObject());
String json = payload.raw();

// Deserialization
Payload<MyObject> payload =
	XML.payload().newInstance(xmlAsString, MyObject.class);
MyObject obj = payload.get();

Payload acts as a facade for the various libraries out there, which means it needs to find in the classpath a third party to do the actual work. Just like SLF4J would need log4J or Logback, for example.

The design is quite flexible in the way it can accommodate custom implementations of the mechanism that does the conversion. I call it the Provider in this context. Understand more about providers in https://github.com/juliaaano/payload#providers.

Testing is something that you might want to use this library for. The ability to swap the underlying provider gives you a way to assemble your JSON test data using a different instrument rather than the one used production, but still keeping the same API.

No major performance drawbacks have been identified by using Payload instead of directly employing Jackson or Gson. The project contains a few JUnit benchmark tests to address the matter.

I have created a small app as a proof of concept for this project: Payload Tests. There you can see how things are expected to work, including the implementation of a custom provider.

Great effort has been put in the design aspect. It is fair to mention the main motivation behind this initiative was actually to exercise good practices such as object composition, OOP, build a pipeline to continuously release in Maven Central, just to name a few. If you have read this far and have also found value in what has been built, I’d be more than happy to accept your contributions. Keep the good coding.

Goals

For every commit pushed to the master branch in GitHub, the following tasks should be completed by Travis:

• Software is built and dependencies are resolved.
• Artifacts are signed.
• Docker image is built.
• Tests run.
• Image is pushed with tag ‘latest’ to Docker Hub.

These are the basics that should invariably happen. Additionally, as a consequence of the command:

git tag v1.0.0 && git push --tags

Travis should also trigger:

• Maven to set a new version based on the Git tag name.
• Docker to push an image with the same tag as the Git tag name.
• Creation of a new GitHub release with all artifacts, javadocs, sources and signature files.

Travis

Make sure Travis and GitHub integration are properly set up.

One of the great advantages of CI tools like Travis is that the build configuration is defined as code and version controlled with the rest of your project in Git. In practice, this means you should have a .travis.yml file checked in your repository.

language: java

jdk:
  - oraclejdk8

services:
  - docker

cache:
  directories:
    - "$HOME/.m2"

before_install:
  # travis encrypt-file command automatically generates the openssl command
  - openssl aes-256-cbc -K $encrypted_88b828c73747_key -iv $encrypted_88b828c73747_iv -in codesign.asc.enc -out codesign.asc -d
  - gpg --batch --fast-import codesign.asc
  - if [ -n "$TRAVIS_TAG" ]; then
      mvn versions:set -DnewVersion=$TRAVIS_TAG;
    fi

install:
  - mvn install -DskipTests=true -B -V -Psign -Dgpg.passphrase=$GPG_PASSPHRASE
  - docker build -t $TRAVIS_REPO_SLUG .

script:
  - mvn test -B

after_success:
  - docker login -u=$DOCKER_USERNAME -p=$DOCKER_PASSWORD;
  - if [ -n "$TRAVIS_TAG" ]; then
      docker tag $TRAVIS_REPO_SLUG $TRAVIS_REPO_SLUG:$TRAVIS_TAG;
      docker push $TRAVIS_REPO_SLUG:$TRAVIS_TAG;
    elif [ "$TRAVIS_BRANCH" == "master" ]; then
      docker push $TRAVIS_REPO_SLUG;
    fi

deploy:
  provider: releases
  api_key:
    secure: encrypted-key-generated-by-travis-setup-releases-cli
  file_glob: true
  file:
    - target/app-*.jar
    - target/java-starter-*.jar
    - target/java-starter-*.jar.asc
  skip_cleanup: true
  on:
    repo: juliaaano/java-starter
    branch: master
    tags: true

JAR Sign and Encryption

In the before_install step of the .travis.yml example above, there is a command to decrypt a codesign.asc.enc file to a decrypted codesign.asc one. This is done securely because my repository, in Travis, is the only one with a private key to decrypt it. Previously, I had used Travis CLI in my local machine to encrypt that file with the public key available in the corresponding Travis build repo.

The codesign.asc is nothing more than another private key I have once created with GPG. Since it is a requirement from Maven Central to have signed JARs, I found useful to include it as part of my builds. There are plenty of resources out there explaining how to work with the GnuPG tool.

A Maven plugin has the job to do the actual JAR signing. For this case, it assumes my key is set as default in the environment (gpg –fast-import). The passphrase is expected to be configured ahead in Travis as an environment variable: $GPG_PASSPHRASE.

There is a project with the pom.xml configured with GPG here.

Docker

Pay attention to the variables $DOCKER_USERNAME and $DOCKER_PASSWORD. They should be manually assigned in Travis (same as $GPG_PASSPHRASE) and in my case they refer to my own Docker Hub credentials.

Besides the build and push steps, one good idea might be executing a ‘docker run’ during the ‘script’ stage and conditionally fail or pass the build.

GitHub Release

Every successful build derived from master and with a tag is directly posted to a GitHub release. An access token (api_key) is required by Travis, but again the command line tool handles that for you.

Conclusion

Much has been said about continuous delivery. I strongly agree it is a matter of process and people before anything else. Nonetheless, I don’t find examples or how-to’s out there quite often. Probably because the resulting implementation is specific to the development process in place. I hope you can use this to get you started and evolve it towards your own deployment pipeline.

The solution presented in this blog came from my Spark Java Maven Archetypes project. Check out the source code at https://github.com/juliaaano/archetypes/tree/master/sparkjava.

When I think about Service Oriented Architectures, I remember the promise of having areas of business modeled as web services that were supposed to be shared and discoverable on the internet. A significant fact which represented this period was the vendor-mafia that came and raped the industry by pushing their heavy weight ESB products.

It turns out Platforms & API’s are not proposing something much different from what people expected from SOA before. I am afraid the same old vendors have already perceived that.

Not long ago I had the opportunity to attend a conference focused on the API/Platform space. I noticed a bunch of companies with bundle products that remembered pretty much the enterprise service buses we learned to be suspicious about. More specifically, there were solutions that addressed the issues of the enterprise in horizontal layers, where API’s were exposed in standard ways with some sort of orchestrator in the middle.

While I draw this parallel between API’s and SOA, I can’t avoid to remember how many discussions there has been around Microservices and SOA. I guess that was the wrong comparison. The new SOA is “The Platform”. Microservices are just an implementation detail.

Lastly, I do understand there are many differences between the new API movement and SOA. One example is the developer engagement. It seems to be more interesting to build apps on top of friendly JSON and hypermedia driven api’s than it used to be with the problematic XML SOAP protocol. However, in principle, I believe both approaches share the same purpose.

public static void main(String... args) {
  get("/hello", (req, res) -> "Hello World");
}

Pretty straightforward. Spark Java leverages Java 8 to provide an easy to use and understand api. Method get() registers the endpoint and starts up an embedded Jetty server to handle the incoming http requests.

Look at this other example:

public static void main(String... args) {
  final Repository repository = new Repository();
  post("/hello", "application/json", (req, res) ->
    Entity entity = repository.save(req.body());
    res.status(201);
    return entity;
  }, new JsonResponseTransformer());
}

Here we declare a POST endpoint that only gets called if the client sets Accept: “application/json” request header. Moreover, we return an entity that is serialized to JSON using an object that implements ResponseTransformer; it could possibly use Gson behind the scenes.

Spark Java has not invented anything new. The design is pretty much taken from Ruby’s Sinatra framework.

In summary

Simple, easy to maintain and understand.

No “magic”. Get rid of all the levels of indirection that a framework like Spring MVC introduces.

Better separation of concerns. Spark Java does not try to save the world.

There’s more…

Let’s go a bit fancy. Here’s a design idea you can use when there are multiple endpoints to configure.

First, create a builder interface:

public interface EndpointBuilder {
  void configure(Service spark, String basePath);
}

Now, let’s say you have one of many other rest endpoints resources to set up:

public class CustomerEndpoint implements EndpointBuilder {

  private final CustomerService customerService;

  public CustomerEndpoint(CustomerService service) {
    this.customerService = service;
  }

  @Override
  public void configure(Service spark, String basePath) {
    spark.get(basePath + "/customer", (req, res) -> {
      return "hello";
    });
  }
}

Finally, create a RestContext class that will hold the spark instance and will enable you to configure whatever routes you wish:

public class RestContext {

  private static final Logger logger = LoggerFactory.getLogger(RestContext.class);
  private final Service spark;
  private final String basePath;

  public RestContext(int port, String basePath) {
    this.basePath = basePath;
    spark = Service.ignite().port(port); // import spark.Service;
  }

  public void addEndpoint(EndpointBuilder endpoint) {
    endpoint.configure(spark, basePath);
    logger.info("REST endpoints registered for {}.", endpoint.getClass().getSimpleName());
  }

  // Then you can even have some fun:
  public void enableCors() {
    spark.before((request, response) -> {
      response.header("Access-Control-Allow-Origin", "*");
      response.header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
      response.header("Access-Control-Allow-Headers", "Content-Type, api_key, Authorization");
    });
    logger.info("CORS support enabled.");
  }
}

You should be able to use this context class in your main method (and optionally in your test classes):

public static void main(String... args) {
  RestContext context = new RestContext(8080, "/api");
  context.addEndpoint(new CustomerEndpoint(new CustomerService()));
  context.addEndpoint(new AnotherEndpoint()); // you can add or remove as many as you want.
  context.enableCors();
}

The result is this website you are seeing now. Although it may look simple (that’s always the goal!), there has been many things I’ve been through during this project. I would like to share with you the major practices and tools I learned the past weeks. This way I hope I can help you if you are also interested on building your own website.

I’ll be brief, most of the topics deserve their own blog posts, and I’m looking forward to write more about them in the future.

Jekyll

The great deal about this website is that it is completely static. I use Jekyll to generate, from templates, the whole content on every source commit. This means no dynamic content, no databases, no CMS; just plain html. I reckon this makes development much simpler because I’ve established just enough architecture to solve my problem.

GitHub Pages

Here comes the magic! GitHub Pages has a wonderful integration with Jekyll. Everytime you push code to your pages repository/branch, GitHub will build your site. You don’t need to keep stored your generated web site, because GitHub will do that for you behind the scenes. In the end you get continuous integration, deployment and hosting for free.

Disqus

After realising the benefits of having a static website, I asked myself: how am I going to provide comments for the posts? Here Disqus comes into play. Just like Google Analytics, you add a javascript to your html page and bam! It’s there.

Analytics

I guess Google Analytics is de facto standard for this kind of thing. If you know better solutions, I’m happy to hear.

Domain (DNS)

Time to setup a custom domain name. I’ve long used juliaaano as an online identity and I hope one day I can tell you the story why. DNS is provided by Amazon Route 53. All I had to do there was to create a couple of CNAME entries here and there.

Accelerated Mobile Pages (Removed)

I’m proud to say this website is powered by AMP. I stumbled upon this technology by accident and got immediately really excited about it. Besides ensuring your pages load super fast, AMP helps you to build better html. Other than that, it’s a step towards the Progressive Web Apps movement. It’s been designed to delivery content to mobile devices, but I see no reason why I wouldn’t use with desktops.

Update (2025): AMP has been removed from this site. Google no longer requires AMP for preferential search ranking, making the additional complexity unnecessary. The site now uses standard HTML with modern best practices like lazy loading images.

Content Delivery Network (CDN)

All my images, javascript and fonts are delivered by Amazon CloudFront, backed by Amazon S3. If you decide to have fun with this stuff, pay special attention to cache headers and Cross-Origin Resource Sharing (CORS) settings.

Compress HTML

Getting the html optimised to be delivered over the network is a piece of cake with Jekyll Compress Html.

Responsive

It has been challenging to learn a few CSS tricks to get this website look decent in different screen sizes. I assume you should always have this in mind.

Accessibility

I hope this blog is friendly to people who are visually impaired. I’ve favoured HTML5 tags (header, nav, section, etc.) instead of divs and I’ve tried to use WAI-ARIA best practices.

Fonts

Why not have a deterministic approach to how your text will look like? I’ve noticed that major websites use their own typeface. Although I didn’t want to license ($$$) a paid web font at this moment, I liked the idea to self host the free fonts my blog is using. The benefits are a stronger visual identity and a more predictable behavior, since you don’t rely on the browser picking up the font for you.

Font Awesome

How awesome is Font Awesome with its endless number of icons. You can setup a private account with their CDN where you are able to do some customisations as well as configure to asynchronously load the fonts in your page. Awesome!

Favicons

Nowadays favicons go beyond the scope of displaying a nice little image in your browser when a web page is bookmarked. There are specific icons for Android, iPhone and so on. Therefore, if you want to look good in all different platforms, make sure you define them properly here or here.

Atom Feeds (RSS)

I keep a RSS-like feed of all my posts. The jekyll-feed plugin does that seamlessly for me.

Meta Tags (Open Graph/Twitter)

This becomes relevant when someone shares a page from your website in a social network. You need to define which image, title and text to display when Facebook/Twitter render the post/tweet card, for example. I’m using a combination of Open Graph and Twitter Cards.

SEO

Jekyll SEO Tag to the rescue.

Sitemap

A sitemap makes easier for Google to find my pages (SEO++). The plugin Jekyll Sitemap creates a new sitemap.xml file on every build.

W3C

I often test my site against the W3C Validator. It helps me to spot malformed html and stay compliant with W3C standards.

HTMLProofer

Fantastic tool to validate generated html output: HTMLProofer.

Conclusion

It’s been a nice learning experience to go through this road. As a developer, I wanted to be a bit more professional by building my presence online with my own hands.

I would like to aknowledge and thank Yegor Bugayenko for his blog and book. They’ve both served to me as a model and foundation for this project.