Forem: Shahid Foy

How to Send Discord Webhook Alerts in Java (Spring Boot Example)

Shahid Foy — Tue, 24 Feb 2026 00:59:12 +0000

If you're building a Java or Spring Boot application and want to send real-time alerts to Discord, this guide will show you exactly how to do it using a lightweight webhook client.

No Discord bot.
No OAuth flow.
Just clean, structured webhook messages sent directly from your backend.

In this article, we’ll walk through:

✅ How Discord webhooks work
✅ How to send webhook messages in Java
✅ A detailed Spring Boot alert example
✅ How to structure rich embeds for production alerts

We’ll be using the n1netails-discord-webhook-client library to make this easy.

You can also follow along by watching the YouTube video here: https://www.youtube.com/watch?v=sBgH_2bOv5Y

Why Send Alerts to Discord from Java?

Many teams already use Discord for communication. Instead of checking dashboards or waiting for email alerts, you can push real-time notifications directly into a channel.

Common use cases:

🚨 Production error alerts
📦 Deployment notifications
🔐 Security findings
💰 Trading bot alerts
📊 Monitoring & uptime notifications

Discord webhooks allow you to send messages using a simple HTTP POST request - perfect for backend systems.

Step 1: Add the Dependency

Maven

<dependency>
  <groupId>com.n1netails</groupId>
  <artifactId>n1netails-discord-webhook-client</artifactId>
  <version>0.3.0</version>
</dependency>

Gradle

implementation 'com.n1netails:n1netails-discord-webhook-client:0.3.0'

This gives you a simple Java client for sending Discord webhook messages.

Step 2: Configure in Spring Boot

@Configuration
public class DiscordWebhookConfig {

    @Bean
    public WebhookService webhookService() {
        return new WebhookService();
    }

    @Bean
    public DiscordWebhookClient discordWebhookClient(WebhookService service) {
        return new DiscordWebhookClientImpl(service);
    }
}

If you're not using Spring Boot:

WebhookService service = new WebhookService();
DiscordWebhookClient client = new DiscordWebhookClientImpl(service);

Make sure to autowire the DiscordWebhookClient in the service you wish to use it on

private final DiscordWebhookClient webhookClient;

public DiscordWebhookDemoApplication(DiscordWebhookClient webhookClient) {
    this.webhookClient = webhookClient;
}

Step 3: Send a Basic Discord Webhook Message in Java

String webhookUrl = "https://discord.com/api/webhooks/xxx/yyy";

Embed embed = new Embed();
embed.setTitle("Build Notification");
embed.setDescription("The build has succeeded! ✅");
embed.setColor(DiscordColor.BLUE.getValue());

WebhookMessage msg = new WebhookMessage();
msg.setUsername("CI Bot");
msg.setContent("Deployment update");
msg.setEmbeds(List.of(embed));
webhookClient.sendMessage(webhookUrl, msg);

That’s the simplest possible example.

Now let’s build something production-ready.

Sending a Detailed Discord Embed Alert (Production Example)

Discord embeds let you send structured messages with:

Title
Description
Colored severity indicator
Fields
Timestamp
Footer
Buttons

Here’s a real-world Spring Boot production error alert example:

String webhookUrl = "https://discord.com/api/webhooks/xxx/yyy";

Embed.Author author = new Embed.Author();
author.setName("N1netails");
author.setUrl("https://n1netails.com");
author.setIcon_url("https://raw.githubusercontent.com/n1netails/n1netails/refs/heads/main/n1netails_icon_transparent.png");

Embed.EmbedField field = new Embed.EmbedField();
field.setName("Environment");
field.setValue("Development");
field.setInline(true);

Embed.Footer footer = new Embed.Footer();
footer.setText("N1netails @ 2026");
footer.setIcon_url("https://raw.githubusercontent.com/n1netails/n1netails/refs/heads/main/n1netails_icon_transparent.png");

Embed.Image image = new Embed.Image();
image.setUrl("https://raw.githubusercontent.com/n1netails/n1netails/refs/heads/main/n1netails_icon_transparent.png");

Embed.Thumbnail thumbnail = new Embed.Thumbnail();
thumbnail.setUrl("https://raw.githubusercontent.com/n1netails/n1netails/refs/heads/main/n1netails_icon_transparent.png");

Embed embed = new EmbedBuilder()
    .withTitle("Build Notification")
    .withDescription("The build has succeeded! ✅")
    .withUrl("https://n1netails.com/")
    .withColor(DiscordColor.ORANGE.getValue())
    .withAuthor(author)
    .withFields(Collections.singletonList(field))
    .withFooter(footer)
    .withImage(image)
    .withThumbnail(thumbnail)
    .withTimestamp(Instant.now().toString())
    .build();

WebhookMessage msg = new WebhookMessageBuilder()
    .withUsername("CI Bot").withContent("Deployment update")
    .withEmbeds(Collections.singletonList(embed))
    .build();

webhookClient.sendMessage(webhookUrl, msg);

This produces a clean, structured Discord alert that your team can immediately scan and act on.

Instead of dumping stack traces into chat, you send contextual, readable notifications.

When Should You Use Discord Webhooks in Spring Boot?

You should use Discord webhooks when:

You want lightweight alerting without managing a bot
Your team already communicates in Discord
You need fast, visible notifications
You want structured alert formatting

For many internal tools, Discord webhooks are faster to implement than full monitoring systems.

Final Thoughts

If you're building backend systems in Java or Spring Boot, sending alerts to Discord via webhooks is one of the simplest ways to improve visibility.

The n1netails-discord-webhook-client makes this process clean, structured, and developer-friendly.

No heavy frameworks.
No bot complexity.
Just fast alerts where your team already is.

Build a Telegram Bot in Java with the N1netails Telegram Client

Shahid Foy — Sun, 15 Feb 2026 22:43:42 +0000

If you’ve ever wanted to send automated alerts, notifications, or rich media messages to Telegram from your Java application, you’ve probably discovered that working directly with the Telegram Bot API can get repetitive fast.

That’s where N1netails Telegram Client comes in. N1netails a lightweight, open-source Java library designed to make sending Telegram messages simple, structured, and production-ready.

In this guide, you’ll learn:

✅ How to create a Telegram bot
✅ How to configure the N1netails client
✅ How to send text, GIFs, images, videos, and media groups
✅ How to add call-to-action buttons

What is N1netails Telegram Client?

N1netails is an open-source project focused on practical alerting and monitoring. The Telegram client module lets you easily send structured Telegram messages from Java applications perfect for:

Alerting systems
Automation tools
Monitoring dashboards
DevOps workflows
App notifications

Instead of hand-crafting API requests, you work with clean Java objects.

🎥 Watch the full video tutorial:
https://www.youtube.com/watch?v=T7drCapES6U

Step 1 - Set Up Telegram

Before using the client, you need a Telegram bot.

Install Telegram

Download Telegram on your smartphone first:

👉 https://telegram.org/

Telegram requires initial mobile setup before desktop use.

Create Your Telegram Bot

1. Talk to BotFather

Open Telegram and search for:

@BotFather

This is Telegram’s official bot manager.

2. Create a new bot

Send:

/newbot

You’ll be prompted to:

Name your bot
Choose a username (must end in bot)

Example:

n1netails_alertbot

3. Save your bot token

BotFather will generate something like:

123456789:ABCdefGhIJKlmNoPQRstuVWXyz

⚠ Keep this private — anyone with it controls your bot.

4. Add the bot to a chat

Add your bot to:

A group chat
Or a direct chat

Ensure it has permission to send messages.

5. Get the chat ID

Option A — Use a helper bot:

@getidsbot

Option B — Use Telegram API:

curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

Look for:

"chat":{"id":...}

You now have:

✔ Bot token
✔ Chat ID

Step 2 - Install the Library

Maven

<dependency>
  <groupId>com.n1netails</groupId>
  <artifactId>n1netails-telegram-client</artifactId>
  <version>0.3.0</version>
</dependency>

Gradle

implementation 'com.n1netails:n1netails-telegram-client:0.3.0'

