Before diving in, here's a quick summary of what this stack gives you:

• No ads or trackers: blocks all ads and trackers at the DNS level across every devices even when you are not in home.

• Remote access to all devices: reach any device or service privately from anywhere, without exposing anything to the public internet.

• Custom DNS rewrites: use clean local domains like paperless.home, grafana.lan or router.local instead of raw IP:ports.

• This is just about how everything works together, not a setup guide don't worry if you need a download it here

How the Stack Fits Together

• Tailscale creates the encrypted tunnel that connects your devices securely.

• AdGuard Home handles DNS resolution, ad blocking, and custom domain rewrites.

• Nginx Proxy Manager routes incoming requests to the right service and issues SSL certificates automatically.

Together, they give you a clean, private network that works from anywhere — with no public exposure.

1. Tailscale

• Tailscale is a mesh VPN built on the WireGuard protocol. It creates encrypted, peer-to-peer tunnels between your devices.

• Unlike traditional VPNs that route all traffic through a central server, Tailscale connects devices directly to each other whenever possible, giving you low-latency, high-performance private networking.

• Instead of exposing services directly to the internet or configuring complicated port forwarding rules, Tailscale allows devices to communicate securely over encrypted tunnels.

Why Use TailScale

• Remote Access: Access your home network from anywhere without port forwarding or exposing services to the public internet

• Cross-Platform: Works on Linux, Windows, macOS, iOS, and Android

• Tailnet: Automatically creates a private network with all your devices

• MagicDNS: dedicated custom domain will be provided.

• Global DNS Control: Set a single DNS server for all connected devices. Point it to our AdGuard Home and every device instantly gets ad blocking and custom domains.

Use Case: Private Access to Self-Hosted Services

Instead of exposing apps to the public internet using services like ngrok or Cloudflare Tunnel:

# Public (exposed, risky)
https://myserver.example.com

You can access them privately through Tailscale:

# Via Tailscale IP
http://100.x.x.x:8080

# Via MagicDNS hostname
http://devicename.tailnet-name.ts.net:8080

# Via custom domain (with AdGuard + NPM — covered below)
http://plex.home

This dramatically reduces your attack surface while keeping everything accessible from your phone, laptop, or any other enrolled device — anywhere in the world.

2. Adgaurd Home

AdGuard Home is a network-wide ad blocker and DNS resolver. Rather than blocking ads in a browser, it blocks them at the DNS level meaning when any device on your network tries to resolve a tracker or ad domain, AdGuard simply returns nothing. The request never leaves your network.

Why Use AdGuard?

• Reduce Telemetry: Many devices (Windows, smart appliances) send telemetry data home. Block these at the DNS level to reduce data leakage.

• Privacy Protection: Block trackers across all devices (phones, laptops, smart TVs) by not using ISP default resolvers.

• No Client Software: Works at the DNS level — no installation needed on individual devices

• Custom Blocklists: Add your own domains or use community blocklists

• Adult Content Filtering: Family-safe DNS options

• Statistics: See what domains are being queried on your network

• DNS rewriting: assign custom domain for rules.

DNS Rewrites

This is what makes the whole stack elegant. In AdGuard Home, you can create DNS rewrite rules like:

paperless.home  →  100.x.x.x   (your server's Tailscale IP)
grafana.home    →  100.x.x.x
portainer.home  →  100.x.x.x

Now, when you type https://paperless.home on any device connected to Tailscale (with AdGuard set as the DNS), it resolves to your server's private IP. NPM then handles routing that request to the right container.

3. Nginx Proxy Manager(NPM)

Nginx Proxy Manager provides a clean web UI for managing Nginx reverse proxy configurations. Instead of writing Nginx config files by hand, you point and click NPM handles SSL certificates, redirects, and proxy rules automatically.

How It Works with the Stack

NPM sits between AdGuard and your actual services. When a request arrives for paperless.home:

1. AdGuard resolves paperless.home → your server's Tailscale IP.

2. The request hits NPM on port 80(http)/443(https).

3. NPM reads the hostname, finds the matching proxy host, and forwards the request to the right Docker container (e.g., paperless-ngx:8000).

4. NPM handles the SSL termination, so your browser gets a valid HTTPS connection.

To build this setup, all you really need is:

• A Linux machine (old PC, mini PC, or VPS)

• Docker

• A bit of patience

• And honestly… ChatGPT helps a lot.

If you want the complete step-by-step setup guide with configuration examples, networking flow, DNS rewrites, and reverse proxy setup:

• Download Guide (Direct)

• Mirror Download

• Create a new Spring Boot project from scratch

• Understand the basic structure of a Spring Boot application

• Set up a persistent in-memory database (H2)

• Write and run basic SQL queries to manipulate data

• Call your API endpoints to interact with the application

Prerequisites

• Basic Kotlin or Java understanding (classes and objects)

• REST API basics understanding

• Familiarity with SQL SELECT commands and conditions

• IntelliJ IDEA or Android Studio (both are essentially the same)

• API Client: Postman (standard choice) or Bruno (open-source alternative)

• Checkout my github for full source code.

Initialize Project

The easiest way to bootstrap your Spring Boot (Kotlin) application is by using the official Spring Initializer.

We are going to create a TODO list back-end.

Go to start.spring.io.

Choose the following configuration as shown above:

• Dependencies:

  1. Spring Web — RESTful API support

  2. H2 Database — In-memory database (no external database required)

  3. Spring Data JPA — Data manipulation library for database operations

Click the Generate button to download a zip file. Extract the contents to your project folder and open it in your IDE.

Final Check

After importing the folder into your IDE, verify that you've configured the Java version to match the one you selected in Spring Initializer:

1. File → Project Structure → Project → SDK

2. File → Settings → Build Tools → Gradle → Gradle JVM

classDiagram
direction TB

%% =======================
%% Application Root
%% =======================
class TodoApplicationKt {
  + main(String[]) Unit
}

%% =======================
%% Controller Layer
%% =======================
class ToDoController {
  + ToDoController(ToDoRepository)
  + create(ToDo) ToDo
  + completeTask() List~ToDo~
  + pendingTask() List~ToDo~
  + patch(Long, ToDoPatch) ToDo
  + delete(Long) Unit
  + deleteAll() String
  + deleteById(ToDoBulkDelete) String
  ---
  List~ToDo~ all
  List~ToDo~ sortedTodos
}

%% =======================
%% Repository Layer
%% =======================
class ToDoRepository {
  <<interface>>
  + completedTask() List~ToDo~
  + sortAllByDateAndTime() List~ToDo~
  + bulkDeleteById(List~Long~) Int
  + pendingTask() List~ToDo~
  + deleteAllTodos() Int
}

%% =======================
%% Data / DTOs
%% =======================
class ToDo {
  + ToDo(Long, String, LocalDate, LocalTime?, Boolean, LocalDate?)
  ---
  LocalDate date
  LocalTime? time
  String title
  LocalDate? completedDate
  Long id
  Boolean completed
}

class ToDoBulkDelete {
  + ToDoBulkDelete(List~Long~)
  ---
  List~Long~ ids
}

class ToDoPatch {
  + ToDoPatch(LocalDate?, LocalTime?, String?, Boolean?)
  + ToDoPatch()
  ---
  LocalDate? date
  LocalTime? time
  String? title
  Boolean? completed
}

%% =======================
%% Relationships
%% =======================
ToDoController --> ToDoRepository : uses
ToDoController --> ToDoPatch : input
ToDoController --> ToDoBulkDelete : input
ToDoController --> ToDo : returns

Project Structure

Data Object Creation

Object

A data class that contains the following task attributes:

• id — Auto-incrementing identifier

• title — Task name

• date — Task due date

• time — Task due time (optional)

• completed — Status (boolean: completed or not)

• completedDate — Date when the task was completed

//ToDo.kt
-----------------------------------------------------------------------------------------
@jakarta.persistence.Entity
data class ToDo(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0,
    var title: String,
    @JsonFormat(pattern = "yyyy-MM-dd")
    var date: java.time.LocalDate = java.time.LocalDate.now(), // Default due date is today
    @JsonFormat(pattern = "HH:mm")
    var time : java.time.LocalTime? = null,
    var completed: Boolean = false,
    var completedDate: java.time.LocalDate? = null,
)

Explanation:

• @Entity — Marks this class as a JPA entity, mapping it to a database table

• @Id — Designates the primary key field

• @GeneratedValue — Configures automatic ID generation using the database's identity column

• @JsonFormat — Specifies the JSON serialization format for date and time fields

Repository

//ToDoRepository.kt
------------------------------------------------------------------------------------------
@Repository
interface ToDoRepository : JpaRepository<ToDo, Long> {
    @Query(
        value = "SELECT * FROM to_do ORDER BY date ASC, time ASC",
        nativeQuery = true
    )
    fun SortAllbyDateAndTime(): List<ToDo>

    @Query(
        value = "SELECT * FROM to_do WHERE completed=true ORDER BY date ASC, time ASC",
        nativeQuery = true
    )
    fun Completedtsk(): List<ToDo>

    @Query(
        value = "SELECT * FROM to_do WHERE completed=false ORDER BY date ASC, time ASC",
        nativeQuery = true
    )
    fun PendingTask(): List<ToDo>

    @Modifying
    @Transactional
    @Query(
        value = "DELETE FROM to_do",
        nativeQuery = true
    )
    fun deleteAllTodos() : Int

    @Modifying
    @Transactional
    @Query(
        value = "DELETE FROM to_do WHERE id IN (:id)",
        nativeQuery = true
    )
    fun BulkDeleteById(id: List<Long>) : Int
}

Explanation:

• ToDoRepository extends JpaRepository — This inheritance grants automatic access to powerful CRUD operations including findAll(), save(), delete(), findById(), count(), and many more without writing any implementation code

• JpaRepository<ToDo, Long> — Takes two generic type parameters: first is the entity class (ToDo) you want to manage, and second is the data type of the entity's primary key (Long in our case)

• @Query — Enables you to write custom native SQL queries or JPQL queries and bind them to repository method declarations

• @Modifying and @Transactional — Required pair of annotations for any query that performs INSERT, UPDATE, or DELETE operations to ensure proper transaction management and data consistency

REST Controller

//ToDocontroller.kt
--------------------------------------------------------------------------------------------
@RestController
@CrossOrigin(origins = ["*"])
@RequestMapping("/")
class ToDoController(private val repo : ToDoRepository) {

    @GetMapping
    fun getAll() : List<ToDo> = repo.findAll()

    @PostMapping
    fun create(@RequestBody toDo: ToDo): ToDo {
        return repo.save(toDo)
    }


    @PatchMapping("/{id}")
    fun patch(@PathVariable id: Long, @RequestBody body: ToDoPatch): ToDo {
    val todo = repo.findById(id).orElseThrow()

    body.title?.let { todo.title = it }
    body.date?.let { todo.date = it }
    body.time?.let { todo.time = it }

    body.completed?.let { newValue ->
        if (!todo.completed && newValue) todo.completedDate = LocalDate.now()
        if (todo.completed && !newValue) todo.completedDate = null
        todo.completed = newValue
    }

    return repo.save(todo)
}

    @DeleteMapping("/{id}")
    fun delete(@PathVariable id: Long) {
        repo.deleteById(id)
    }

    // Get all todos sorted by date and time
    @GetMapping("/bytime")
    fun getSortedTodos() : List<ToDo> = repo.SortAllbyDateAndTime()

    // Get todos grouped by status (incomplete first, then completed)
    @GetMapping("/completed")
    fun completeTask() : List<ToDo> = repo.Completedtsk()

    @GetMapping("/pending")
    fun pendingTask() : List<ToDo> = repo.PendingTask()

    @DeleteMapping("/deleteall")
    fun deleteAll(): String {
        val deletecount = repo.deleteAllTodos()
        return "$deletecount todos deleted"
    }

    @DeleteMapping("/bulkdelete")
    fun deleteById(@RequestBody body: ToDoBulkDelete): String {
        val deleteCount = repo.BulkDeleteById(body.ids)
        return "$deleteCount deleted"
    }
}

Explanation:

Class-Level Annotations:

• @RestController — Combines @Controller and @ResponseBody, indicating this class handles HTTP requests and returns JSON responses automatically

• @CrossOrigin — Enables Cross-Origin Resource Sharing (CORS), allowing requests from any origin (use specific origins in production)

• @RequestMapping("/") — Sets the base URL path for all endpoints in this controller (root path in this case)

HTTP Method Annotations:

• @GetMapping — Handles HTTP GET requests (retrieve data)

• @PostMapping — Handles HTTP POST requests (create new resources)

• @PatchMapping — Handles HTTP PATCH requests (partial updates)

• @DeleteMapping — Handles HTTP DELETE requests (remove resources)

Parameter Annotations:

• @PathVariable — Extracts values from the URL path (e.g., /delete/5 → id = 5)

• @RequestBody — Maps the HTTP request body (JSON) to a Kotlin object automatically

Endpoint Breakdown:

• getAll() — Returns all todos using the built-in findAll() method

• create() — Accepts a ToDo object and saves it to the database

• patch() — Updates specific fields of an existing todo; uses Kotlin's ?.let to update only non-null fields

• delete() — Removes a single todo by ID

• getSortedTodos() — Returns todos ordered by date and time

• completeTask() / pendingTask() — Filters todos by completion status

• deleteAll() — Removes all todos and returns the count

• deleteById() — Bulk deletion of multiple todos by their IDs

DTO (Data Transfer Object)

Explanation

DTOs are lightweight data structures that transfer specific data between client and server without exposing the entire entity. They enable partial updates (sending only fields to modify), controlled data exposure (hiding sensitive fields), and security (preventing modification of immutable fields like id). Each operation can have its own DTO, making the API clearer and more flexible.

DTO Implementations:

ToDoPatch — Used for partial updates via PATCH requests. All fields are nullable, allowing clients to update only the fields they specify:

data class ToDoPatch(
    val date: LocalDate? = null,
    val time: LocalTime? = null,
    val title: String? = null,
    val completed: Boolean? = null
)

ToDoBulkDelete — Used for bulk deletion operations, accepting a list of IDs to delete multiple todos in a single request:

data class ToDoBulkDelete(
    val ids: List<Long>
)

By using these DTOs, the API remains flexible, secure, and easy to understand for developers consuming it.

Application Configuration

application.properties

Configure your Spring Boot application by creating or editing the application.properties file in the src/main/resources directory:

# Application name
spring.application.name=todo

# Server port (default is 8080)
server.port=8080

# H2 Database configuration - File-based for data persistence
# Data persists even after server restart in ./data/todo-db directory
spring.datasource.url=jdbc:h2:file:./data/todo-db;AUTO_SERVER=TRUE;DB_CLOSE_DELAY=-1

# Database credentials (empty for H2 default)
spring.datasource.username=
spring.datasource.password=

# Database driver
spring.datasource.driver-class-name=org.h2.Driver
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect

# JPA/Hibernate configuration
# 'update' automatically creates/updates tables based on entity classes
spring.jpa.hibernate.ddl-auto=update

# Enable SQL query logging in console (useful for debugging)
spring.jpa.show-sql=true

# H2 Web Console configuration
# Access at: http://localhost:8080/h2
spring.h2.console.enabled=true
spring.h2.console.path=/h2

Key Configuration Explained:

• server.port — Defines which port the application runs on (default: 8080)

• spring.datasource.url — Uses file-based H2 database for persistence; data survives server restarts

• spring.jpa.hibernate.ddl-auto=update — Automatically creates or updates database schema based on entity classes

• spring.h2.console.enabled=true — Enables web-based database console for direct SQL queries and table inspection

• spring.jpa.show-sql=true — Logs all SQL statements to console, helpful for learning and debugging

Running Your Application

Start the Application

There are multiple ways to run your Spring Boot application:

Method 1: Using IDE (Recommended for Beginners)

1. Locate the main application file (usually named TodoApplication.kt)

2. Look for the main() function with @SpringBootApplication annotation

3. Click the green Run button (▶️) next to the main function or class name

4. Alternatively, right-click on the file and select Run 'TodoApplicationKt'

   

Method 2: Using Gradle (Command Line)

Open the terminal in your project root directory and run:

./gradlew bootRun

For Windows:

gradlew.bat bootRun

Method 3: Using the Gradle Task Panel

1. Open the Gradle panel on the right side of your IDE

2. Navigate to Tasks → application

3. Double-click on bootRun

Verify the Application is Running

Once the application starts, you should see console output similar to this:

Tomcat started on port(s): 8080 (http)
Started TodoApplicationKt in X.XXX seconds

Quick Health Check

Open your browser and navigate to:

• API Base URL: http://localhost:8080/

• H2 Console: http://localhost:8080/h2

If you see a JSON response (likely an empty array []) at the base URL, your application is running successfully!

Accessing the H2 Database Console

1. Open your browser and go to http://localhost:8080/h2

2. Enter the following connection details:

   • JDBC URL: jdbc:h2:file:./data/todo-db

   • User Name: (leave empty)

   • Password: (leave empty)

3. Click Connect

You can now run SQL queries directly to view your TO_DO table and inspect the data.

Stopping the Application

• In IDE: Click the red Stop button **** in the Run panel

• In Terminal: Press Ctrl + C

Testing Your API

Now that your application is running, let's test all the endpoints using Postman or Bruno. Make sure your server is running on http://localhost:8080.

1. Create a Todo (POST)

Endpoint: POST http://localhost:8080/

2. Get All Todos (GET)

Endpoint: GET http://localhost:8080/

Expected Response (200 OK):

3. Get Todos Sorted by Date and Time (GET)

Endpoint: GET http://localhost:8080/bytime

Returns all todos ordered by date and time (earliest first).

4. Get Pending Todos (GET)

Endpoint: GET http://localhost:8080/pending

Returns only incomplete todos (completed: false).

5. Get Completed Todos (GET)

Endpoint: GET http://localhost:8080/completed

Returns only completed todos (completed: true).

6. Update a Todo (PATCH)

Endpoint: PATCH http://localhost:8080/1

Request Body (JSON): (Include only fields you want to update)

{
  "completed": true,
  "title": "Completed Spring Boot Tutorial"
}

Expected Response (200 OK):

{
  "id": 1,
  "title": "Completed Spring Boot Tutorial",
  "date": "2025-12-01",
  "time": "14:30",
  "completed": true,
  "completedDate": "2025-11-30"
}

7. Delete a Single Todo (DELETE)

Endpoint: DELETE http://localhost:8080/1

Expected Response: 200 OK (no content)

8. Bulk Delete Todos (DELETE)

Endpoint: DELETE http://localhost:8080/bulkdelete

Request Body (JSON):

{
  "ids": [1, 2, 3]
}

Expected Response:

"3 deleted"

9. Delete All Todos (DELETE)

Endpoint: DELETE http://localhost:8080/deleteall

Expected Response:

"5 todos deleted"

Testing Tips

1. Test in Order: Start with POST to create data, then test GET, PATCH, and DELETE operations

2. Check H2 Console: After each operation, verify changes in the database console (http://localhost:8080/h2)

3. View Logs: Watch the console for SQL queries if spring.jpa.show-sql=true is enabled

4. Use Collections: In Postman/Bruno, organize these requests in a collection for easy testing

Next Steps & Improvements

Congratulations on building your first Spring Boot REST API! Here are ways to take it further:

• Input Validation — Add @NotBlank, @Size, and @Valid annotations to ensure data integrity

• Error Handling — Implement @ControllerAdvice for global exception handling with proper HTTP status codes

• Production Database — Migrate from H2 to PostgreSQL, MySQL or MongoDB for production use

• User Management — Add User entity with relationships to todos for multi-user support

• Security — Add Spring Security with JWT authentication and role-based access control

• API Documentation — Integrate Swagger/OpenAPI for interactive API documentation

Conclusion

You've successfully built a fully functional Spring Boot REST API with Kotlin! You learned to create entities, repositories, controllers, configure databases, and test endpoints.

thanks for reading, if you have any suggestion don’t hesitate to contact me.