DEV Community: sabyasachi

Set up dev environment with Claude Code

sabyasachi — Sat, 10 Jan 2026 21:17:24 +0000

Originally published at https://blog.sabyasachi.io/posts/prep-for-claude/

As the competition for coding agents intensifies, Claude Code seems one of the popular choices. If you are relatively new to the space and thinking about how to get started, here is my two cents after using Claude Code.

Prepare the code so that Claude understands its context

To do that generate CLAUDE.md file in the repo. It is a file that Claude automatically pulls into the context.
CLAUDE.md can contain following information -

An overview of what this repo is all about.
Important files.
Bash commands, including commands to test and build.
Formatting styles. Claude Code comes with an in-built /init command which generates an initial CLAUDE.md file after exploring the codebase. Important is to review, add and update this first version to reflect the information about the codebase.

Once we have a baseline CLAUDE.md file, it is important to keep it updated so that changes made to the codebase can be reflected. We can either automate this part by running some job after each main push or make it using human-in-the-loop, so that a reviewer can mark what needs to be added to the md file.

GitHub Access

Considering majority using GitHub, Claude can access GitHub in two ways

using gh CLI.
using GitHub MCP server.

Often the whole truth about the codebase may not be within the same repo. For example it might be using some shared libs which are in different repo. Or we just simply want to search for usage of a certain pattern. Claude Code can use either gh CLI or MCP server.

Setup MCP servers

MCP servers are what connects the model with the data it requires. I mentioned about GitHub MCP above, additionally I would recommend to use Context7 for documentation of open source libs, so that Claude can look into the documentation if required. The exact set of MCP is dependent on what you are actually building. In my context who is writing microservices using Java and AWS, my go-to MCP servers are

GitHub
Context7
AWS knowledge MCP

  Some MCP servers can bring too many tools or tool output, which can take up a significant chunk of the context window. GitHub is one of the MCP servers where tool surface area can get big.
  See the https://github.com/github/github-mcp-server/issues/1286

Additionally MCPs can bring security concerns. Fundamentally, once connected, Claude Code can call whatever tools the server exposes. Make sure to add only well-known, official servers, and use allowlists/denylists and MCP permissions where possible. Also note that project-scoped MCP servers live in .mcp.json and Claude Code prompts for approval before using them.

Sub-Agents, Commands, Skills

At this point you have a repo with necessary CLAUDE.md file and you may have added a few MCP servers. You are already on good fundamentals. Claude can produce better results, from this section onwards we move into more powerful constructs of Claude which will take the experience into next level.

Sub-Agents - Claude Code already runs a main agent loop. Sub-Agents are custom agents for specific workflow. For example, as developer once the feature development is done we can create a code-review sub agent which does a first phase of check before sending out the PR, or maybe a sub agent which fixes trivial bugs or update dependencies. Sub agents starts with a clean context so this can also be seen as extension of the main context. Sub agents can use tools coming from MCP servers. Claude Code can use a specific agent based on the agent description and context, otherwise we can mention to Claude Code to use the sub agent.
Commands - Once we start using Claude Code regularly for development, we will develop a few prompts which we repeat. For example it can be please tell me about this repo or review my code etc. As we repeat the same prompt a time saver is to create commands from them and use /code-review instead of writing a whole prompt. By doing this we also remain consistent.

   Note- Claude Code comes with a few commands for regular coding tasks like code review and exploring PR. While those work, you may still need to create your own command that fits your code context.

Skills - This is a real game changer. Skills are modular set of instructions, scripts and other resources which can extend the capability of the agent. Skills are model-invoked: Claude decides which Skills to use based on your request. Skills are auto-discoverable, and we can also give Skills to sub agents specifically. Let's take an example - maybe you always need to check for your org specific code formatting and imagine you have a feature-developer sub agent and a code-reviewer sub-agent. We can create a format skill and add the skill to both the sub agent. Now, skills are also discoverable by the main agent. For first time when I encountered skills my doubt was if main agent can discover skill should I start creating more skills or sub-agents ? The answer is still not clear to me but there are subtle nuances -
- Main agent only loads the skill name + description at startup and the full skill is loaded on demand hence saving some context.
- Skills are chosen based on context and here we are dependent on the choice of the main agent. In recent versions of Claude Code Skills have become more powerful.
Skills can run in a forked context, and can also be run in the context of an agent (including custom ones).
Skills can be user-invocable too (there is a user-invocable flag that controls whether the skill appears in the slash command menu).

Sandbox

So, you may have a few agents, augmented with skills, maybe some command which summons the agent. That's a solid setup. But hey we haven't spoken about security. The next few points I would like stress about it so that we do not end up in yet another "Claude wiped up my prod db" scenario. When we run Claude without a sandbox two things happen - it is running on your hardware directly having access to your filesystem, second, Claude being itself conscious about permissions keep on asking for permissions for any command that it wants to access/do some operations. Sandbox provides an isolated environment for Claude Code to work on. Also note there are sandbox modes (auto-allow vs regular permissions mode), so you can tune how many prompts you get.

Permissions

In many scenarios, we may not want Claude Code to access some files or, in an enterprise scenario we might want to restrict fetching from web. For these things set up Permissions. In practice this is Read/Edit/WebFetch rules, so you can restrict what Claude can read, what it can edit, and which domains it can fetch.

Env

MCP configs support environment variable expansion in .mcp.json (useful for machine-specific paths and sensitive values like API keys). Keep secrets out of the repo and wire them via env vars instead.

Once you are here, you have a pretty solid baseline with Sandbox and Permissions to start with. You can now tweak this based on experience.

Agentic coding is gaining traction, models are becoming increasingly efficient to generate code, as developers we need to adopt these tools. Consider these agents as your peer programmer or assistant rather than a replacement. The onus now will be on reviewing what the code generates, tweaking the agentic coding environment to match your coding style etc.
Hope this post will help to setup Claude Code and navigate the basic concepts.

Key Considerations for AWS Lambda on production

sabyasachi — Mon, 10 Jul 2023 18:14:32 +0000

AWS Lambda is an indispensable component of modern cloud architectures. Its serverless nature, low infrastructure requirements, and pay-as-you-go pricing have made it a cornerstone of production workloads. However, while the benefits of AWS Lambda are undeniable, it is crucial to be aware of certain considerations to ensure its successful implementation.

Monolithic or Individual Lambda

The first choice we often faced with how much code should be there in one lambda. AWS best practice is against having a monolith lambda See here but if we separate out each functionality to separate lambda wouldn't we end up in an explosion of lambdas? From a pricing perspective, it might not be a problem but what about code organization? do developers jump around in repos for relevant code? how to handle code duplications?

One approach I find out useful for me is to have a single repo for related functions but deploy them as separate lambda. In this way, we can keep the common code together and reuse it in all the functions.

Pros -

From a readability perspective, it will feel like a single application.

It will still be deployed as separate functions so we are not introducing monolithic lambda.

We can keep the common code together hence less duplicity.

Cons -

In complex CI/CD, we need to understand which part of the code has changed and act accordingly.

More fragmented infra

Continuing from above, if we break down a service into individual lambdas we need to essentially take care of automated deployment for each lambda.A decision that we need to take here is whether we have one infra code or separate infra code for each lambda. It will be beneficial to separate out the infra code for each lambda so that we are not unnecessarily building or updating all lambda.

One problem often arises here is about which lambda owns a particular infra. We can use tagging to assign ownership.

But overall we are now managing from one service to multiple functions so it is a challenge nonetheless.

Cognitive load

Because it is so easy to integrate lambdas with another service we often feel like adding Lego blocks and before we realize we end up with numbers of different components that work with each other.

As a developer what we need here is overall visibility of what event is generated by which service consumed by which lambda which in turn triggers other service it soon becomes a cognitive load.

Create an overall architecture diagram updated and handy we will often need that.I would personally love to have a tool that can visualize the whole topology.

Testing

AWS Lambda is an AWS offering and it is often integrated with another service so a question arises of how to test that. There is a whole section in the AWS doc about testing. However, one thing that I differ slightly from here is the usage of a simulator. I personally like usage simulators like localStack. This gives me much higher confidence than mocking out relevant parts. The documentation talks about testing by actually deploying on AWS, which is absolutely fine but if devs can test locally that will be much faster. Localstack alongside test-containers can speed up the process.

Tracing

Most of the time Lambdas are part of an overall architecture and not in a standalone way. This means we need tracing, logging, and metrics to work seamlessly when service-to-lambda interactions are happening.