Step 3 - Configuration

Spring Boot Setup

Create a configuration class:

@Configuration
public class TelegramConfig {

  @Bean
  public BotService botService() {
    return new BotService();
  }

  @Bean
  public TelegramClient telegramClient(BotService service) {
    return new TelegramClientImpl(service);
  }
}

Plain Java Setup

BotService service = new BotService();
TelegramClient client = new TelegramClientImpl(service);

Step 4 - Sending Messages

Simple Text Message

TelegramMessage msg =
  new TelegramMessage("Telegram works!", false);

client.sendMessage(chatId, botToken, msg);

GIF Message

TelegramMessage msg =
  new TelegramMessage(
    "Check this GIF!",
    "https://giphy-url.gif",
    false
  );

CTA Button Message

Button button =
  new Button("Visit Site", "https://example.com");

InlineKeyboardMarkup markup =
  new InlineKeyboardMarkup(List.of(List.of(button)));

TelegramMessage msg =
  new TelegramMessage("Click below!", false, markup);

Image Message

TelegramMessage msg = new TelegramMessage();
msg.setText("Photo alert!");
msg.setImages(List.of("https://image-url.png"));

Video Message

TelegramMessage msg = new TelegramMessage();
msg.setText("Video alert!");
msg.setVideos(List.of("https://video-url.mp4"));

Media Group (Images + Videos)

TelegramMessage msg = new TelegramMessage();
msg.setText("Media bundle!");
msg.setImages(List.of("image1.png", "image2.png"));
msg.setVideos(List.of("video.mp4"));

⚠ Note: Telegram does not allow CTA buttons with media groups.

Important Notes

Media must be public URLs
CTA buttons only work with single media messages
Keep bot tokens secure

Why Use This Client?

Without the library:

❌ Manual API formatting
❌ Boilerplate HTTP calls
❌ Error-prone message building

With N1netails:

✅ Clean Java message models
✅ Structured API calls
✅ Rich media support
✅ Production-ready workflow

Final Thoughts

The N1netails Telegram Client removes friction when integrating Telegram messaging into Java applications. Whether you’re building alerts, automation, or monitoring systems, it gives you a simple and extensible foundation.

If you want fast Telegram integration without wrestling the raw API, this library is a solid choice.

👉 GitHub repository:
https://github.com/n1netails/n1netails-telegram-client

🦊 N1netails:
https://n1netails.com/

Join the Discord:
https://discord.gg/ma9CCw7F2x

If this helped you, consider starring the repo and sharing it with other Java developers. Happy building 🚀

How I Used Google Jules to Implement Google OAuth2 in My Spring Boot + Angular Application

Shahid Foy — Wed, 26 Nov 2025 23:51:48 +0000

Google Jules has been out for a few months now, and I decided to finally give it a real development task:
implement Google OAuth2 login in my Spring Boot + Angular application (N1netails)—while following the exact same authentication pattern I previously implemented for GitHub OAuth2.

A while back, I wrote a detailed guide covering the GitHub OAuth2 integration, which serves as the prequel to this article:
👉 https://dev.to/shahidfoy/how-i-implemented-github-oauth2-into-my-spring-boot-angular-app-n1netails-5bo

For this update, I reused the same structure and simply extended it for Google OAuth2.

Tag: v0.3.14 https://github.com/n1netails/n1netails/tree/v0.3.14
Pull Request: https://github.com/n1netails/n1netails/pull/203/files

Using Google Jules, I asked it to analyze the existing GitHub OAuth2 logic and apply the same pattern for the Google OAuth2 flow—making the integration faster, more consistent, and less error-prone.

🔐 Google OAuth2 in Spring Boot

The most important configuration piece is the registrationId Spring Security uses to differentiate OAuth providers.
It corresponds directly to your YAML keys:

spring.security.oauth2.client.registration.github
spring.security.oauth2.client.registration.google

OAuth2 Configuration (application-oauth.yml)

https://github.com/n1netails/n1netails/blob/v0.3.14/n1netails-api/src/main/resources/application-oauth.yml

spring:
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: ${GITHUB_CLIENT_ID:your-github-client-id}
            client-secret: ${GITHUB_CLIENT_SECRET:your-github-client-secret}
            scope: read:user,user:email
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"  # /login/oauth2/code/github
            client-name: GitHub
          google:
            client-id: ${GOOGLE_CLIENT_ID:your-google-client-id}
            client-secret: ${GOOGLE_CLIENT_SECRET:your-google-client-secret}
            scope: openid,email,profile
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}" # /login/oauth2/code/google
            client-name: Google
        provider:
          github:
            authorization-uri: https://github.com/login/oauth/authorize
            token-uri: https://github.com/login/oauth/access_token
            user-info-uri: https://api.github.com/user

🔄 OAuth2 Success Handler

After a successful login, Spring Boot passes the OAuth token + user info to my OAuth2Service. From there, the service generates a JWT token for N1netails and redirects to the Angular frontend.

Code reference:
https://github.com/n1netails/n1netails/blob/89f84bbd13b845888e8cc279b0334603ef8207ab/n1netails-api/src/main/java/com/n1netails/n1netails/api/config/security/Oauth2LoginSecurityConfig.java#L47-L54

.oauth2Login(oauth2 -> oauth2
    .successHandler((request, response, authentication) -> {
        OAuth2AuthenticationToken oauthToken = (OAuth2AuthenticationToken) authentication;
        OAuth2User oAuth2User = (OAuth2User) authentication.getPrincipal();
        String provider = oauthToken.getAuthorizedClientRegistrationId();
        String jwtToken;

        if ("github".equalsIgnoreCase(provider)) {
            jwtToken = oAuth2Service.loginGithub(oAuth2User, oauthToken);
        } else if ("google".equalsIgnoreCase(provider)) {
            jwtToken = oAuth2Service.loginGoogle(oAuth2User, oauthToken);
        } else {
            throw new IllegalStateException("Unexpected provider: " + provider);
        }

        response.sendRedirect(oAuth2RedirectsSuccess + jwtToken);
    })
);

🧩 Google Login Service Logic

If you’re curious how oAuth2Service.loginGoogle() is implemented, you can see the full logic here:

https://github.com/n1netails/n1netails/blob/89f84bbd13b845888e8cc279b0334603ef8207ab/n1netails-api/src/main/java/com/n1netails/n1netails/api/service/impl/OAuth2ServiceImpl.java#L135-L200

In short:

Spring Security sends the Google OAuth user details.
The service creates or updates the user in the N1netails database.
A JWT token is generated for the SPA (Angular).
No passwords are stored—identity is validated by Google.

This is one of the biggest benefits of OAuth2:
authentication is delegated to the provider, reducing security risk in your system.

🖥️ Google Login on the Angular Frontend

Google Jules also helped mirror the GitHub login button structure on the Angular side.

HTML reference:
https://github.com/n1netails/n1netails/blob/v0.3.14/n1netails-ui/src/main/typescript/src/app/pages/login/login.component.html#L71-L81

<button
  *ngIf="googleAuthEnabled"
  nz-button
  nzType="primary"
  (click)="loginWithGoogle()"
  class="login-btn google-login-btn"
  type="button"
>
  <nz-icon nzType="google" nzTheme="outline" style="margin-right: 8px;" />
  Login with Google
</button>

Angular Login Method

https://github.com/n1netails/n1netails/blob/89f84bbd13b845888e8cc279b0334603ef8207ab/n1netails-ui/src/main/typescript/src/app/pages/login/login.component.ts#L57-L61

loginWithGoogle() {
  // window.location.href = 'http://localhost:9901/oauth2/authorization/google';
  window.location.href = this.uiConfigService.getApiUrl() + '/oauth2/authorization/google';
}

The commented line (http://localhost:9901/...) is just the default local Spring Boot OAuth2 endpoint during development.

📌 Full Pull Request

To see every change involved in adding Google OAuth2 to both Spring Boot and Angular:

👉 https://github.com/n1netails/n1netails/pull/203/files

⭐ Final Thoughts

Using Google Jules to extend my OAuth2 implementation saved time and helped keep the pattern consistent across providers.
If you're building a Spring Boot + Angular app and want to offer multiple OAuth providers (GitHub, Google, etc.), this approach is clean, reusable, and secure.

If you found this helpful, please consider starring the repo 💙
👉 https://github.com/n1netails/n1netails

📨 Mocking Emails in a Spring Boot App Using MailHog – How I Integrated Email Testing into N1netails

Shahid Foy — Thu, 07 Aug 2025 21:53:20 +0000

Recently, I added a new email notification feature to my N1netails project — a developer-focused alerting tool built with Spring Boot. One of the contributors suggested we look into using MailHog for local email testing, which turned out to be a great fit.

📬 Now, new users receive a welcome email when signing up, and existing users get alerts via email when something important happens.

When deploying to production via N1netails Dashboard, I registered a real email address via Outlook. But for local development and testing, I needed a way to simulate sending emails without actually sending them.

That’s where MailHog came in — a lightweight, fake SMTP server with a built-in web UI for viewing test emails.

🔧 What is MailHog and Why Use It in a Spring Boot Project?

MailHog is a tool that captures outgoing emails sent from your app, so you can:

✅ Test email templates without spamming real inboxes
✅ Debug SMTP configurations locally
✅ Preview emails in a browser

It’s ideal for Spring Boot developers building user signup flows, alerting systems, or any feature involving transactional emails.

🚀 Step-by-Step: How to Use MailHog with Spring Boot

1. Install MailHog

Option A: Binary Download

Download the binary from MailHog GitHub Releases

# Example for Windows:
mv MailHog_windows_amd64.exe mailhog.exe

Option B: Go

go install github.com/mailhog/MailHog@latest

Option C: Docker (Recommended)

docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog

2. Run MailHog

If you're using Docker, it's already running:

SMTP Server → localhost:1025
Web UI → http://localhost:8025

3. Configure Spring Boot to Use MailHog

Update your application.yml (or use Spring profiles):
View how it is configured in n1netails here application-email.yml

spring:
  mail:
    host: localhost
    port: 1025
    username: dummy
    password: dummy
    from: support@n1netails.com
    properties:
      mail.smtp.auth: false
      mail.smtp.starttls.enable: false

Optional: Make it toggleable using environment variables:

n1netails:
  email:
    enabled: ${EMAIL_ENABLED:false}

4. Trigger an Email

You can test by creating an account on the live N1netails Dashboard — or just simulate it in your code.

5. Preview Emails in the Web UI

Go to http://localhost:8025 to:

View email subject and content
Inspect headers
Test HTML rendering

🛠️ How N1netails Uses Email Templates (Spring Boot + Liquibase)

Here’s how I wired the backend email flow inside N1netails:

Email templates are stored in the DB
I load them via a Spring Data repository
Dynamic content is injected using {{placeholders}}
Emails are sent using JavaMailSender

Templates are pre-loaded using Liquibase.

📥 SQL Table for Templates

db.changelog-00012:

CREATE TABLE IF NOT EXISTS ntail.email_notification_template
(
    id BIGINT NOT NULL,
    name character varying(100),
    subject TEXT,
    html_body TEXT,
    CONSTRAINT email_notification_template_pkey PRIMARY KEY (id)
);

🎨 HTML Welcome & Alert Email Templates

Welcome & Alert Template SQL
Includes {{username}}, {{n1netailsEmail}}, and more

🧬 Spring Boot Code for Sending Emails in N1netails

Entity:
EmailNotificationTemplateEntity.java

Repository:
EmailNotificationTemplateRepository.java

Service:
EmailServiceImpl.java

It fetches the email template by name, applies dynamic parameters, and sends using JavaMailSender.

✅ Summary

With MailHog, I was able to:

Add robust email notifications to N1netails
Test locally with no risk of spamming users
Preview and iterate on email designs
Keep emails stored and maintainable in a database

If you're building a Spring Boot SaaS, consider adding MailHog to your local dev workflow!

💬 If you found this useful or want to see more behind-the-scenes of N1netails, feel free to follow or ask questions. I'm building this open and dev-first. If you are interested in contributing you can view the GitHub

🦊 Happy coding!

How I Implemented GitHub OAuth2 into My Spring Boot + Angular App N1netails

Shahid Foy — Sat, 02 Aug 2025 04:28:00 +0000

Not everyone wants to log into a website using a basic email and password form. Sometimes it’s due to a lack of trust, and other times, just pure convenience. That’s why many websites now offer OAuth2 login options—reducing the cognitive load of remembering passwords and adding an extra layer of trust via a known provider.

I recently implemented GitHub OAuth2 login in my N1netails application and wanted to share how I got it working.

N1netails is built using the JASP stack (Java, Angular, Spring Boot, and PostgreSQL). Okay, I made up the acronym, but you get the idea. Spring Boot greatly simplifies OAuth2 integration—it handles most of the "magic" behind the scenes. But integrating it smoothly with an Angular frontend still takes some work. I initially followed Spring Boot and OAuth2, but found it lacking guidance for an Angular setup. So here’s the full walkthrough based on what I learned.

You can also check out the actual pull request here: GitHub OAuth2 Implementation Pull Request

Setting Up a GitHub OAuth2 App

Before getting started, you’ll need to create a GitHub OAuth2 App via Developer Settings.

Here’s what I used for the configuration:

Application name: n1netails-local
Homepage URL: https://localhost:4200
Application description: (Add a brief description of your app)
Authorization callback URL: http://localhost:9901/login/oauth2/code/github

Once you've completed the setup, GitHub will generate a Client ID and Client Secret. Make sure to save these values—they’ll be added to your application.properties (or application.yml) later for Spring Boot to use.

The OAuth2 Flow (Spring Boot + Angular)

Here’s the basic flow I implemented:

The Angular login page presents a GitHub login button.
Clicking the button redirects the user to Spring Boot's OAuth2 authorization endpoint.
After authentication, Spring Boot generates a JWT and redirects the user back to Angular.
Angular captures the token and fetches the user profile.
The app is now authenticated and fully functional for the user.

1. GitHub Login Button in Angular

On the login page, I created a GitHub login button. When clicked, it redirects the user to the backend for GitHub authorization.

login.component.html

<button 
  *ngIf="githubAuthEnabled"
  nz-button
  nzType="default"
  (click)="loginWithGithub()"
  class="login-btn github-login-btn"
  type="button"
>
 <nz-icon nzType="github" nzTheme="outline" style="margin-right: 8px;"/>
 Login with GitHub
</button>

login.component.ts

loginWithGithub() {
  // Redirects to Spring Boot's OAuth2 authorization endpoint
  // window.location.href = 'http://localhost:9901/oauth2/authorization/github';
  window.location.href = this.uiConfigService.getApiUrl() + '/oauth2/authorization/github';
}

2. Backend: Spring Boot OAuth2 Configuration

Start by adding the required Spring Security OAuth2 dependency to your backend:

pom.xml

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

This automatically enables the /oauth2/authorization/github endpoint, which Spring Security uses to initiate the OAuth2 login flow.

Next, configure your OAuth2 settings in application.properties or application.yml. Here's what my setup looks like using YAML:

application-oauth.yml

auth:
  github:
    enabled: ${GITHUB_OAUTH2_ENABLED:true}
  oauth2:
    redirects:
      success: ${AUTH_OAUTH2_REDIRECT_SUCCESS:http://localhost:4200/#/oauth2/success?token=}

spring:
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: ${GITHUB_CLIENT_ID:your-github-client-id}
            client-secret: ${GITHUB_CLIENT_SECRET:your-github-client-secret}
            scope: read:user,user:email
            redirect-uri: "{baseUrl}/login/oauth2/code/github"
            client-name: GitHub
        provider:
          github:
            authorization-uri: https://github.com/login/oauth/authorize
            token-uri: https://github.com/login/oauth/access_token
            user-info-uri: https://api.github.com/user

🔐 Note: Replace your-github-client-id and your-github-client-secret with the actual credentials you generated from GitHub. If you're using environment variables (recommended for security), make sure GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are defined in your environment. Also make sure the GitHub OAuth2 process is enabled for GITHUB_OAUTH2_ENABLED.

This configuration tells Spring Security how to interact with GitHub's OAuth2 endpoints and how to handle the redirect after successful authentication.

Since my app already supports email/password login via JWT, I created a separate Spring Security config for OAuth2. This allows GitHub auth to be handled with higher priority by using @Order.

Oauth2LoginSecurityConfig.java

@Order(1)
@Configuration
@ConditionalOnProperty(prefix = "auth.github", name = "enabled", havingValue = "true")
public class Oauth2LoginSecurityConfig {
    http
        .securityMatcher("/oauth2/**", "/login/**")
        .authorizeHttpRequests(auth -> auth
                .requestMatchers("/oauth2/**", "/login/**").authenticated()
                .anyRequest().permitAll()
        )
        .csrf(AbstractHttpConfigurer::disable)
        .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED))
        .oauth2Login(oauth2 -> oauth2
                .successHandler((request, response, authentication) -> {
                    OAuth2AuthenticationToken oauthToken = (OAuth2AuthenticationToken) authentication;
                    OAuth2User oAuth2User = (OAuth2User) authentication.getPrincipal();

                    String jwtToken = oAuth2Service.loginGithub(oAuth2User, oauthToken);
                    // Redirect to Angular app with the token as query param (ex. "http://localhost:4200/oauth2/success?token=" + jwtToken)
                    response.sendRedirect(oAuth2RedirectsSuccess + jwtToken);
                })
        );

    return http.build();
}