for tracing While X-Ray is a great tool often organizations do have an existing tracing mechanism or the cost of X-Ray becomes an issue.We need to come up with a unified tracing solution. One option is to depend on a standard library like Opentelemetery to programmatically propagates tracing info.Another option is to run the same logic but using AWS lambda Extension API.In the second approach, we can make the tracing part language agnostic and run as a separate process from lambda.

Beware about quota

AWS Lambda by default has a quota of a maximum of 1000 concurrent executions in an account.Initially, this might not be an issue. But as the environment grows we will start to see throttles.Beware of any scenario that can cause unbounded execution of lambda that might eat up quota from other lambdas.If the event producer produces a large number of events considering having an upper bound of how many concurrent lambdas can be spawned at max. One example configuration for SQS mapping can be found here

In conclusion, AWS Lambda is a powerful and valuable tool for building scalable and cost-effective cloud architectures. However, its adoption requires careful consideration of various factors. With thoughtful planning and the adoption of best practices, AWS Lambda can significantly enhance scalability, reduce TCO, and drive successful deployments in production environments.

Spring Boot 3 meets Graal Native Image

sabyasachi — Sat, 29 Oct 2022 10:14:43 +0000

Spring Boot 3 is the upcoming big release for spring boot. Based on Spring Framework 6, this release is packed with many new features. One thing that has generated a lot of interest in dev community is Graal native image support. Spring Boot 3 comes with out of the box support for generating native images, which promises fast startup time. Spring already has an experimental project Spring Native to support graal native image generation, however from 3.x version it comes out of box with Spring Boot and no new module is needed.

Spring Native is going to be discontinued.

How to generate native image

Let's first generate a spring boot project from start.spring.io . Add GraalVM Native Support to the list of dependencies.

Currently it requires Graal VM 22.3 version.

There are three ways to generate native image -

Using buildpack - spring-boot-maven-plugin can make use of buildpacks to generate an image with native executable. The generated pom has the below plugin

<plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <image>
                        <buildpacks>
                            <buildpack>gcr.io/paketo-buildpacks/bellsoft-liberica:9.9.0-ea</buildpack>
                            <buildpack>gcr.io/paketo-buildpacks/java-native-image</buildpack>
                        </buildpacks>
                    </image>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>

it uses liberica buildpack which uses Graal 22.3 support.

with this if you run spring-boot:build-image an OCI compatible image will be generated which uses native executable .

To see how buildpacks work check out my post https://dev.to/sabyasachi/buildpack-with-spring-boot-300o

Using Maven - spring-boot-starter-parent comes with graal native-image-plugin in profile native. The below command generates an executable for your local machine architecture -

mvn -Pnative native:compile

We need to have graal 22.3 installed on local machine,

As of writing this post I could only found 22.3.r17.ea-nik distribution via sdk man. In case you do not see this distribution in sdk list try setting sdkman_beta_channel=true in ~/.sdkman/etc/config file.

Using aot processed jar - Most of us might be transitioning from using uber jar to native image. We might want to support both before we gain enough confidence and operational excellence. If we run mvn package an aot processed jar will be generated, which then can be used with native-image tool to generate native executable artifact. I see this option as a great entrypoint to adopt graal native image.

Graal reachability metadata support

During native image generation, native-image tool does a static analysis. There are classes which might not get accessed during this static analysis and they get left out in the final artifact. To overcome this some extra information can be provided during build time. Creating this extra metadata is cumbersome. There's an effort to consolidate these metadata information for various 3rd party libraries into a shared github repo https://github.com/oracle/graalvm-reachability-metadata .

During generation of native image spring makes use of this repo to include already known configs and hence makes the build much easier.

Testing with Native image

The official document guides us to write unit and integration test and test it with the JVM version of the application. This will lower the feedback time as compiling native image still takes a lot of time (approx 7-8 min in my 2019 Macbook Pro) .

However, there's a nice feature to run the aot compiled jar and run some integration test against it .

What I like and didn't like

Likes

Building of graal native image has improved a lot and having it out of the box will really help its adoption.
GraalVM reachability metadata is a great addition to help compatibility issues.
Faster startup .
AOT processed artifact.
I was able to use flyway with postgres seamlessly , previously when I tried with Spring native image this integration didn't work .

Things that need to keep in mind-

As I add spring boot actuator and had jmx enabled, startup of my application failed. I need to disable expose of management endpoint via JMX as JMX is not supported in Graal native image.
Configartion like @Profile and @ConditionalOnProperty is not supported. These are used very frequently .
Build time is still on a little longer side. On my personal 2019 MacBook Pro it tool approx 7-8min .
We need to expect compatibility issue with 3rd Party libs.
no JVMTI or Java Agents support.
No thread dump,heap dump .

Both Graal native image and Spring's support is still is very early days. Right now I see graal native can be fit very aptly in Serverless world where we need fast startup. Absence of JIT compilation, JVMTI, JMX those does not come into play in a lean serverless world.

If I compare Spring with Micronaut or Quarkus support for graal native I must say Spring is catching up very fast. Support for reachability metadata is a nice addition in spring.

Overall, yes it is promising but my only concern remains with compatibilty with other libs , longer build time and features that are not supported in native image .

Spring Feign Client

sabyasachi — Sun, 28 Aug 2022 06:01:00 +0000

Often a service needs to call Http endpoints , Feign comes from the OpenFeign project makes it easier to call http endpoints in a declarative fashion.
Spring has openfeign integraton through its Spring Cloud OpenFeign integration.

How To include feign clients

The actual project for feign is OpenFeign https://github.com/OpenFeign/feign . Spring comes with it's own starter . Add below dependency to the project

    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-openfeign</artifactId>
    </dependency>

For an example let's create a service named feign-serviceA which will call feign-serviceB . feign-serviceB exposes a GET endpoint /hello which returns a simple hello response body.

In order to call the endpoint using a feign client from feign-serviceA we need to do following -

Create an interface annotated with @FeignClient like below

@FeignClient(url = "<host:port for serviceB>", name = "serviceB")
public interface ServiceBClient{

    @GetMapping("/hello")
    public ResponseEntity<String> sayHello();
}

Add @EnableFeignClients annotation to main class .

and we are all set we can simply autowire ServiceBClient and call method sayHello like any normal method call .

@EnableFeignClients takes a list of clients if we have many feign clients then it is better to mention the clients as argument otherwise spring will do a classpath scan to find out feign clients.

Feign Configuration

Under the hood feign comes with some components which are used to make a call to remote endpoints and encode/decode request response .

Client - To make HTTP call feign requires http client. By default openfeign comes with a Default Client. We can override it with ApacheHttpClient, OkHttpClient or ApacheHC5FeignClient . These feign clients are wrapper around a delegate client. For example ApacheHttpClient wraps a httpcomponents httpclient and converts the response to feign response.
Decoder - Something needs to convert the feign Response to the actual type of the feign method's return type. Decoders are that instruments. By default spring provides an OptionalDecoder which delegates to ResponseEntityDecoder which further delegates to SpringDecoder. We can override it by defining a bean of Decoder .
Encoder - We call feign methods by passing objects to it something needs to convert it to http request body. Encoder does that job. Again By default spring provides SpringEncoder.

Along side above components there are also support for caching, metrics provided by spring feign starter .

We can create a configuration class and override the defaults for the above components.
If we want to override default for single components @Feign accepts configuration arguments which we can use to define custom override for default values.

Retry

Feign has baked in support for retry mechanism. However by default it uses Retry.NEVER_RETRY . For example we can create a custom retryer which will retry any status code > 400. Below is the code for our CustomRetryer .

public class CustomRetryer extends Retryer.Default{
    public CustomRetryer(long period, long maxPeriod, int maxAttempts){
        super(period, maxPeriod, maxAttempts);
    }

    @Override
    public void continueOrPropagate(RetryableException e){
        log.info("Going to retry for ", e);
        super.continueOrPropagate(e);
    }

    @Override
    public Retryer clone(){
        return new CustomRetryer(5,SECONDS.toMillis(1), 5);
    }
}