Note: I used SessionCreationPolicy.IF_REQUIRED to allow Spring Security to maintain session state only when needed, without affecting my JWT-based setup.

3. Handling the OAuth2 Login in Backend

This is where most of the GitHub integration logic lives—inside the OAuth2Service. It handles user retrieval, creation, linking accounts, and generating JWTs.

OAuth2ServiceImpl.java

@Slf4j
@Service
@Transactional
@RequiredArgsConstructor
@Qualifier("oAuth2Service")
public class OAuth2ServiceImpl implements OAuth2Service {

    private final UserRepository userRepository;
    private final OrganizationRepository organizationRepository;
    private final JwtTokenUtil jwtTokenUtil;

    private final OAuth2AuthorizedClientService authorizedClientService;
    private final RestTemplate restTemplate = new RestTemplate();

    @Override
    public String loginGithub(OAuth2User oAuth2User, OAuth2AuthenticationToken authentication) {

        log.info("loginGithub");
        log.info("getting user info from OAuth2User");
        String provider = "GITHUB";
        log.info("providerId");
        String providerId = Optional.ofNullable(oAuth2User.getAttribute("id")).map(Object::toString).orElse(null);
        log.info("username");
        String username = oAuth2User.getAttribute("login");
        log.info("email");
        String email = oAuth2User.getAttribute("email"); // may be null
        log.info("avatarUrl");
        String avatarUrl = oAuth2User.getAttribute("avatar_url");
        log.info("name");
        String name = oAuth2User.getAttribute("name");
        log.info("getting user info from OAuth2User COMPLETED");

        OAuth2AuthorizedClient client = authorizedClientService.loadAuthorizedClient(
                authentication.getAuthorizedClientRegistrationId(),
                authentication.getName()
        );
        String accessToken = client.getAccessToken().getTokenValue();

        if (email == null) email = fetchPrimaryEmailFromGithub(accessToken);
        if (email == null) email = username + "@users.noreply.github.com";

        // Step 1: Try to find existing user by provider+providerId
        UsersEntity user = userRepository.findByProviderAndProviderId(provider, providerId).orElse(null);

        if (user == null) {
            // Step 2: Try to find by email
            user = userRepository.findUserByEmail(email).orElse(null);

            if (user != null) {
                // Step 3: Link GitHub to existing user
                log.info("Linking GitHub to existing user: {}", email);
                user.setProvider(provider);
                user.setProviderId(providerId);
            } else {
                // Step 4: New user registration
                log.info("Creating new user from GitHub OAuth2");
                user = new UsersEntity();
                user.setProvider(provider);
                user.setProviderId(providerId);
                user.setUserId(UserUtil.generateUserId());
                user.setJoinDate(new Date());
                user.setActive(true);
                user.setEnabled(true);
                user.setNotLocked(true);
                user.setRole(com.n1netails.n1netails.api.model.enumeration.Role.ROLE_USER.name());
                user.setAuthorities(Authority.USER_AUTHORITIES);

                OrganizationEntity n1netailsOrg = organizationRepository.findByName("n1netails")
                        .orElseThrow(() -> new RuntimeException("Default 'n1netails' organization not found."));

                user.setOrganizations(new HashSet<>(Set.of(n1netailsOrg)));
            }
        }

        // Common fields for all paths
        user.setEmail(email);
        user.setUsername(username);
        user.setProfileImageUrl(avatarUrl);

        // Set names
        if (name != null && !name.isBlank()) {
            int lastSpace = name.lastIndexOf(" ");
            if (lastSpace != -1) {
                user.setFirstName(name.substring(0, lastSpace));
                user.setLastName(name.substring(lastSpace + 1));
            } else {
                user.setFirstName(name);
            }
        }

        user.setLastLoginDateDisplay(user.getLastLoginDate());
        user.setLastLoginDate(new Date());

        log.info("Saving user from GitHub OAuth2");
        userRepository.save(user);

        return jwtTokenUtil.createToken(new UserPrincipal(user));
    }


    private String fetchPrimaryEmailFromGithub(String accessToken) {
        String url = "https://api.github.com/user/emails";
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "token " + accessToken);

        HttpEntity<Void> entity = new HttpEntity<>(headers);
        ResponseEntity<List<Map<String, Object>>> response = restTemplate.exchange(
                url,
                HttpMethod.GET,
                entity,
                new ParameterizedTypeReference<>() {}
        );

        if (response.getStatusCode().is2xxSuccessful() && response.getBody() != null) {
            for (Map<String, Object> emailObj : response.getBody()) {
                Boolean primary = (Boolean) emailObj.get("primary");
                Boolean verified = (Boolean) emailObj.get("verified");
                String email = (String) emailObj.get("email");
                if (primary != null && primary && verified != null && verified) {
                    return email;
                }
            }
        }
        return null; // fallback if no primary email found
    }
}

Key highlights:

Tries to find a user by provider and providerId
If not found, checks by email to potentially link accounts
If still not found, creates a new user
Finally, returns a JWT for the session

If GitHub doesn’t provide the email, we fetch it manually using the access token:

private String fetchPrimaryEmailFromGithub(String accessToken) {
    ...
    return email; // if primary + verified found
}

4. Updating the User Entity

I added provider and providerId fields to track OAuth2 providers like GitHub:

UsersEntity.java

private String provider;    // ex. "GITHUB"
private String providerId;  // GitHub user ID

5. Updating the Repository

To support provider-based lookups:

UserRepository.java

Optional<UsersEntity> findByProviderAndProviderId(String provider, String providerId);

6. Redirecting Back to Angular After Successful OAuth2 Login

After successful login, Spring redirects the user to Angular with the JWT token:

Oauth2LoginSecurityConfig.java

response.sendRedirect(oAuth2RedirectsSuccess + jwtToken);

7. Angular: Capturing the JWT Token

In Angular, I created a route /oauth2/success and a component to process the token:

oauth2-success.component.ts

ngOnInit(): void {
  this.route.queryParams.subscribe(params => {
    const token = params['token'];
    if (token) {
      this.authenticationService.saveToken(token);
      this.userService.getSelf().subscribe(user => {
        this.authenticationService.addUserToLocalCache(user);
        this.router.navigate(['/dashboard']);
      });
    } else {
      this.router.navigate(['/login']);
    }
  });
}

8. Getting the Authenticated User

The frontend calls the /self endpoint to fetch the user’s profile using the JWT token.

user.service.ts

getSelf(): Observable<User> {
  return this.http.get<User>(`${this.uiConfigService.getApiUrl()}/ninetails/user/self`);
}

Backend:

UserController.java

@GetMapping("/self")
public ResponseEntity<UsersEntity> getCurrentUser(@RequestHeader(AUTHORIZATION) String authorizationHeader) {
    ...
    return ResponseEntity.ok(user);
}

Wrap-Up and Improvements

That’s the full OAuth2 login integration with GitHub in my Spring Boot + Angular app.

A few potential improvements I’m considering:

Adding a failure handler inside Oauth2LoginSecurityConfig
Simplifying the logic in the /self endpoint
Adding support for other providers like Google or LinkedIn

You can check out the full PR again here: GitHub OAuth2 Implementation Pull Request

If you’re curious about Project N1netails, here are some links:

Fixing OutOfMemoryError in Spring Boot: Implementing Pagination (With Angular Example)

Shahid Foy — Sun, 20 Jul 2025 00:35:16 +0000

Earlier this week, I asked other Spring Boot developers to test my side project, N1netails Dashboard—a self-hosted, developer-friendly alerting and monitoring platform built with Spring Boot (backend) and Angular (frontend).

The goal of N1netails is to provide an open-source alternative to heavy SaaS solutions like PagerDuty, making it easy for developers to send and manage alerts from their applications. It’s designed to be lightweight, customizable, and perfect for small teams or embedded use cases.

During testing, we discovered a critical issue: my small 1GB DigitalOcean droplet kept crashing with an OutOfMemoryError. The culprit? Some API endpoints were returning all rows from certain database tables at once.

I knew this was bound to happen eventually, but I didn’t expect it so soon. This reminded me why early testing—especially with QA engineers or security-minded red teamers—is crucial for side projects. Catching performance bottlenecks early saves you from production headaches later.

The fix was simple but powerful: implementing pagination in both my Spring Boot backend and Angular frontend. Here’s how I did it.

What is pagination?

Pagination splits large datasets into smaller, manageable pages instead of loading everything at once. This keeps your app responsive and avoids memory crashes.

Think of Google Search—when you search for something, it doesn’t show millions of results at once. Instead, it loads 10–20 results per page, improving performance and user experience.

In my case, returning thousands of database rows in a single API response was eating up memory. Pagination limited each request to 50 rows at a time, fixing the OutOfMemoryError instantly.

Implementing pagination in my Spring Boot application

I implemented pagination in four steps.

1. Create a `PageRequest` POJO

This object lets the frontend specify page size, sorting, and optional search terms.

PageRequest

import lombok.Getter;
import lombok.Setter;
import org.springframework.data.domain.Sort;

@Getter
@Setter
public class PageRequest {
    private int pageNumber = 0;
    private int pageSize = 10;
    private Sort.Direction sortDirection = Sort.Direction.ASC;
    private String sortBy = "id";
    private String searchTerm;
}

✔ What each field does

pageNumber → Which page to load (starts at 0).
pageSize → How many rows per page.
sortDirection → ASC or DESC.
sortBy → Which column to sort by.
searchTerm → Optional filter for the results.

2. Update the Repository

For my tail_type table, I updated the repository to use Spring Data JPA’s Page and Pageable.

TailTypeRepository

@Repository
public interface TailTypeRepository 
    extends PagingAndSortingRepository<TailTypeEntity, Long>, 
            JpaRepository<TailTypeEntity, Long> {

    Optional<TailTypeEntity> findTailTypeByName(String name);

    Page<TailTypeEntity> findByNameContainingIgnoreCase(String searchTerm, Pageable pageable);
}

Behind the scenes, Spring converts this method into SQL like:

SELECT t.*
FROM tail_type t
WHERE LOWER(t.name) LIKE LOWER(CONCAT('%', :searchTerm, '%'))
ORDER BY t.id ASC
LIMIT :pageSize OFFSET :offset;

3. Update the Service Layer

The service takes the PageRequest, builds a Pageable, and maps TailTypeEntity → TailTypeResponse.

TailTypeServiceImpl

@Override
public Page<TailTypeResponse> getTailTypes(PageRequest request) {
    Sort sort = Sort.by(request.getSortDirection(), request.getSortBy());
    Pageable pageable = org.springframework.data.domain.PageRequest.of(
        request.getPageNumber(), request.getPageSize(), sort
    );

    Page<TailTypeEntity> tailTypeEntities = 
        (request.getSearchTerm() != null && !request.getSearchTerm().isEmpty())
        ? tailTypeRepository.findByNameContainingIgnoreCase(request.getSearchTerm(), pageable)
        : tailTypeRepository.findAll(pageable);

    List<TailTypeResponse> tailTypeResponseList = tailTypeEntities
        .stream()
        .map(this::generateTailTypeResponse)
        .toList();

    return new PageImpl<>(tailTypeResponseList, pageable, tailTypeEntities.getTotalElements());
}

4. Expose Pagination in the Controller

Finally, the controller accepts a PageRequest and returns a paginated response.

TailTypeController

@Operation(summary = "Get all tail types", responses = {
    @ApiResponse(responseCode = "200", description = "Paginated tail types",
        content = @Content(array = @ArraySchema(schema = @Schema(implementation = TailTypeResponse.class))))
})
@GetMapping
public ResponseEntity<Page<TailTypeResponse>> getTailTypes(@ParameterObject PageRequest request) {
    return ResponseEntity.ok(tailTypeService.getTailTypes(request));
}

Angular Implementation

Once the backend was ready, I added pagination support to the Angular frontend.

1. Define Interfaces

These match the backend request and response.

Page Interface

export interface PageRequest {
    pageNumber: number;
    pageSize: number;
    sortDirection: string;
    sortBy: string;
    searchTerm?: string;
}

export interface PageResponse<T> {
    content: T[];
    totalPages: number;
    totalElements: number;
    size: number;
    number: number; // current page number
}

2. Create a Pagination Utility Service

A helper service to generate default pagination params.

PageUtilService

@Injectable({ providedIn: 'root' })
export class PageUtilService {
  getPageRequestParams(pageRequest: PageRequest): HttpParams {
    let params = new HttpParams()
      .set('pageNumber', pageRequest.pageNumber)
      .set('pageSize', pageRequest.pageSize)
      .set('sortDirection', pageRequest.sortDirection)
      .set('sortBy', pageRequest.sortBy);

    if (pageRequest.searchTerm) {
      params = params.set('searchTerm', pageRequest.searchTerm);
    }
    return params;
  }

  setDefaultPageRequest(): PageRequest {
    return { pageNumber: 0, pageSize: 50, sortDirection: "ASC", sortBy: "id" };
  }

  setDefaultPageRequestWithSearch(term: string): PageRequest {
    return { ...this.setDefaultPageRequest(), searchTerm: term };
  }
}

3. Call the API in a Service

TailTypeService

getTailTypes(pageRequest: PageRequest): Observable<PageResponse<TailTypeResponse>> {
    let params = this.pageUtilService.getPageRequestParams(pageRequest);
    return this.http.get<PageResponse<TailTypeResponse>>(this.host, { params });
}

4. Display Paginated Data

Finally, I used the service in my settings component:

Setting component

private listTailTypes() {
  const pageRequest: PageRequest = this.pageUtilService.setDefaultPageRequest();
  this.tailTypeService.getTailTypes(pageRequest)
    .subscribe((response: PageResponse<TailTypeResponse>) => {
      this.tailTypes = response.content;
    });
}

And rendered it in the template:

Setting component HTML

<div class="alert-list">
  <h4>Tail Types</h4>
  <div class="alert-form">
    <input nz-input [(ngModel)]="searchTailType" (ngModelChange)="searchType()" name="searchTailType"
      placeholder="Search type" class="alert-input" />
    <button nz-button nzType="default" (click)="searchType()" class="alert-btn"><nz-icon nzType="search"
        nzTheme="outline" /></button>
  </div>
  <ul>
    <li *ngFor="let type of tailTypes">
      {{ type.name }}
      <button *ngIf="type.deletable" nz-button nzType="link" nzDanger
        (click)="removeAlertType(type.name)">Remove</button>
    </li>
  </ul>
  <div class="alert-form">
    <input nz-input [(ngModel)]="newTailType" name="newTailType" placeholder="Add new type" class="alert-input" />
    <button nz-button nzType="default" (click)="addAlertType()" class="alert-btn">+</button>
  </div>