One important fact is feign Retry works either on IOException or RetryableException thrown from some errorDecoder . Below is how a custom decoder looks like -

    @Bean
    public ErrorDecoder errorDecoder(){
        return (methodKey, response) -> {
            byte[] body = {};
            try {
                if (response.body() != null) {
                    body = Util.toByteArray(response.body().asInputStream());
                }
            } catch (IOException ignored) { // NOPMD
            }
            FeignException exception = new FeignException.BadRequest(response.reason(), response.request(), body, response.headers());
            if (response.status() >= 400) {
                return new RetryableException(
                        response.status(),
                        response.reason(),
                        response.request().httpMethod(),
                        exception,
                        Date.from(Instant.now().plus(15, ChronoUnit.MILLIS)),
                        response.request());
            }
            return exception;
        };
    }

Though documentation says feign retries on IOException internally when an IOException occurs it wraps it in a RetryableException.

Support for resiliency

One form of resiliency through retries we saw in last section. Spring has CircuitBreaker support for feign . It achieves it through a separate Feign builder FeignCircuitBreaker.Builder . The actual implementation of circuitbreaker comes from resilience4j library.

Interceptor

Sometimes we want to modify the request by adding some extra information. For example we may add some header for each request. We can achieve this by using RequestInterceptor. For experiment I added below interceptor which populates a header userid.

    @Bean
    public RequestInterceptor userIdRequestInterceptor(){
        return (template) -> {
            template.header("userid", "somerandomtext");
        };
    }

feign-serviceB reads this header and returns back as header. If we do a curl we get below response

< HTTP/1.1 200
< connection: keep-alive
< date: Sat, 20 Aug 2022 15:27:47 GMT
< keep-alive: timeout=60
< userid: somerandomtext
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 7
<
* transfer closed with 7 bytes remaining to read

We see userid is added to the response.
A very useful application for interceptor is when feign has to send oauth2 access token . Out of the spring provides a OAuth2FeignRequestInterceptor which adds access token for each request.

Client side loadbalancing support

From spring boot 2.4.0 feign has integration with spring-cloud-loadbalancer which can fetch client url info from various service discovery providers and make that info available to feign .

Usage of feign simplifies various aspect of making http request. In a typical production environment we may need to override several components like clients, decoder, errorDecoder etc . Also within Spring ecosystem feign is nicely integrated with resiliency, loadbalancing , metrics etc which makes it automatic choice when we are working in a microservices architecture .

Generate application metrics using SpringBoot and Micrometer

sabyasachi — Sun, 22 May 2022 11:20:28 +0000

Introduction

Observability is one of the pillars of modern microservices architecture. Application metrics is one dimension of that observbility. When an application runs on production we may want to know various operational metrics like memory,cpu ,threadpool usage etc as well as buisness metrics for example how many request for a particular operations are made.
Spring boot with the help of micrometer enables application developers to expose various metrices.

Setup metrics

To add support for metrics , we need to add actuator dependency



<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

and we also need to enable the metrics endpoint like following -



management:
  endpoints:
    web:
      exposure:
        include: metrics

That's it our application now set to expose metrics.

The below curl



curl localhost:8080/actuator/metrics | jq .

will give response like -



{
  "names": [
    "application.ready.time",
    "application.started.time",
    "disk.free",
    "disk.total",
    "executor.active",
    "executor.completed",
    "executor.pool.core",
    "executor.pool.max",
    "executor.pool.size",
    "executor.queue.remaining",
    "executor.queued",
    "hikaricp.connections",
    "hikaricp.connections.acquire",
    "hikaricp.connections.active",
    "hikaricp.connections.creation",
    "hikaricp.connections.idle",
    "hikaricp.connections.max",
    "hikaricp.connections.min",
    "hikaricp.connections.pending",
    "hikaricp.connections.timeout",
    "hikaricp.connections.usage",
    "http.server.requests",
    "jdbc.connections.active",
    "jdbc.connections.idle",
    "jdbc.connections.max",
    "jdbc.connections.min",
    "jvm.buffer.count",
    "jvm.buffer.memory.used",
    "jvm.buffer.total.capacity",
    "jvm.classes.loaded",
    "jvm.classes.unloaded",
    "jvm.gc.live.data.size",
    "jvm.gc.max.data.size",
    "jvm.gc.memory.allocated",
    "jvm.gc.memory.promoted",
    "jvm.gc.overhead",
    "jvm.gc.pause",
    "jvm.memory.committed",
    "jvm.memory.max",
    "jvm.memory.usage.after.gc",
    "jvm.memory.used",
    "jvm.threads.daemon",
    "jvm.threads.live",
    "jvm.threads.peak",
    "jvm.threads.states",
    "logback.events",
    "process.cpu.usage",
    "process.files.max",
    "process.files.open",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "system.load.average.1m",
    "tomcat.sessions.active.current",
    "tomcat.sessions.active.max",
    "tomcat.sessions.alive.max",
    "tomcat.sessions.created",
    "tomcat.sessions.expired",
    "tomcat.sessions.rejected"
  ]
}

These are the metrics that spring boot provides out of the box. We can see it includes jvm memory, threads, cpu usage etc.

The below request will show used jvm memory



 curl 'http://localhost:8080/actuator/metrics/jvm.memory.max'| jq .


 {
  "name": "jvm.memory.max",
  "description": "The maximum amount of memory in bytes that can be used for memory management",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 5620367357
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": [
        "heap",
        "nonheap"
      ]
    },
    {
      "tag": "id",
      "values": [
        "CodeHeap 'profiled nmethods'",
        "G1 Old Gen",
        "CodeHeap 'non-profiled nmethods'",
        "G1 Survivor Space",
        "Compressed Class Space",
        "Metaspace",
        "G1 Eden Space",
        "CodeHeap 'non-nmethods'"
      ]
    }
  ]
}

A metrics can have multiple dimensions. For example jvm.memory.max has heap and nonheap size. We can drill down to metrics using its tags like .



curl 'http://localhost:8080/actuator/metrics/jvm.memory.max?tag=area:heap' | jq .

{
  "name": "jvm.memory.max",
  "description": "The maximum amount of memory in bytes that can be used for memory management",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 4294967294
    }
  ],
  "availableTags": [
    {
      "tag": "id",
      "values": [
        "G1 Old Gen",
        "G1 Survivor Space",
        "G1 Eden Space"
      ]
    }
  ]
}

So far we know that spring boot exposes metrics and we can request metric endpoint to get those metrics and if required we can drill down to this metrics using available tags.

Custom Metrics

What if we need more metrics?