</div>

Final Thoughts

Before pagination, my /ninetails/tail-type endpoint returned thousands of rows, causing my 1GB DigitalOcean droplet to crash. After implementing pagination, each request now loads only 50 rows, fixing the issue and making the app much faster.

If you want to test it yourself, check out N1netails Dashboard or the N1netails GitHub.

Questions? Contributions? Join me on Discord.

How I Secured Passwords in My Spring Boot Project (N1netails) Using BCrypt

Shahid Foy — Sun, 06 Jul 2025 19:07:40 +0000

With the rise of LLMs and the 'vibe coding' movement, many cool ideas are going from concept to code in days or even hours. I'm all for this creative energy—I've always seen programming as a tool to bring ideas to life. But one thing that concerns me is whether these quickly built apps include proper security measures—especially for protecting sensitive data like user passwords.

If you do not use the right methods for password hashing or if you use outdated hashing methods you risk leaking your customers sensitive information, like their passwords. It's best practice to use a unique password for every site, but most people end up reusing the same one—or small variations of it—because remembering dozens of passwords is nearly impossible without a password manager.

The reality is I am sure that a lot of these vibe coded websites might be littered with software vulnerabilities. That’s just how things are right now—LLMs often don’t provide solutions for the latest versions of a framework. Instead, they usually suggest code based on older versions they were trained on. And if you're relying on an LLM to generate your backend code without explicitly handling password security, it might suggest saving passwords as plain text—introducing a huge security risk.

Today I wanted to share how I implemented Bcrypt hashing on my open-source project N1netails.

What are hashing algorithms and how do they help you with protecting user passwords?

Hashing algorithms are mathematical functions that take an input (or "message") and return a fixed-size string of characters, which is typically a hash. The key properties of cryptographic hashing algorithms are:

Deterministic: The same input always gives the same output.
Fast computation: Quickly produce the hash.
Irreversibility: It’s computationally infeasible to reverse the hash to get the original input.
Collision resistance: It’s hard to find two different inputs that produce the same hash.
Avalanche effect: A small change in input drastically changes the hash output.

How Hashing Helps Protect User Passwords

When users create accounts, you don’t store the password directly. Instead:

You hash the password using a secure algorithm.
Store the hashed value in your database.
During login, hash the password attempt and compare it with the stored hash. This means that even if someone steals your database, they don’t get actual passwords.

To further improve security, we use:

Salts: Random values added to the password before hashing to prevent precomputed attacks (rainbow tables).
Slow hashing: To resist brute-force attacks (e.g., bcrypt, scrypt, Argon2).

MD5 vs Bcrypt

Feature	MD5	Bcrypt
Algorithm Type	Fast cryptographic hash function	Adaptive key derivation function
Designed For	Checksums, not password storage	Secure password hashing
Speed	Extremely fast	Intentionally slow
Salt Support	No (must be added manually)	Built-in
Collision Resistance	Weak (many known collisions)	Strong
Adjustable Cost	No	Yes (`work factor` or `cost`)
Secure?	❌ No	✅ Yes (as of now)

Why MD5 is Bad for Passwords

Fast: Makes brute-force attacks much easier.
No salting by default: Allows precomputed attacks (rainbow tables).
Broken cryptography: Collisions are trivial to generate.
Not designed for passwords: Originally used for checksums (e.g., file integrity).

⚠️ MD5 is considered cryptographically broken and should never be used for passwords.

How I used Bcrypt with Spring Security to hash user passwords before they are saved into the database

Hashing passwords can be tricky if you're trying to implement it from scratch. That’s why I decided to use the existing Spring Security framework and the BCryptPasswordEncoder it provides.

View the source code here:
https://github.com/n1netails/n1netails/blob/v0.2.9/n1netails-api/src/main/java/com/n1netails/n1netails/api/config/ProjectSecurityConfig.java

import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;

...
public class ProjectSecurityConfig {
    private final BCryptPasswordEncoder passwordEncoder;
    ...

    @Bean
    public AuthenticationManager authenticationManagerBean(HttpSecurity http) throws Exception {
        AuthenticationManagerBuilder authenticationManagerBuilder = http.getSharedObject(AuthenticationManagerBuilder.class);
        authenticationManagerBuilder.userDetailsService(userDetailsService).passwordEncoder(passwordEncoder);
        return authenticationManagerBuilder.build();
    }
}

The method above defines a Spring @Bean that provides a custom AuthenticationManager for your application. Here’s what it’s doing under the hood:

🔍 Method Breakdown

@Bean
public AuthenticationManager authenticationManagerBean(HttpSecurity http) throws Exception {

Declares a Spring bean named authenticationManagerBean.
Returns an instance of AuthenticationManager, which is used by Spring Security to authenticate users.
Takes HttpSecurity as a parameter, so it can access shared security configuration.

AuthenticationManagerBuilder authenticationManagerBuilder = 
    http.getSharedObject(AuthenticationManagerBuilder.class);

Retrieves the shared AuthenticationManagerBuilder from the HttpSecurity context.
This builder is used to configure how authentication should work.

authenticationManagerBuilder
    .userDetailsService(userDetailsService)
    .passwordEncoder(passwordEncoder);

userDetailsService(userDetailsService): Tells Spring how to load user information (e.g., from a database).
passwordEncoder(passwordEncoder): Tells Spring how to verify the password (e.g., using BCryptPasswordEncoder).

This configuration links your authentication mechanism to your custom logic.

return authenticationManagerBuilder.build();

Finalizes the configuration and returns a fully built AuthenticationManager bean that will be used by Spring Security to authenticate login attempts.

✅ What This Achieves

You provide a custom way to authenticate users (via your UserDetailsService).
You ensure secure password handling using a specific encoder (e.g., bcrypt).
You expose this AuthenticationManager bean so it can be used in other parts of your app, like a custom login filter or controller.

🔒 Why It's Needed

Spring Security (since version 5.7) recommends defining your own AuthenticationManager bean if you're doing custom authentication, instead of relying on the default global one.

Without this, Spring might not know how to authenticate users, or might not use your desired password encoder.

When used with my SecurityFilterChain the AuthenticationManager bean defined above is automatically injected into the filter chain.

    @Bean
    @Order(SecurityProperties.BASIC_AUTH_ORDER)
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        ...
        http.authorizeHttpRequests(
                auth -> auth
                        .requestMatchers(PUBLIC_URLS).permitAll()
                        .anyRequest().authenticated()
        );

        return http.build();
    }

🔐 The Result

Now users no longer need to worry about their passwords being saved into the database in plain text. The result will now be hashed and will not be useful to hackers if they managed to get into the N1netails database.

You may notice that some users don’t even have passwords. That’s because I added support for passkey-based logins, which you can read more about here:
https://dev.to/shahidfoy/adding-passkey-login-to-my-open-source-project-n1netails-using-yubico-and-webauthn-passkeys-2iae

Sadly after working on my passkey implementation for some time I decided to make passkeys as a secondary login method because I currently do not have a way to validate user emails before sign up which I am planning to implement in the future.

If you're vibe-coding your next side project, I'm rooting for you! Just remember: security matters, especially when you're handling user data.

Cheers, and happy coding!

🚨 Build Better Alerts: Meet N1netails – A Lightweight, Self-Hosted Alerting System

Shahid Foy — Sun, 06 Jul 2025 04:42:54 +0000

Managing alerts across modern applications can quickly get complex—or expensive. Whether you're a solo dev, a small team, or running microservices across environments, you need a tool that just works without locking you into a platform or draining your budget.

That’s why I built N1netails – a developer-first, open-source alerting platform.

🧠 What is N1netails?

N1netails is a self-hosted alerting system designed for developers who want more control and less complexity. Inspired by the simplicity of SLF4J for logging, N1netails lets you send and manage alerts with pluggable integrations and full extensibility.