Spring uses Micrometer(https://micrometer.io/) underneath which takes care of generating and exposing metrics.
MeterRegistry is the core concept of micrometer that holds multiple metrices.

We can simply inject an instance of MeterRegistry in our custom metrics provider like below -



@Component
public class InventoryMetrics{
    private Counter inventoryCounter;

    public InventoryMetrics(MeterRegistry meterRegistry){
        inventoryCounter = Counter.builder("products")
                .description("Product Count")
                .register(meterRegistry);
    }

    public void inventoryAdded(int count){
        inventoryCounter.increment(count);
    }
}

Here we have created a new metrics named products , every time we add a new product we will increment the value.

Now if we curl our metrics endpoint with we get product count



curl 'http://localhost:8080/actuator/metrics/products' | jq .

{
  "name": "products",
  "description": "Product Count",
  "baseUnit": null,
  "measurements": [
    {
      "statistic": "COUNT",
      "value": 2
    }
  ],
  "availableTags": []
}

Streaming metrics

On production we would like to stream metrices to a data store like elasticsearch, influxdb etc. Spring Boot supports out of the box various data sinks https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.metrics .

For this post I ran a influxdb docker image locally . We can see our custom metrics pushed to influx -

On the application side configuration looks like -



management:
  metrics:
    export:
      influx:
        uri: 'http://localhost:8086'
        token: '<your-token>'
        bucket: '<your bucket>'
        org: '<your org>'
        autoCreateDb: false

NOTE: Config properties for influxdb 1.x and 2.x different.
The above config is for influxdb 2.x. For 1.x we need to use username , password and db instead of token,bucket and org. Also autoCreateDb should be false as otherwise springboot will try to create a db named mydb .

Micrometer metric Types

Counter Counters are monotonically increasing metrics. It can be incremented by a fixed amount which is always positive.

Gauge Gauges are instantaneous metrics this can either go up or down.

Timer Timers are short duration latencies and frequency of events.

Our custom metric is a type of counter to measure the added products .

This is at a very high level how to expose metrics.

In production though we need to be aware of the volume of metrics, because if volumes and frequency is high our dashboards can become really slow.

We should also think about a retention policy of data to not to store unecessary old data. This will help saving some storage.

In conclusion metrics are essential part of our services and spring boot make it easy to gather and expose it to various data sinks.

Using AWS CDK to bring infra code closer to application developers

sabyasachi — Sun, 15 May 2022 09:56:56 +0000

AWS Summit Berlin 2022 took place on May11-12 there I attended a great talk by Gregor Hohpe and Luis Morales from AWS titled Infrastructure as actual code. In it they presented AWS CDK. I thought of giving it a try and this post is about my initial impression about AWS CDK.

Before we go to what AWS CDK does , let's look at why infrastructure as code is important. In current cloud native application architecture ability to deploy infra in an automated, repeatable and consistent way is a must have. Many tools provides a way to achieve that for example CloudFormation by AWS, terraform for Hashicorp to name a few.

However primarily these tools have it's own DSL to achieve that. Cloudformation uses YAML/Json files, while terraform uses HCL (HashiCorp Configuration Language).

What if developers can use their favourite programming language that they are using to write their application and in which they have expertise ? Well this is where AWS CDK shines.

AWS CDK enables us to use known programming language like Typescript, JavaScript, Java, Python, Java, C#/.Net and Go.

Below is how a simple Lambda function with Api Gateway integration may look like -

public class MovieLambdaInfraStack extends Stack{
    public MovieLambdaInfraStack(final Construct scope, final String id){
        this(scope, id, null);
    }

    public MovieLambdaInfraStack(final Construct scope, final String id, final StackProps props){
        super(scope, id, props);
        // Parameters
        CfnParameter version = CfnParameter.Builder
                .create(this, "lambda-version")
                .description("Version of lambda app jar")
                .type("String")
                .build();
        // Bucket storing lambda code
        IBucket lambdaCodeBucket = createBucket();

        // Lambda Definition
        String lambdaSource = "movie-lambda-app-" + version.getValueAsString() + ".jar";
        IFunction lambda = Function.Builder.create(this, "sab-lambda-artifact")
                .code(Code.fromBucket(lambdaCodeBucket, lambdaSource))
                .runtime(Runtime.JAVA_11)
                .functionName("sab-lambda-artifact")
                .handler("com.sab.LambdaHandler")
                .tracing(Tracing.ACTIVE)
                .timeout(Duration.minutes(5))
                .memorySize(512)
                .build();

        // Api Gateway

        LambdaIntegration lambdaIntegration = LambdaIntegration.Builder
                .create(lambda)
                .proxy(true)
                .build();

        RestApi api = RestApi.Builder.create(this, "movies")
                .defaultIntegration(lambdaIntegration)
                .apiKeySourceType(ApiKeySourceType.HEADER)
                .build();

        Resource movies = api.getRoot().addResource("movies");
        movies.addMethod("POST");

    }

    @NotNull
    private IBucket createBucket(){
        return Bucket.fromBucketName(this, "lambda-code-bucket", "sab-lambda-artifact");
    }
}

and a simple main method that will be run by AWS CDK to deploy this stack

 public static void main(final String[] args) {
        App app = new App();

        new MovieLambdaInfraStack(app, "MovieLambdaInfraStack", StackProps.builder()
                .env(Environment.builder()
                        .account("xxxxxx")
                        .region("xxxx")
                        .build())
                .build());

        app.synth();
    }

AWS CDK comes with cmd line cli which will deploy this app on AWS. Underneath it generates a cloudformation template.

AWS CDK Basic Components

App - An App is an component which will be deployed by cdk and will contain one or more than Stacks.

Stack - A Stack is what defines our infra. This will contain one or more Constructs

Constructs - These are real AWS services . We can also create our custom constructs.

See more components at https://docs.aws.amazon.com/cdk/v2/guide/core_concepts.html.

Things that I like

I have used cloudformation, which personally I do not prefer mostly because for complex infra it can become real tangled up and hard to read.

In recent times I have used mostly terraform, and I liked it. It supports multiple cloud. We can create our own modules and components in terraform. HCL language is pretty expressive. It has it's own way to define functions, types, loop of variables which sometimes become a little unintuitive for us developers.

my first impression With AWS CDK is that I see below advantages -

As developer I feel much at ease to be able to use my favourite and known programming constructs to infra.
We can even write Unit tests using good old Junit . Below is an example

 @Test
    void itShouldGenerateLambda(){
        App app = new App();
        Stack lambda = new MovieLambdaInfraStack(app, "MovieLambdaInfraStack");
        Template template = Template.fromStack(lambda);
        template.resourceCountIs("AWS::Lambda::Function",1);
        template.hasResourceProperties("AWS::Lambda::Function", Map.of(
                "Handler", "com.sab.LambdaHandler"
        ));
    }

We can make full use of abstraction in case of using object oriented programming languages.
This ability of creating abstraction will help us to impart same domain driven design thinking that we can apply on application code level.
More over I see if we use good abstraction level while writing our infra code it will serve as a blue print how different components are interacting to each other. In other word, we can discover the infrastructural architecture of an application . We will have both software level architecture and infra level architecture side by side in a single place . I believe this will give us great insight.
Developers get a broader picture how infra components are working together to achieve what their application code try to express.

On the down side

However on the down side -

Strong tie up with cloudformation means this is AWS cloud specific. Though there are libraries like cdk-tf (https://github.com/hashicorp/terraform-cdk) for terraform and cdk8s for Kubernetes is available.
Relatively new so I am yet to judge it's efficiency in large production infrastructure.

But overall I liked the CDK approach and I hope it's adoption will bring infra code closer to application code and break the silos in terms of tools and languages between infra and application code.

Using Spring Data JPA for data access layer

sabyasachi — Mon, 09 May 2022 19:25:27 +0000

Introduction

We started with a simple hello world application and we covered up to how to set up our database schema flyway. We are now ready to write some code which will interact with database.

Before we jump on to code let's look at a bit of history.
Java has a nice JDBC api which helps us query database. Making it a base many ORM tools come into existence, Hibernate, Mybatis, Toplink to name a few. ORMs bridged the gap between JDBC and objet orientedness with how we perform database operations and mapped them to some objects. Though we have many different opinions about penalty of using ORMs but in practical we see a huge adotion of this tools and specially Hibernate.

JPA is a specification and is an attempt to uniform the APIs used by many ORMs .

If we look at Java based applications today JPA+Hibernate has become the defacto choice for relational databases.

Spring brings more utility that makes life a lot easier for developer.

Now this post is not a Hibernate or JPA tutorial rather it is a simple Spring tutorial on how to use Spring's support for JPA and Hibernate.

The dependencies

Like always we have a starter named spring-boot-starter-jpa . Below is the dependency

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

What does it bring to the application ?

We see it brings hibernate core dependencies and JPA dependencies.

A small note here JPA which was previously used to be known as Java Persistence API has now renamed to Jakarta Persistence API due to naming rights issues.

What Spring data jpa provides is

A Repository interface to auto generate most boiler plate query pattern.
Support for annotation driven transaction mechanism .
Easy auditing for entities .
Support for paginations, filter and so on.

So now that we have our dependencies in place, let's start with code.

Our entity class is simple and looks like below

@Getter
@Setter
@Entity
@Table(schema = "inv", name = "products")
public class Product{
    @Id
    @GeneratedValue
    private UUID id;
    private String name;
    private Long stock;
    private String manufacturer;
    @CreatedDate
    private OffsetDateTime createdOn;
}

(imports are ommitted for brevity)

It's a simple JPA entity with id field as identifier. Now comes the best part, we ofcourse need some code to store and retrieve products from database. Good news is Spring has got us covered. All you need to do is define a repository as below -

Repository

@Repository
public interface ProductRepository extends JpaRepository<Product, UUID>{

}

That's it spring will generate all boiler plate basic query like persists, findAll to name a few .

JpaRepository also supports generating query to find by some column of the entity for example id, name, stock, manufacturer,created on. All we need is a method named findBy<propertyName>. For a list of supported methods read https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.query-methods.query-creation

Let's try to fetch a product by id .

Below is ProductService which takes the Product DTO as input and stores into database.

@Service
@RequiredArgsConstructor
public class ProductService{
    private final ProductRepository productRepository;

    public Product save(Product productDTO){
        ProductEntity productEnity = new ProductEntity();
        productEnity.setName(productDTO.getName());
        productEnity.setManufacturer(productDTO.getManufacturer());
        productEnity.setStock(productDTO.getStock());
        productEnity.setCreatedOn(OffsetDateTime.now());

        ProductEntity savedEntity = productRepository.save(productEnity);

        return toProductDTO(savedEntity);
    }

    private Product toProductDTO(ProductEntity productEntity){
        return Product.builder()
                .id(productEntity.getId())
                .createdOn(productEntity.getCreatedOn())
                .manufacturer(productEntity.getManufacturer())
                .name(productEntity.getName())
                .stock(productEntity.getStock())
                .build();
    }
}

All we need to do after creating our entity is to call productRepository.save(productEnity) .

I have not used any transactions, because JpaRepository itself works in a transaction. Also in this simple example I am not lazily loading any properties from the entity so it is fine to ommit the transaction .

Logging

We may want to check what SQL hibernate is generating for that we can use below properties

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true

In output we will see below logs

Hibernate: 
    insert 
    into
        inv.products
        (created_on, manufacturer, name, stock, id) 
    values
        (?, ?, ?, ?, ?)

What if we want to see the actual inputs passed in the insert statement. Well there is no direct property but we can enable logs like below

logging:
  level:
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE

Our application will churn out logs -

2022-05-08 12:09:36.682 TRACE 40492 --- [nio-8080-exec-1] o.h.type.descriptor.sql.BasicBinder      : binding parameter [1] as [TIMESTAMP] - [2022-05-08T12:09:36.651572+02:00]
2022-05-08 12:09:36.683 TRACE 40492 --- [nio-8080-exec-1] o.h.type.descriptor.sql.BasicBinder      : binding parameter [2] as [VARCHAR] - [test-mfg1]
2022-05-08 12:09:36.683 TRACE 40492 --- [nio-8080-exec-1] o.h.type.descriptor.sql.BasicBinder      : binding parameter [3] as [VARCHAR] - [test-product5]
2022-05-08 12:09:36.683 TRACE 40492 --- [nio-8080-exec-1] o.h.type.descriptor.sql.BasicBinder      : binding parameter [4] as [BIGINT] - [100]
2022-05-08 12:09:36.683 TRACE 40492 --- [nio-8080-exec-1] o.h.type.descriptor.sql.BasicBinder      : binding parameter [5] as [OTHER] - [dd7d89fa-c201-4338-871f-a00fed464bd5]

Let's try to get all products -

We again going to take help from Spring JPA repositories and our code will look something like -

    public List<Product> getAllProducts(){
       return productRepository.findAll()
                .stream()
                .map(this::toProductDTO)
                .collect(Collectors.toList());
    }

Pagination

Well the above works but there's a basic issue, there may be a huge number of products, in that case we need pagination support. Spring repositories are here to rescue us again.
We need to modify our ProductRepository class a little -

@Repository
public interface ProductRepository extends PagingAndSortingRepository<ProductEntity, UUID>{

}

Our method signatures change this time and most of the method takes an Pageable type .
The modified method looks like

    public Page<Product> getAllProducts(Pageable pageRequest){
       return productRepository.findAll(pageRequest)
                .map(this::toProductDTO);
    }

Notice how the return type changes from List<Product> to Page<Product> . A Page type contains information like total page count and total items.

We can also verify in our application log that select queries are not using limit and offset instead of doing a select all .

Hibernate: 
    select
        productent0_.id as id1_0_,
        productent0_.created_on as created_2_0_,
        productent0_.manufacturer as manufact3_0_,
        productent0_.name as name4_0_,
        productent0_.stock as stock5_0_ 
    from
        inv.products productent0_ limit ? offset ?

Note

Response from our controller also needs to be changed to accomodate the new pagination
information.

Auditing

If we look into our save method in ProductService, we are setting the value of createdOn field to be current date time. Although in this demo context there is nothing wrong in doing that , there is a better way to populate this fields.

Spring data jpa provides auditing fetaure via AuditingEntityListener. This provide a bunch of annotations that populate a field before or after an event.

Let's try to populate our createdOn field.

We first need to add @EntityListeners(AuditingEntityListener.class) to our ProductEntity class.
We need to provide a bean of type DateTimeProvider which will be responsible for providing a current time. Because we are using OffsetDatetime we create a bean like below which gives an OffsetDatetime.

    @Bean
    public DateTimeProvider dateTimeProvider(){
        return ()-> Optional.of(OffsetDateTime.now());
    }

Finally, we add the following annotation @EnableJpaAuditing(dateTimeProviderRef = "dateTimeProvider") .

Just like timestamp we can also add an auditorAwareRef which returns an AuditorAware<T> . Let's add a new column to our ProductEntity

    @CreatedBy
    private String createdBy;

and we add a bean like below

    @Bean
    public AuditorAware<String> auditorAwareRef(){
        return () -> Optional.of("test-user");
    }

if we now create a new product we will see test-user has been set as createdBy in database.

Note

Adding a constant test-user is only for example purpose. Getting the real user name may involve getting it from ThreadLocal, SecurityContext, Auth Header or from anything else suitable for your context.

We also have other annotation LastModifiedBy and LastModifiedOn to capture modification auditing.

Some More features

@Query - Sometime even the provided repository methods will not be enough for our usecase. May be we need a more complex query, in that case we can add a method and use @Query annotation to specify our sql query. If we set native=true we can provide a native SQL query not a JPQL one.
Specification - Our repository can also inherit from JpaSpecificationExecutor which provides method that takes an Specification type . We can make use of JPA Criteria query to build more nuanced and complex queries.

Spring data jpa is a big module and not everything can be covered in a single post. However we now can create an entity and know how to persist it and query it. In future posts we will see more features from spring-data-jpa.

That's it from this post .

Migrate Database with Flyway

sabyasachi — Sun, 01 May 2022 10:47:00 +0000

Introduction

Most of the services that we generally encounter in our daily job will simply take some input from users and populate database , and read from database
and show it on UI. Each database has a schema, now it is rarely happens that we know each nitty gritty of our domain and come up with a perfect schema at day one. Most of the time we go thorugh an iterative process of modifying our schema as and when requirments change. Now all these migrations can reside separately to the application and can be handled by database teams but what if we can keep this migration script along side of our application in a versioned way and apply them on application startup? That's what flyway does for us.

Flyway (https://flywaydb.org/documentation/) is an open source database migration tool that is used to migrate your database schema. It can be used standalone but it has nice integration with spring boot. Liquibase in another option for database migration most of the time we will see one of these two being used in production services.

Flyway supports a vast list of databases check in documentation for more details.

Flyway Convention

Flyway favours simplicity and convention over configuration.

Each flyway migration script file has the format of V<version>__<description>.sql
If we want to undo a migration, we can put that script in a file names U<version>__<description>.sql
Flyway also stores the checksum of file. So once a file has been applied the content cannot be changed.
It tracks the migration history in a table named flyway_schema_history .

Flyway with Spring Boot

To show case flyway with spring boot I am going to use our last inventory-service. So our intention is to start creating a schema and that should be applied by flyway.

To integrate flyway with spring boot we start with adding below dependency to our service.



<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
</dependency>

We start by adding spring-boot-starter-data-jpa this gives us jpa and hibernate capabilities to our application.

As we are using here postgresql we need to add postgresql driver dependency.

And last but not the least we need to add flyway-core dependency.

Flyway uses spring datasource configuration to find out database uri and credentials. Let's add the details of our database to our application.

For this blog I have created a db named inventory and a R/W user named inventory_rw . So our application config looks like as following.



spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/inventory
    username: inventory_rw
    password: '*****'

So till now flyway knows which database to connect with which credentials. Now we need to provide the migration script.
We name our first migration script as V1__init.sql and it looks like as following-



CREATE SCHEMA IF NOT EXISTS inv;

SET search_path TO inv,public;

CREATE TABLE IF NOT EXISTS products(
 id UUID PRIMARY KEY,
 product_name  VARCHAR(255) NOT NULL,
 stock NUMERIC NOT NULL default 0,
 manufacturer VARCHAR(255) NOT NULL
);

Now if we run the application, the application starts up. We see some logs like below -



 Successfully applied 1 migration to schema "public", now at version v1 (execution time 00:00.046s)

if we connect to our database we see the following -

So there is our table . We also see the owner is our user .

if we check in public schema we can say the flyway_schema_history table is also created.

And here is how it looks like -

Now let's try to change our migration script. We get below exception



Caused by: org.flywaydb.core.api.exception.FlywayValidateException: Validate failed: Migrations have failed validation
Migration checksum mismatch for migration version 1
-> Applied to database : 2071614183
-> Resolved locally    : 387884339. Either revert the changes to the migration, or run repair to update the schema history.

So once your schema is applied by default we cannot change the script. However if we want we can disable this check by spring.flyway.validate-on-migrate=false.

Let's add a column to our table. To do this we need to add a new migration script with version number greater than previous version.

Let's create a new file name V2_created_on_column.sql and add the following script.



ALTER TABLE products ADD COLUMN created_on TIMESTAMP NOT NULL ;

On logs we see below lines -



 Current version of schema "public": 1
 Migrating schema "public" to version "2 - created on"
 Successfully applied 1 migration to schema "public", now at version v2 (execution time 00:00.051s)

if we check our table we can see the new column is added.

Introducing flyway in already existing database

If we already have a database that is not created using flyway and the public schema (or the schema in which we want our flyway-schema-history-table to be created) already has other tables we will see below exception.



Found non-empty schema(s) "public" but no schema history table. Use baseline() or set baselineOnMigrate to true to initialize the schema history table.

Flyway basically refuses to migrate on a non empty database for which it does not have a schema history table.
To overcome this issue, we need to provide a baseline to flyway. A baseline is a way to tell flway that don't care what happended till this version and apply any changes above this version.
With spring config we achieve this by adding below property to our application.



spring:
  flyway:
    baseline-on-migrate: true
    baseline-version: '0'

Now here's a small catch if you don't provide which version to baseline the default value provided is 1.
So here I am providing a custom value 0 so that my scripts like V1 onwards are applied.

The schema history table will look somehting like below -

We now have a new entry called <<Flyway Baseline>> in our schema history table.

Flyway custom user

Till now in our configuration, flyway is using the user provided in spring datasource.
However it may be possible that your application uses a read-only user .
In this scenario to provide a different user to flyway we need to specify user for flyway.

The below config uses a separate R/W user to do the migration -



spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/inventory
    username: inventory_ro
    password: '******'
  flyway:
    baseline-on-migrate: true
    baseline-version: '0'
    user: inventory_rw
    password: '******'

Flyway integration of spring boot has a lot of properties to configure, for example we can define custom schema where flyway_schema_history table will be created, cherry pick migration script, default schema name etc. A list of these properties can be found https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html.

So that's it from this post. We now know how to iterate over our database and apply migrations using flyway. In next post wit this knowledge I will show how to integrate a database with spring boot application.

Writing REST API with OpenAPI and SpringBoot

sabyasachi — Sun, 24 Apr 2022 07:08:31 +0000

Till now we have seen how to generate a new spring boot application and then how to containerize it. However our application till does not have any functionality. Today we will see how to create a REST API with Spring boot.We will take a schema first approach and we will generate the REST API stub using the schema. This article will show how a OpenAPI specification looks like and how can we generate our REST API stub using the schema.

OpenAPI Specification

APIs are contract between the application and consumers of the application. These consumers can be machines or humans. OpenAPI is a specification to write your API contract in human and machine readable format. It standardizes the way we can describe our API. The entire specififaction can be found here https://spec.openapis.org/oas/v3.1.0 .

Our First API Spec

Let's create a new service, I call it inventory-service. We now know how to generate a new spring boot application. We add a yml openAPI spec file in src/resources/spec/inventory-api.yml . A minimal API can look as follows -

openapi: "3.0.3"
info:
  title: inventory-api
  version: 1.0.0
paths:
  /products:
    get:
      description: Get All Products
      operationId: getAllProducts
      responses:
        '200':
          description: All products are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfProducts'
        '404':
          description: No Product returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      description: Add A Product to inventory
      operationId: addProduct
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '201':
          description: Product added successfully
          headers:
            location:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/{id}:
    get:
      description: Get A Product By ID
      operationId: getProductById
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Get a product by id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: No Product returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      description: Update A Product
      operationId: updateProduct
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Created product is  returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product Does not Exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListOfProducts:
      type: array
      items:
        $ref: '#/components/schemas/Product'

    Product:
      type: object
      properties:
        id:
          type: string
          format: UUID
    Error:
      type: object
      properties:
        message:
          type: string

It is a very minimal API . We can see in paths section we have description of our API. Each API endpoint has it's optional request body and response body. We can also define if some custom headers are required, path parameters , query parameters and so on.
In the components section we define our models and these are referenced in our API.

I will not go deeper into the OpenAPI spec but because it is very vast but we can always consult the spec for our specific use case .

Generating REST API for Spring

Now that we have our OpenAPI spec, there are plugins and tool available to generate code from our spec. We can use the openapi-generator https://openapi-generator.tech/docs/installation to generate our REST API. We can use cli to generate our REST API.

There is also a maven plugin https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin which we will use to generate our source .

The maven plugin uses the openapi-generator to generate the source code.

To use the maven-plugin we will add it to the build section like following -

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.4.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/spec/inventory-api.yml</inputSpec>
                <generatorName>spring</generatorName>
                <generateSupportingFiles>false</generateSupportingFiles>
                <configOptions>
                    <basePackage>com.sab.inventory</basePackage>
                    <sourceFolder>src/java/main</sourceFolder>
                    <interfaceOnly>true</interfaceOnly>
                    <modelPackage>com.sab.inventory.dto</modelPackage>
                    <apiPackage>com.sab.inventory.api</apiPackage>
                    <skipDefaultInterface>true</skipDefaultInterface>
                    <openApiNullable>false</openApiNullable>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Both the plugin and the actual openapi-generator has lot of config options we can check it from https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin and https://openapi-generator.tech/docs/generators/spring.

In the above example I have used the bare minimum config . I will explain them below .

* `inputSpec` - This is the path to the OpenAPI spec file.
* `generatorName` - ooenapi-generator can produce source code multiple language and framework. Because we want to generate for Spring I chose spring as the generator name.
* `generateSupportingFiles` - When I generated first I saw some unecessary supporting files were generated as I do not need those I turned it to false.
* `configOptions` - Properties that maps directly to the generator options.
   ** `basePackage` - package name for your generated sources
   ** `sourceFolder` - folder where your generated sources will be placed
   **  `interfaceOnly` - We can either generate only REST API interface or we can generate some default code. I make it true as I want to generate only REST API interface.
   ** `modelPackage` - package name for your generated model/dto classes.
   ** `apiPackage` - package name for your generated API classes.
   **   `skipDefaultInterface` - We can skip the genration of default methods in the interface.
   ** `openApiNullable` - With the value true it will generate an import of `org.openapitools.jackson.nullable.JsonNullable` however I didn't need it so I make it false.

So what is the output of the above code ? Below is how our REST API stub looks like

/**
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech) (5.4.0).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 */
package com.sab.inventory.api;

import com.sab.inventory.dto.Error;
import com.sab.inventory.dto.Product;
import java.util.UUID;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.NativeWebRequest;
import org.springframework.web.multipart.MultipartFile;

import javax.validation.Valid;
import javax.validation.constraints.*;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import javax.annotation.Generated;

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2022-04-23T22:00:49.464591+02:00[Europe/Berlin]")
@Validated
@Tag(name = "products", description = "the products API")
public interface ProductsApi {

    /**
     * POST /products
     * Add A Product to inventory
     *
     * @param product  (optional)
     * @return All products are returned (status code 201)
     *         or No Product returned (status code 400)
     */
    @Operation(
        operationId = "addProduct",
        responses = {
            @ApiResponse(responseCode = "201", description = "All products are returned", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Product.class))),
            @ApiResponse(responseCode = "400", description = "No Product returned", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Error.class)))
        }
    )
    @RequestMapping(
        method = RequestMethod.POST,
        value = "/products",
        produces = { "application/json" },
        consumes = { "application/json" }
    )
    ResponseEntity<Product> addProduct(
        @Parameter(name = "Product", description = "", schema = @Schema(description = "")) @Valid @RequestBody(required = false) Product product
    );


    /**
     * GET /products
     * Get All Products
     *
     * @return All products are returned (status code 200)
     *         or No Product returned (status code 404)
     */
    @Operation(
        operationId = "getAllProducts",
        responses = {
            @ApiResponse(responseCode = "200", description = "All products are returned", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Product.class))),
            @ApiResponse(responseCode = "404", description = "No Product returned", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Error.class)))
        }
    )
    @RequestMapping(
        method = RequestMethod.GET,
        value = "/products",
        produces = { "application/json" }
    )
    ResponseEntity<List<Product>> getAllProducts(

    );


    /**
     * GET /products/{id}
     * Get A Product By ID
     *
     * @param id  (required)
     * @return All products are returned (status code 200)
     *         or No Product returned (status code 404)
     */
    @Operation(
        operationId = "getProductById",
        responses = {
            @ApiResponse(responseCode = "200", description = "All products are returned", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Product.class))),
            @ApiResponse(responseCode = "404", description = "No Product returned", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Error.class)))
        }
    )
    @RequestMapping(
        method = RequestMethod.GET,
        value = "/products/{id}",
        produces = { "application/json" }
    )
    ResponseEntity<Product> getProductById(
        @Parameter(name = "id", description = "", required = true, schema = @Schema(description = "")) @PathVariable("id") UUID id
    );


    /**
     * PUT /products/{id}
     * Update A Product
     *
     * @param id  (required)
     * @param product  (optional)
     * @return Created product is  returned (status code 200)
     *         or Error (status code 400)
     *         or Product Does not Exist (status code 404)
     */
    @Operation(
        operationId = "updateProduct",
        responses = {
            @ApiResponse(responseCode = "200", description = "Created product is  returned", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Product.class))),
            @ApiResponse(responseCode = "400", description = "Error", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Error.class))),
            @ApiResponse(responseCode = "404", description = "Product Does not Exist", content = @Content(mediaType = "application/json", schema = @Schema(implementation =  Error.class)))
        }
    )
    @RequestMapping(
        method = RequestMethod.PUT,
        value = "/products/{id}",
        produces = { "application/json" },
        consumes = { "application/json" }
    )
    ResponseEntity<Product> updateProduct(
        @Parameter(name = "id", description = "", required = true, schema = @Schema(description = "")) @PathVariable("id") UUID id,
        @Parameter(name = "Product", description = "", schema = @Schema(description = "")) @Valid @RequestBody(required = false) Product product
    );

}

Now we have our API interface , we can now create our controller and implement the methods.

So that's it for this post, I will actually implement the API using tests so watch out for the next post.

Containerize Your Spring Boot App

sabyasachi — Sat, 16 Apr 2022 11:16:29 +0000

In my previous post https://dev.to/sabyasachi/spring-boot-first-steps-25nl we saw how to create a simple spring boot application which actually does nothing much. I also touched about how to package that as jar file and run locally. However currently in production environment docker is hugely adopted. In this post we will see how to containerize our spring boot application.

First Step, just works

FROM ubuntu:18.04
ARG MAVEN_VERSION=3.8.5
ARG BASE_URL=https://downloads.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries
# Install Java
RUN apt-get update \
    && apt-get install -y curl\
    && apt-get install -y openjdk-17-jdk ca-certificates-java\
    && apt-get clean \
    && update-ca-certificates -f
ENV JAVA_HOME /usr/lib/jvm/java-17-openjdk-amd64
RUN export JAVA_HOME
# Install Maven
RUN  curl -OLs ${BASE_URL}/apache-maven-${MAVEN_VERSION}-bin.tar.gz \
 && tar -xzf apache-maven-${MAVEN_VERSION}-bin.tar.gz -C /usr/local/ \
 && ln -s /usr/local/apache-maven-${MAVEN_VERSION}/bin/mvn /usr/bin/mvn \
 && rm -f /tmp/apache-maven-${MAVEN_VERSION}-bin.tar.gz