✅ Built in Java
✅ Send alerts via simple HTTP POST
✅ Works with your existing stack (Spring Boot, Angular, Node, Bash, etc.)
✅ Integrates via n1netails-kuda (Java library) or REST API
✅ Self-hosted and open-source — no vendor lock-in
✅ Lightweight enough to embed in microservices
✅ Supports real-time notification channels like Discord and Telegram

🔧 How It Works

You deploy the N1netails API and N1netails UI and send alerts from your app using the Kuda SDK (or directly via HTTP):

📦 Example: Docker quickstart

If you want to try N1netails out without hosting it yourself you can send posts request to the N1netails Dashboad

Alerts appear on the N1netails dashboard.Here is how to make a post request to N1netails

N1netails Kuda Java SDK
If you are building your services using Java you can use the kuda library to easily send alerts from your app to the N1netails project
N1netails Kuda

💡 Use Cases

Error alerting
Health checks for self-hosted systems
Lightweight incident tracking for indie SaaS
Default exception handler for Java apps (n1netails-kuda)

🛠️ Under the Hood

Java 17
Spring Boot
Angular (for the UI)
RESTful API
Pluggable alert delivery system (n1netails-kuda)

🙌 Contribute or Try It Out

If you’re looking for a clean, hackable, dev-focused alternative to PagerDuty, give n1netails a spin.

⭐ Star the project: github.com/n1netails/n1netails

🛠️ Pull requests and feedback are always welcome!

Built by @shahidfoy with 🔥 and Tea

How to Deploy a Spring Boot and Angular App on DigitalOcean with Docker, Nginx, and HTTPS

Shahid Foy — Fri, 04 Jul 2025 18:33:32 +0000

I have been working a side project called N1netails which is an open-source project that provides practical alerts and monitoring for applications. I wanted to share what I learned on how to deploy my application to DigitalOcean. One thing to note is the project is primarily written in Springboot. Even the UI is an Angular application wrapped inside of Springboot. So if you are deploying an Angular application by itself you will have to modify some of steps for docker compose and nginx. You can view the result of my deployment here N1netails Dashboard.

🌐 N1neTails DigitalOcean Deployment Guide

This guide walks you through setting up the N1neTails application with Docker Compose and configuring Nginx as a reverse proxy on a Digitalocean Ubuntu server.

Table of Contents
- Postgres Database
- Domain or subdomain
- Docker setup
- Nginx setup
- Setup HTTPS with certbot

1. Create Postgres Database

For this implementation I decided to use DigitalOcean to host my Database Cluster.
You can read more about setting up Database Clusters on DigitalOcean here:
https://docs.digitalocean.com/products/databases/postgresql/how-to/create/

DigitalOcean makes it easy to create new users and databases within your cluster.
Steps 1 & 2 can be done on DigitalOcean but are provided in case your database is hosted elsewhere.

Step 1: Create `n1netails` user (can be done on DigitalOcean):

CREATE USER n1netails WITH PASSWORD 'your_password';

Step 2: Create `n1netails` database (can be done on DigitalOcean):

CREATE DATABASE "n1netails"
  WITH
  OWNER = n1netails
  ENCODING = 'UTF8'
  LOCALE_PROVIDER = 'libc'
  CONNECTION LIMIT = -1
  IS_TEMPLATE = False;

Step 3: Grant n1netails user access to n1netails database:

GRANT CREATE ON DATABASE n1netails TO n1netails;

Step 4: Generate `ntail` schema:

CREATE SCHEMA IF NOT EXISTS ntail AUTHORIZATION n1netails;

Step 5: Set timezone to UTC:

ALTER DATABASE n1netails SET timezone TO 'Etc/UTC';

2. Create a Subdomain (e.g., `app.n1netails.com`)

You can set up n1netails using your own domain or subdomain.
You can configure DNS settings where you registered your domain (e.g., Squarespace, GoDaddy, Namecheap).

Add an A Record:

Host: app
Type: A
Value: Your server’s public IP address
TTL: Default (3600)

Save the DNS settings.

📌 It may take a few minutes (or up to 24 hours) for DNS to propagate.

3. Docker Compose Setup

Set up docker compose on ubuntu by following these docs:

Add the following directories within the digital ocean server projects/n1netails

Create a docker-compose.yml file inside of projects/n1netails with the following content:

services:
  api:
    image: shahidfo/n1netails-api:latest
    container_name: n1netails-api
    ports:
      - "9901:9901"
    depends_on:
      liquibase:
        condition: service_completed_successfully
    environment:
      SPRING_PROFILE_ACTIVE: docker
      SPRING_DATASOURCE_URL: jdbc:postgresql://<digital-ocean-postgres-db-url>:<digital-ocean-postgres-db-port>/n1netails
      SPRING_DATASOURCE_USERNAME: n1netails
      SPRING_DATASOURCE_PASSWORD: <n1netails_password>
      N1NETAILS_PASSKEY_RELYING_PARTY_ID: <domain-url> # e.g. app.n1netails.com
      N1NETAILS_PASSKEY_ORIGINS: https://<domain-url> # e.g. https://app.n1netails.com
      OPENAI_ENABLED: true
      OPENAI_API_KEY: <your_openai_api_key>
      OPENAI_API_URL: https://api.openai.com

  ui:
    image: shahidfo/n1netails-ui:latest
    container_name: n1netails-ui
    ports:
      - "9900:9900"
    depends_on:
      - api
    environment:
      SPRING_PROFILE_ACTIVE: docker
      API_BASE_URL: https://<domain-url>
      OPENAI_ENABLED: true

  liquibase:
    image: shahidfo/n1netails-liquibase:latest
    container_name: n1netails-liquibase
    environment:
      SPRING_PROFILE_ACTIVE: docker
      SPRING_DATASOURCE_URL: jdbc:postgresql://<digital-ocean-postgres-db-url>:<digital-ocean-postgres-db-port>/n1netails
      SPRING_DATASOURCE_USERNAME: n1netails
      SPRING_DATASOURCE_PASSWORD: <n1netails_password>

Prepare Docker Compose with above config and deploy:

# Stop and remove old containers
docker compose down -v

# Start containers in detached mode
docker compose up -d

# tail docker logs (optional)
docker compose logs -f

4. Nginx Setup

Step 1: Install Nginx on your server if not installed:

# Update the package list to ensure you get the latest available versions
sudo apt update

# Install the Nginx web server
sudo apt install nginx

Step 2: Create the Nginx config file

Create the file /etc/nginx/sites-available/n1netails.conf with the following content:

server {
    listen 80;
    server_name <domain-url>;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    add_header X-XSS-Protection "1; mode=block";

    # Route API calls to backend
    location /ninetails/ {
        proxy_pass http://localhost:9901/ninetails/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Route OpenAPI config (Swagger needs this)
    location /v3/ {
        proxy_pass http://localhost:9901/v3/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Route Swagger UI to backend
    location /swagger-ui/ {
        proxy_pass http://localhost:9901/swagger-ui/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Route all other requests to frontend
    location / {
        proxy_pass http://localhost:9900/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Step 3: Enable the site and disable default

# Enable the new site
sudo ln -s /etc/nginx/sites-available/n1netails.conf /etc/nginx/sites-enabled/n1netails.conf

# Disable the default site
sudo rm /etc/nginx/sites-enabled/default

Step 4: Test and reload Nginx

# Test the Nginx configuration for syntax errors
sudo nginx -t

# Reload Nginx to apply the new configuration without downtime
sudo systemctl reload nginx

# Check nginx logs
sudo tail -f /var/log/nginx/error.log

5. Install Certbot & Enable HTTPS

# Update packages
sudo apt update

# Install Certbot and Nginx plugin
sudo apt install certbot python3-certbot-nginx

Then run:

# Automatically obtain and configure SSL
sudo certbot --nginx

Follow the prompts:

Choose your subdomain (e.g., app.n1netails.com)
Redirect HTTP to HTTPS when prompted ✅

✅ You now have HTTPS enabled.

Step 1: Verify HTTPS

Visit:

Visit your domain to varify https

Example

https://app.n1netails.com

Check for the padlock icon in the address bar.

Step 2: Enable SSL Certificate Auto-Renewal

Let’s Encrypt certificates expire every 90 days. Certbot sets up a systemd timer automatically.

Verify with:

systemctl list-timers | grep certbot

Test the renewal process:

sudo certbot renew --dry-run

Adding Passkey Login to My Open Source Project n1netails Using Yubico and WebAuthn

Shahid Foy — Thu, 03 Jul 2025 00:14:10 +0000

Passwords suck.

They're reused, guessed, phished, and forgotten. So for my open-source alerting platform n1netails, I wanted something better—passkey authentication.

🔐 Why Passkeys?

Passkeys are the modern answer to broken password security. They’re based on WebAuthn, a W3C and FIDO standard that uses public-key cryptography instead of secrets.

Here's what makes passkeys powerful:

Phishing-resistant – There's no shared secret to steal, so attackers can't trick users into giving up credentials.
Device-native – Built into OS-level authenticators like Face ID, Touch ID, PIN, Windows Hello, etc.
User-friendly – One tap or face scan instead of typing a password.
Cross-device sync – Platforms like Apple and Google sync passkeys across your devices using end-to-end encryption.
No server-side secrets – Even if your database is compromised, passkey-based credentials can’t be reused or reverse-engineered.

🧠 How Passkeys Actually Work (Under the Hood)

Here’s a quick breakdown of the passkey flow from a technical perspective:

🔐 Registration (Creating a Passkey)

The server generates a challenge (random data) and sends it to the browser.
The browser asks the user to verify themselves using a platform authenticator (e.g., biometric or device PIN).
If verified, the authenticator creates a new key pair (public/private keys).
The public key is sent to the server and stored alongside a unique credential ID.
The private key remains securely stored in the device and never leaves it.

🔑 Authentication (Logging In)

The server generates a new challenge and asks the browser to authenticate.
The browser prompts the user to verify with their platform authenticator.
The private key on the device signs the challenge.
The browser sends this signed challenge, along with the credential ID, back to the server.
The server verifies the signature using the stored public key.

If the signature is valid, the user is authenticated.

📱 What This Means for Developers

No password hashing or resets
No secret storage headaches
Improved security and UX out of the box

Passkeys can be used as a primary or secondary authentication factor. In my project, I'm using them as a secondary login option.

🚨 About the Project: n1netails

N1netails is a self-hosted, developer-friendly alerting platform designed to be embedded or run independently—think lightweight, programmable PagerDuty.

I’ve been building this as a way to learn and explore:

Clean architecture in Springboot
Real-time alerts via APIs
Secure self-hosting with modern auth like passkeys

🔧 How I Implemented Passkeys (WebAuthn)

To implement passkeys, I used the Yubico WebAuthn Server library along with Google Jules as my peer programming buddy. Since I don't yet have email validation set up in the project, I decided to only allow registered users to generate passkeys. Here's a simplified breakdown of the approach:

Registration Flow
- An existing user chooses to register a passkey.
- The backend generates a WebAuthn challenge using Yubico's server libraries.
- The client (browser) handles the platform authenticator (Face ID, Touch ID, PIN, Windows Hello, etc.).
- The resulting credential is verified and stored.
Login Flow
- The server issues a challenge.
- The client authenticates using a previously registered passkey.
- The server validates the signature and logs the user in.

The Yubico library took care of most of the protocol details like challenge generation, signature validation, and credential parsing.

📁 Code and Examples

You can view the source code and passkey implementation here:

👉 GitHub - n1netails passkey implementation

Relevant components include:

N1ntails Liquibase - Generate PasskeyCredentials table Create table passkey credentials
N1netails API - POM Dependencies Yubico Webauthn Dependencies
N1netails API - Passkey Data Transfer Objects (DTO) Passkey DTO's
N1netails API - Registration and login controllers Passkey Controller
N1netails API - Integration with session-based login system Passkey Service
N1netails API - Saving passkey data in the database Passkey Credential Repository
N1netails API - Yubico credential repository helper Yubico Credential Repository
N1netails UI - Passkey service Angular passkey service
N1netails UI - Edit profile register passkey Start passkey Registration
N1netails UI - Login user with passkey Login with passkey

🚀 Final Thoughts

Passkeys aren’t the future—they’re now. If you’re building a product where security and usability matter, adding WebAuthn is well worth it. Using Google Jules as my peer programming buddy helped me get started, but it didn’t work completely out of the box. I had to tweak the database schema and refactor parts of the Passkey service and repository layers to get it working properly. If you are using Passkeys with email it is probably a good idea to make sure the user can validate their email before generating a passkey.

n1netails is still in its early stages, but you can:

⭐ Star the repo: Github N1netails
📄 Read the docs: n1netails.com
💬 Try it out and share feedback!

Forem: Shahid Foy

How to Send Discord Webhook Alerts in Java (Spring Boot Example)

Why Send Alerts to Discord from Java?

Step 1: Add the Dependency

Maven

Gradle

Step 2: Configure in Spring Boot

Step 3: Send a Basic Discord Webhook Message in Java

Sending a Detailed Discord Embed Alert (Production Example)

When Should You Use Discord Webhooks in Spring Boot?

Final Thoughts

Build a Telegram Bot in Java with the N1netails Telegram Client

What is N1netails Telegram Client?

Step 1 - Set Up Telegram

Install Telegram

Create Your Telegram Bot

1. Talk to BotFather

2. Create a new bot

3. Save your bot token

4. Add the bot to a chat

5. Get the chat ID

Step 2 - Install the Library

Maven

Gradle

Step 3 - Configuration

Spring Boot Setup

Plain Java Setup

Step 4 - Sending Messages

Simple Text Message

GIF Message

CTA Button Message

Image Message

Video Message

Media Group (Images + Videos)

Important Notes

Why Use This Client?

Final Thoughts

How I Used Google Jules to Implement Google OAuth2 in My Spring Boot + Angular Application

🔐 Google OAuth2 in Spring Boot

OAuth2 Configuration (application-oauth.yml)

🔄 OAuth2 Success Handler

🧩 Google Login Service Logic

🖥️ Google Login on the Angular Frontend

Angular Login Method

📌 Full Pull Request

⭐ Final Thoughts

📨 Mocking Emails in a Spring Boot App Using MailHog – How I Integrated Email Testing into N1netails

🔧 What is MailHog and Why Use It in a Spring Boot Project?

🚀 Step-by-Step: How to Use MailHog with Spring Boot

1. Install MailHog

Option A: Binary Download

Option B: Go

Option C: Docker (Recommended)

2. Run MailHog

3. Configure Spring Boot to Use MailHog

4. Trigger an Email

5. Preview Emails in the Web UI

🛠️ How N1netails Uses Email Templates (Spring Boot + Liquibase)

📥 SQL Table for Templates

🎨 HTML Welcome & Alert Email Templates

🧬 Spring Boot Code for Sending Emails in N1netails

✅ Summary

How I Implemented GitHub OAuth2 into My Spring Boot + Angular App N1netails

Setting Up a GitHub OAuth2 App

The OAuth2 Flow (Spring Boot + Angular)

1. GitHub Login Button in Angular

2. Backend: Spring Boot OAuth2 Configuration

3. Handling the OAuth2 Login in Backend

4. Updating the User Entity

5. Updating the Repository

6. Redirecting Back to Angular After Successful OAuth2 Login

7. Angular: Capturing the JWT Token

8. Getting the Authenticated User

Wrap-Up and Improvements

Fixing OutOfMemoryError in Spring Boot: Implementing Pagination (With Angular Example)

What is pagination?

Implementing pagination in my Spring Boot application

1. Create a PageRequest POJO

2. Update the Repository

3. Update the Service Layer

1. Create a `PageRequest` POJO

Step 1: Create `n1netails` user (can be done on DigitalOcean):

Step 2: Create `n1netails` database (can be done on DigitalOcean):

Step 4: Generate `ntail` schema:

2. Create a Subdomain (e.g., `app.n1netails.com`)