COPY . .

RUN mvn clean package
COPY target/*.jar app.jar
CMD ["java","-jar","app.jar"]

We create a new image by running docker build -t spring-first-web-app:1.0.0 and then we run our application by running docker run spring-first-web-app:1.0.0.
So far so good. We see application starting up.

First Improvement

While the above image works just fine, we can see some issues. First one is of size.
If we run docker images spring-first-web-app:1.0.0 we see that the image is about 1 GB.

This is huge for an application which has basically nothing.
First thing we can do to move to a smaller base image.

FROM openjdk:17
ARG MAVEN_VERSION=3.8.5
ARG BASE_URL=https://downloads.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries

RUN  curl -OLs ${BASE_URL}/apache-maven-${MAVEN_VERSION}-bin.tar.gz \
 && tar -xzf apache-maven-${MAVEN_VERSION}-bin.tar.gz -C /usr/local/ \
 && ln -s /usr/local/apache-maven-${MAVEN_VERSION}/bin/mvn /usr/bin/mvn \
 && rm -f /tmp/apache-maven-${MAVEN_VERSION}-bin.tar.gz

COPY . .

RUN mvn clean package
COPY target/*.jar app.jar
CMD ["java","-jar","app.jar"]

We moved to a new base image. OpenJDK which is the open source branch of Java provides many base images. These images has its advantage that we do not need to manually install Java, also these images time to time get security patches and updates. So one task is off our list.

Now when we build our image we can see that the size is reduced to about 600MB

There is also another base image available which is based on alpine linux. Generally Alpine based images are even smaller but as per OpenJDK alpine based images are only supported in EA versions. More see https://hub.docker.com/_/openjdk .

Second Improvement

Can we do better ? If we follow carefully we have two stage , in first stage we download maven and compile our java source code. In second stage we run our packaged application. Once we have our packaged application we do not need anymore mvn and JDK . All we need is a JRE.
Here comes the idea of multistage docker build. In a multistage docker build we can pick and chose artifacts from previous stages and throw away anything from all previous stages.
Below is how we can do this.

FROM eclipse-temurin:17 as build
ARG MAVEN_VERSION=3.8.5
ARG BASE_URL=https://downloads.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries

RUN  curl -OLs ${BASE_URL}/apache-maven-${MAVEN_VERSION}-bin.tar.gz \
 && tar -xzf apache-maven-${MAVEN_VERSION}-bin.tar.gz -C /usr/local/ \
 && ln -s /usr/local/apache-maven-${MAVEN_VERSION}/bin/mvn /usr/bin/mvn \
 && rm -f /tmp/apache-maven-${MAVEN_VERSION}-bin.tar.gz

COPY . .

RUN mvn clean package
COPY target/*.jar app.jar

FROM eclipse-temurin:17-jre-alpine as production
COPY --from=build app.jar .
CMD ["java","-jar","app.jar"]

In the above docker file we have two stages. First stage build is build stage. In build stage we download maven and compile our java source code. In second stage production we run our packaged application. Learn more about multistage docker build from https://docs.docker.com/develop/develop-images/multistage-build/ .

Let's see how much is the docker size now -

We see a huge reduction in size. Point to note here is I have moved to a different base image. Reason is , for production stage I want a JRE only image. However for newer versions of Java the upsteam OpenJDK project didn't produce anymore JREs hence there is no JRE only image. There are a lot of discussion in github about this. For example see https://github.com/docker-library/openjdk/issues/468 .

There is also another provider Adoptium (previously known as AdoptopenJDK) which under their version of Java called Temurin still provides a JRE image. You can find a nice article about their decision https://blog.adoptium.net/2021/12/eclipse-temurin-jres-are-back/ . Hence I moved to using temurin.

Are there still room for improvements ?

Indeed! though not much about size(Well you can try some distroless image).But I would like to focus on below two topic -

Spring Layered image
Spring Buildpack .

Spring buildpack provides support for creating image for spring application without needing to write Dockerfile I have alteady written a post about this https://dev.to/sabyasachi/buildpack-with-spring-boot-300o . This also touched a little about layering.

In a separate posts I will explain how to create a spring layered image.

So, that's it from this post. We now know how to create a bare minimum spring application and how to create an image.

Spring-Boot ,First Step

sabyasachi — Sat, 16 Apr 2022 11:07:11 +0000

Introduction

I have been using Spring framework ecosystem since 2012. Overtime many new modules has been added and the adoption of the framework has increased. As of today it is I can say most popular framework in the industry. But one problem remains for new users of Spring that because Spring does a lot of work under-the-hood, it is sometimes feels like magic and generally production systems differ a lot from your getting started guide it is even more important to not only rely on what is coming out of the box but also to understand how it works. I will be sharing a series of blog post aiming to start with very basics and then move to more advanced topics but focusing with underlying details. I hope this series will help beginners o tip their toes in this beautiful framework.

In this blog we will see how to create your first Spring Boot application. Spring Boot is another offering in Spring framework universe which makes it easy to create a Spring application. It has been highly adopted in todays microservices world.

Spring Boot applications are simple java application with some spring specific dependencies. We can use your own dependency management like maven or gradle to create our application. In this blog I will be using Maven as dependency manager.

First Step

So how to start. There are a few options -

You can use mvn archetype to create a new spring boot application. It can be a simple maven based project.
Another option and which I use very often is to visit the site start.spring.io and create a project from there . Below is a screenshot of how it looks

As we see in the screenshot there are various options . On the left we can use Maven or Gradle as build tool.

We can also chose Java or kotlin or Groovy as our application language. Spring Boot has currently two main version branch 2.x and upcoming 3.x version.

After that we can provide your application name and other details .

It offers to package the application as Jar or War. As of now we will chose Jar . More on how to package your application later.

And finally the Java version, we can chose upto Java 18. For this blog I will stick with Java 17 .

Now lets look at the right side there is something called dependencies. Here is what the first magic happens with Spring Boot applications. As I mentioned earlier, Spring Boot applications are based on spring framework. So there are a few dependencies that are required to run the application. We can either manually provide those dependencies or we can use something called spring-boot-starters these are curated set of dependencies focusing to add some specific feature to applications.

The first dependency that we will use to create a web application is called spring-boot-starter-web. This will give us an embedded tomcat server and enable us to run our application as a web application. After adding it we click on Generate. This will download a zip file with a maven project.

First Application

The generated project structure looks like below

A typical maven project , the pom.xml looks like below

First, we see we have two depedencies, spring-boot-starter-web and spring-boot-starter-test. The later one is used for unit testing and fetches junit5.

Important thing to notice here apart from the dependencies, there is a parent pom which is inherited. The parent pom is spring-boot-starter-parent. This parent pom contains all build plugins and due to which when we do a simple mvn package command we get a runnable jar. It contains many configuration regarding configuration properties and other stuff.

This parent starter in turn inherits from spring-boot-dependencies which contains compatible curated set of dependecies for spring boot.

In your favourite editor you can go inside each of these parent poms and see what they actually fetch, but it is not absolutely necessary to understand each of them as most of the time you need not to configure them.

So now we have a spring boot project we saw what are the dependencies we have. Let's see how to run our very new application and what is the output.

There are many ways to run the application -

Running the jar file. Spring boot applications produce a runnable uber jar with all dependencies inside it, which can be run directly.
Using IDE , every Spring boot application has a main method and we can just run the main method from IDE .
You can also containerize the application and run the docker instant. More of it later. But spring has support for something called buildpack also which will produce an image even without a Dockerfile.

So lets first see running the uber jar . First we package the application using mvn package. Then simply run java -jar <your-jar-file>. For my case the output looks like below

From the output we can see it has started a tomcat server and it is listening on port 8080. This is the default settings. We can also use Jetty server instead of tomcat server. Also we can change the default port to some other port.

What's Inside Your Jar

We can extract the created jar file to see what is inside. To extract or unzip the jar file we can use command jar -xvf <your-jar-file>. The output looks like below

It is important to look inside the jar because a lot of worthy optimization can be done which we will see in later that can contribute in faster builds and startup.

Now at this point we have a running application. We know how to run it locally. Let's see some quick configuration.

Changing the default port

The default port of 8080 is fine may be if we are running a single application, but what if we wanted to run another application ? In a typical production environment a single physical/virtual server may host multiple applications.
We can use server.port property in application.properties to change the port.

Using Jetty instead of tomcat

Tomcat comes out of the box however we can use Jetty as embedded server. To do that we need to use below pom config.

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-tomcat</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jetty</artifactId>
        </dependency>

For details we can see https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto.webserver .

So that's it from this post. We have just taken a tiny step to create a simple spring boot application. In the next post we will deep dive on how to package our application.

Deploy model with FastAPI and Heroku

sabyasachi — Tue, 15 Mar 2022 20:22:03 +0000

In this blog we will see how we can deploy our model with FastAPI and Heroku. Below technologies will be used:

FastAPI
Heroku
Docker
Github workflow
AWS

Our model will classify images of dogs and cats.

First Generating the model

We use the data from https://www.kaggle.com/c/dogs-vs-cats . A model is creted using pretrained resnet model. The kaggle notebook is available here. Not really a SOTA model but it is good enough for our purposes.
We saved the model in AWS S3. We will use the model in our FastAPI server.

The FastAPI service

Our FastAPI server will be a simple REST API. It has one enpoint /pet which will accept an image file and return the prediction. Our code look like this:

@app.post("/pet")
async def predict(file: UploadFile=File(...)):
    image = read_imagefile(await file.read())
    tfms= transforms.Compose([
                                            transforms.Resize((224,224)),
                                            transforms.RandomRotation(20),
                                            transforms.RandomVerticalFlip(p=0.1),
                                            transforms.ToTensor(),
                                            transforms.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225)),
                                            ])
    image = tfms(image)
    image = image[None,:]
    dcModel = DogCatModel(models.resnet34(pretrained=False))
    dcModel.load_state_dict(torch.load('/code/model.pth',map_location=torch.device('cpu')))
    dcModel.eval()
    with torch.no_grad():
        prediction= dcModel(image)
        val,label = torch.max(prediction,dim=1)
        log.info(f"Prediction: {label.item()} with val {val.item()}")
        if val > 0.7:
            label = label.item()
            return {"prediction": label}
        else:
            return {"prediction": "Unknown"}

As you can see the code is a pretty straight forward. We read the image file and transform it to a tensor. We load the model and make a prediction.
The complete code can be found here.

Now that we have our model and the FastApi service we can now deploy it.

The Deployment.

First an application need to be created on heroku. I named the application dog-cat-fastapi.
We can upload the whole code as zip and heroku will automatically deploy the code, however I decided to use docker image as I also wanted to run the code locally.

The dockerFile looks like

FROM ubuntu:20.04

WORKDIR /code

# install utilities
RUN apt-get update && \
    apt-get install --no-install-recommends -y curl && \
    apt-get install -y python3.8 python3-distutils python3-pip python3-apt
# Installing python dependencies
RUN python3 -m pip --no-cache-dir install --upgrade pip && \
    python3 --version && \
    pip3 --version
# pip install aws cli
RUN pip3 install awscli 
ARG MODEL_NAME
ARG AWS_ACCESS_ID
ARG AWS_ACCESS_SECRET
ENV AWS_ACCESS_KEY_ID=$AWS_ACCESS_ID
ENV AWS_SECRET_ACCESS_KEY=$AWS_ACCESS_SECRET
ENV AWS_DEFAULT_REGION=eu-west-1
# Copy model files
RUN aws s3 cp s3://datascience-sab/${MODEL_NAME}.pth .

COPY requirements.txt .

RUN pip3 install --no-cache-dir --upgrade -r /code/requirements.txt

COPY ./app /code/app 

EXPOSE $PORT

CMD gunicorn -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT app.main:app

A few things to notice here -

RUN aws s3 cp s3://datascience-sab/${MODEL_NAME}.pth . command will pull the model file from S3 bucket.
In order to access aws S3 it needs credential, for this worklfow we are passing the credential from github secret and set those in ENV.
When I first deployed the app I could not connect to it , turned out that Heroku does not support the EXPOSE command and it sets the random port as env variable named PORTan we can use that to expose the port. the belo command will make the app avilable in the port CMD gunicorn -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT app.main:app

Finally we make our github workflow below is the step to deploy on heroku

....
....
- name: Build and push
      env:
        HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
        AWS_ACCESS_ID: ${{ secrets.AWS_ACCESS_ID }}
        AWS_ACCESS_SECRET: ${{ secrets.AWS_ACCESS_SECRET }}
      run: heroku container:push web --app=${{ secrets.HEROKU_APP_NAME }} --arg AWS_ACCESS_ID=${{ secrets.AWS_ACCESS_ID }},AWS_ACCESS_SECRET=${{ secrets.AWS_ACCESS_SECRET }},MODEL_NAME=model
    - name: Release
      env:
        HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
      run: heroku container:release web --app=${{ secrets.HEROKU_APP_NAME }}

we pass app name, secrets the model name as build args to heroku container:push command.
After this we use heroku container:release command to release the app.
The complete github workflow can be found here.

With this we can deploy our app to heroku.

Below are some improvements that can be done

Enhance the model .
Introduce model versioning.
Improved logging, tracing and metrics for the service.
Also clean up docker image and stream line all RUN and pip commands.

Thats it for now. It was really satisfying for me to learn about the fastapi framework and deploy a model on heroku.