After deciding to build my own NestJS StarterKit, the first challenge was to design a core architecture that actually deserves to be called a “starter.” Not just a bunch of boilerplate folders, but a structure that could grow with real-world projects, from early MVPs to production-grade systems.

At my last job, I worked at a software house that delivered a lot of client projects. Each new project started with the same conversation:

“Should we copy the last repo again?”

That’s the problem I want to solve, to create a starter that’s modular, maintainable, and easy to extend. This article walks through how I designed the core architecture of that StarterKit.

Architectural Goals

Before touching any line of code, I wrote down a few non-negotiables for the architecture:

1. Fast to start — a new MVP should be bootstrapped in minutes.

2. Modular and scalable — each domain should live independently, but still play nicely with others.

3. Developer-friendly — clear conventions, minimal surprises.

4. No vendor lock-in — I want to own the stack, not depend on third-party auth or config systems.

5. Extendable without refactor hell — adding a feature shouldn’t break existing modules.

These goals shape every decision in the StarterKit, from folder naming to dependency design.

Core Design Principles

There are three big ideas behind the architecture:

• Domain-driven modular structure
  Each domain (like user, auth, post, etc.) lives as its own NestJS module — fully self-contained, with its own entities, DTOs, and services.

• Convention over configuration
  The StarterKit uses opinionated patterns (like where to put guards, filters, or repositories) so developers spend less time deciding and more time building.

• DIY-first, vendor-second
  Instead of relying on services like Clerk or Auth0, I implement our own auth, config, and persistence layers, flexible and portable.

Folder & Module Structure

Here’s the project skeleton at a glance:

src/
├── common/
│   ├── dtos/
│   ├── interceptors/
│   ├── helpers/
│   └── ...
├── config/
│   ├── app.config.ts
│   └── ...
├── lib/
│   ├── prisma/
│   └── ...
├── modules/
│   ├── auth/
│   ├── user/
│   └── ...
├── app.module.ts
└── main.ts

common/ folder holds global concerns and reusable building blocks that are not tied to any specific domain. Think of it as your project’s toolbox.
config/ all configuration logic lives here, not scattered in .env calls across the app.
lib/ folder is for wrapping third-party libraries or SDKs so they integrate cleanly into Nest’s DI ecosystem.
modules/ contains all business domains. Each one can live independently or be plugged into other projects.

This separation helps maintain domain isolation: the auth module shouldn’t need to know about user, and vice versa. It also simplifies testing, you can load only the module you’re working on.

Key Architectural Components

Here’s what makes up the “core” of the StarterKit:

1. Config Module

Centralized environment management, with schema validation.
Everything reads from a single source of truth, no magic process.env calls scattered around.

2. Prisma Module

Instead of wrapping Prisma behind a custom repository layer, the StarterKit uses Prisma directly through a dedicated PrismaModule located under lib/prisma.

This keeps things simple and closer to how Prisma is designed to be used, strongly typed, auto-generated, and efficient.
Every domain service can inject PrismaService directly for database access, benefiting from full TypeScript type safety and autocomplete on every query.

3. Common Utilities

Contains:

• Global interceptors and filters (logging, error handling)

• Custom pipes and decorators

• Shared exceptions and response wrappers

They keep the app consistent and predictable across modules.

4. Modules — the heart of the StarterKit

Every business domain in the StarterKit lives inside its own NestJS module under the modules/ directory.
This is where the actual business logic resides, the features that make your app what it is.

A typical domain module looks like this:

src/modules/user/
├── user.controller.ts
├── user.service.ts
├── user.module.ts
└── dto/
    ├── create-user.dto.ts
    └── update-user.dto.ts

Each module is self-contained and follows the same conventions:

• Controller handles HTTP requests, validation, and routing.

• Service contains the domain logic and interacts with Prisma or external services.

• DTOs define the input/output contracts.

• Module file (*.module.ts) wires everything together and exports what other modules may need.

The philosophy is simple:

“Each domain owns its data, logic, and contracts — no shared global state.”

This modular layout makes it easy to:

• Add or remove features without breaking unrelated parts of the system.

• Scale horizontally — you can later extract a module into its own microservice if needed.

• Keep team boundaries clear — each developer or squad can own a module independently.

5. AppModule as Composition Root

AppModule ties everything together.
It imports core modules, registers global providers, and bootstraps the dependency graph.

Design Alternatives I Considered

I actually explored three different paths before landing here:

1. Monolithic structure
   ✅ Simple to start, but scales poorly.
   ❌ Changes in one area can ripple everywhere.

2. Microservices
   ✅ Great isolation, clear boundaries.
   ❌ Overkill for early MVPs; too much infra overhead.

3. Modular monolith (chosen)
   ✅ Keeps isolation and simplicity.
   ✅ Easy to scale horizontally later.
   ❌ Requires clear boundaries discipline, but that’s a good thing.

In terms of architecture pattern, I leaned toward a Clean Architecture style, but not dogmatically, just enough layering to keep things tidy without abstraction fatigue.

Developer Experience

Architecture isn’t just about structure; it’s about how it feels to build with it.

• Built-in CLI scripts to scaffold modules quickly.

• Opinionated ESLint, Prettier, and commit hooks.

• Strict TypeScript setup for safer refactors.

• Auto-registration for common NestJS decorators.

The goal: new developers can clone, pnpm start:dev, and start shipping features, no setup pain.

What’s Next

The next step after architecture is to tackle Authentication.
In the next article “Building the Auth Module” . I’ll explain how I implemented a flexible auth flow with JWT, refresh tokens, and optional social login, all built on top of this core architecture.

Closing Thoughts

Good architecture isn’t about complexity, it’s about clarity.
When the system’s design reflects how you think about your problem domain, everything else becomes easier: refactoring, testing, even onboarding new devs.

This StarterKit is still evolving, but its foundation feels solid, simple enough for small projects, yet robust enough to grow into something much bigger.

Over the years, I’ve built and maintained quite a few backend projects. Some started from scratch, others from templates, and a few evolved from messy prototypes that somehow made it to production. One thing kept repeating: every new project meant doing the same setup again and again.

1. Setting up configs.

2. Setting up authentication.

3. Integrating Prisma.

4. Structuring modules.

5. Defining error handling, logging, and response formats.

At my last job, I actually built something similar, an internal SkeletonKit for the company’s software house projects. It was designed to standardize backend development across multiple client applications and help the team move faster when starting new services. But that project was strictly for internal use, customized for the company’s stack and business needs.

This time, I wanted to build something that goes beyond work. Something open, flexible, and accessible to anyone who loves building scalable backends.

That’s when I decided to create the NestJS MVP StarterKit, my own open-source foundation for real-world applications.

The Problem with Existing Starter Kits

There are many NestJS starter projects out there, and some of them are great. But most of them live at one of two extremes.

1. Too minimal, basically a fresh NestJS install with a few renamed folders.

2. Too opinionated, forcing you to follow someone else’s architecture or tools.

They often look nice on GitHub, but once you try to use them for a real project, things start falling apart.

Common issues I’ve seen:

• Folder structures that don’t scale well.

• Missing modular design and clear domain boundaries.

• Reliance on third-party auth like Auth0 or Clerk that creates vendor lock.

• Outdated dependencies and inconsistent patterns.

• A focus on “getting started fast” instead of “staying maintainable”.

So yes, they’re great for demos, but not for long-term projects.

Why I’m Doing This Myself

After years of working on backend systems, I realized I didn’t want a “template” anymore. I wanted a foundation.

When you’ve built enough APIs, you start to see what keeps breaking and what’s always needed. You get tired of rebuilding the same structure for every new idea.

I needed something clean, extensible, and trustworthy. A base I could spin up quickly for any MVP, but that could also scale without a full rewrite later.

That’s why I decided to build my own starter kit.
Not because I think I can do it better than others, but because I want one that fits the way I think about architecture.

The Principles Behind My StarterKit

This project is more than just a collection of files. It’s a reflection of certain ideas I really believe in.

• DIY Auth and Core Logic
  No vendor lock. Full control over the stack and the data.

• Scalable Modular Structure
  Each domain, like Auth or User, is its own module that can grow independently.

• Modern and Predictable
  Follows clean architecture patterns without going overboard.

• Production-Ready from Day One
  Includes configs, Prisma, logging, Docker setup, and Swagger.

• Readable and Educational
  Every decision should make sense when you read the code. Not just “it works”, but “here’s why it’s written this way”.

Basically, this isn’t just a starter kit. It’s a learning base for real-world backend development with NestJS.

Tech Stack and Design Choices

Every tool was chosen with long-term maintenance in mind.

• NestJS for its structured, modular architecture.

• Prisma ORM for type-safe and elegant database management.

• Passport and JWT for solid authentication and authorization flows.

• Docker and Environment Configs for consistent local and production environments.

• Jest for testing key modules.

• Swagger (OpenAPI) for easy API documentation and collaboration.

It’s intentionally simple on the surface, but powerful once you start building on it.

What I’m Trying to Achieve

I’m not doing this to reinvent the wheel. I just want to simplify my own workflow and reduce setup fatigue.

My goals are simple:

• Create a codebase that matches how I think and work.

• Make it fast to start new projects without rebuilding boilerplate.

• Share it so others who value clean architecture can use it too.

In a way, this project is also my documentation of thought, a living reference I can return to, refine, and grow with.

The Journey Ahead

This isn’t a one-time release. I’ll document it piece by piece, like an engineering journal.

Each core module (Auth, User, Config, Logging, etc.) will have its own breakdown.
I’ll explain:

• Why the design choices were made.

• What trade-offs were considered.

• What alternative patterns might also work.

Because the goal isn’t just to share code. It’s to share thinking.

Closing Thought

The best starter kit isn’t the one you download. It’s the one you understand deeply because you built it yourself.

That’s why I’m building my own NestJS StarterKit.
Not because others don’t exist,
but because this one will fit me and hopefully help others too.

Late September 2025 became one of those moments when I had an unexpectedly interesting experience. It all started with a small LinkedIn notification one afternoon. Someone with the initials AP reached out to me and asked if I really knew how to self-host a Signal server, especially since Signal Messenger’s own documentation on this is quite limited.

I confidently said YES, because I had already written about this topic on my blog (here).

A spark of excitement hit me. This felt like a chance to work with Signal Messenger on a larger scale and see it implemented more broadly.

In Short: The Technical Side of Signal Server

As I explained in my blog article, deploying a Signal Server is very challenging. The documentation is limited, the architecture is highly complex, and it relies on many supporting services.

Signal also uses several premium services from cloud providers. For example, BigTable, which I can’t realistically purchase just for a small-scale setup. Their design is clearly optimized for large-scale deployments, which is why many of their components depend on highly scalable services.

Recruitment Contact

I confidently answered every question from the client in our LinkedIn chat. They became interested in implementing the solution and decided to recruit me. Not just on a contract basis, since they noticed I was open to work, they offered me a full-time remote position for an initial duration of one year, with the possibility of extension.

That was quite appealing. A fully remote job, offered right away as a full-time role. They also suggested continuing the conversation over a WhatsApp voice call. I hesitated for a moment and did a quick background check on their profile, company, and track record. Everything looked “real” and legitimate. The profile was verified, and the person was listed as a Co-Founder and CTO of an Indian company.

Over the next two days, I had several WhatsApp conversations with another person, let’s call them MK, who seemed to be part of HR or perhaps an IT team lead. I also had a voice call with MK to discuss my experience and how I handle Signal Server deployments. Up to this point, nothing felt suspicious. Their technical questions were relevant and reasonable.

After that, MK scheduled an interview for me with their Senior Software Engineer based in the United States. They mentioned that the company in India was a branch of their US headquarters.

Red Flags Start to Appear

Nothing seemed strange… until I received a WhatsApp message that said,

Look in your inbox and you will find an email. Reply to it.

I checked my inbox. Nothing. I checked All Mail. Still nothing. Then I opened the Spam folder and there it was.

The email looked like this:

Hi Iriyanto

How are you?

Our reference is from our India company, Which you discussed on the LinkedIn.

so you have to send us your latest CV,

The following points are essential in which your actual full name,, as well as gender, date of birth, full address, contact number, email ID, passort number, as well as the name of the university and the name of the college where you passed graduation and what percentage you passed, and the name of the company in which you have worked in the last three years and the main role in which project you have done the details. Which countries in the world have you visited, which country's visa is in your passport? And whether you have applied to any company in USA or India before, If yes, when did you do it and then why did you not accept the application?

Suspicious? Definitely. They hadn’t even sent me an official offer letter, yet they were already asking for highly sensitive personal data, like passport number, travel history, and visa information.

This felt wrong, so I checked the email domain: tibco-hr-uk@tibco.online. Wait… .online domain? That was odd. I checked the official site tibco.com, it exists, has a verified LinkedIn page, and is a legitimate company with more than 25 years of history. Would a company of that scale really use a .online domain, and from the UK no less, not the US?

I cross-checked the LinkedIn profile of the so-called Senior Software Engineer from the “US branch.” Something didn’t add up. The real TIBCO page was verified, but this one claimed to be TIBCO Software (SA) Pty Limited and was unverified, yet somehow had many followers. Could LinkedIn followers be bought? Possibly.

At this point, my gut told me this was a scam, a clever one, but a scam nonetheless.

Escalation and Manipulation

Of course, I refused to provide such sensitive personal data, especially since I hadn’t even received an official offer letter yet. I politely replied, explaining that I would only share sensitive information once a formal offer was sent and onboarding had begun.

They kept trying to convince me, not through an official tibco.com email address, but by insisting that their Indian company was legitimate. They even sent me what looked like official company documents, including their CIN registration. But at this point, I was already too suspicious. I repeated my stance: I would not share sensitive information unless it came through official tibco.com channels and after receiving an offer letter.

And what did I get in return? Their tone on WhatsApp and email became completely unprofessional, behavior you would never expect from a large, established company.

They began demanding that I verify my LinkedIn account, claiming they rarely make offers to unverified users. Then came the accusations:

When is a LinkedIn CV valid? When you are verified on LinkedIn, then a LinkedIn CV is considered valid.

We suspect that you may be involved in some criminal activity in your country, which is why you are not disclosing your name.

Yap… They actually accused me of being a criminal. My real name, nationality, and phone number (+62) were all clearly listed on LinkedIn, and they already had my email and WhatsApp contact.

The messages escalated further:

you are trying to cheat LinkedIn companies by creating a fake profile on LinkedIn, creating a fake CV, and doing criminal activities on LinkedIn, we have to write it in the LinkedIn report, wait for a while and you will get your result.

We are now feeling that you are not getting a job even in your own country, so you are doing this online because your nature is criminal and arrogant.

And then came the most extreme message:

Hello cheater Iriyanto

Tell me your real name and real country? You seem to be the biggest cheater and fraud of the country, or you are a terrorist of your country because you are hiding your identity and lying to everyone.

dont worry We are taking action with you in your own country.

Yes. They actually called me a terrorist.

The escalation was absurd. In just a few days, I went from being a potential hire to being labeled a criminal and a terrorist, all because I refused to hand over my sensitive personal data.

What I Learned

• Never share sensitive personal data before receiving an official offer letter.

• Always verify the company’s email domain.

• Legitimate companies will never threaten or intimidate candidates.

• Watch for red flags early. Trust your instincts and investigate before moving forward.

Practical Tips for Other Developers

• Verify the company: check their email domain, cross-check on MCA (if it’s an Indian company), look them up on stock exchanges, and confirm through their official website.

• Use safe platforms for communication, such as LinkedIn, Upwork, or reputable job boards.

• Don’t be afraid to say “no” to unreasonable requests.

• Keep all evidence and report suspicious activity as phishing or scam.

Closing

Looking back, I felt disappointed. I was excited at first, but relieved that I got out without becoming a victim.

My message: stay cautious. Even the most convincing job offer can turn out to be a scam.

I encourage you to stay alert and share experiences like this so other developers don’t fall into the same trap.

It’s hard to believe, but I’ve been using NestJS for almost five years now. My journey started back in college when I was offered a project to build a backend system for a vessel tracking website based on MarineTraffic. At that time, I had just begun learning Node.js and this was my very first real-world project using it.

When facing a real project, the first questions that came to mind were: What are the requirements? What kind of backend architecture would be suitable? And most importantly, which framework could support those needs? My search for the right framework naturally began with the most popular option at the time, one and only Express.js.

Express, with its tagline “Fast, unopinionated, minimalist web framework for Node.js,” seemed appealing at first. The flexibility was impressive, almost too impressive. While exploring, I quickly found myself falling into a rabbit hole: Which companion packages should I use? How should the folder structure look? Should I follow MVC? Should I write in JavaScript or switch to TypeScript? And the list of questions kept growing.

That’s when I realized I might need to refine my search. Instead of looking for a minimal framework, I needed something more structured, an opinionated Node.js framework. And that’s when I discovered NestJS.

Key Reasons I’ve Stuck with NestJS for 5 Years

1. TypeScript as a First-Class Citizen

   TypeScript by default? Yes, please! Many developers argue that strongly typed languages make things unnecessarily complicated. That might be true for small projects, but when you’re building something more solid, TypeScript acts like a safety net for JavaScript. It saves you from those dreaded runtime type errors that can appear out of nowhere.

   With TypeScript, functions, objects, and even complex structures come with helpful snippets and autocomplete support. This speeds up development and reduces guesswork. NestJS embraces TypeScript from the ground up. When creating a new NestJS project, TypeScript is the default choice, though you can still opt for JavaScript if you want.

   But honestly, once you’ve enjoyed the safety, clarity, and productivity boost of TypeScript, who would want to go back to plain JavaScript?

2. Clean Architecture

   NestJS introduces a modular folder structure that feels both organized and intuitive. This is quite different from the traditional MVC approach, where you typically separate files by their function, controllers go into a controller folder, models into a model folder, and so on.

   With NestJS, the modular concept groups everything based on the domain of your application. For example, the UserModule contains the controller, service, entity, and repository related to users. If there’s an error in login, you know exactly where to look, the AuthModule. Everything related to authentication stays inside that module and nowhere else.

   This modular design makes projects much easier to navigate and maintain, especially as they grow larger. Instead of hunting across multiple folders, you can focus on a single module that fully encapsulates a feature or domain.

3. Dependency Injection

   Impressed with NestJS’s modular architecture? Hold on… it gets even better once you meet its powerful dependency injection (DI) system. Since NestJS takes inspiration from Angular, it also adopts Angular’s DI pattern.

   Modules in NestJS become even more powerful thanks to DI. For example, if Module A needs to use a service from Module B, you simply export the service in Module B and import that module into Module A. The DI container will take care of providing the instance wherever it’s needed.

   Another benefit of DI is performance optimization. By default, NestJS services are singletons, meaning only one instance is created and shared across the application. This saves memory and ensures consistent state management. Of course, if your use case requires it, you can also configure services to be request-scoped or transient.

   In short, DI in NestJS isn’t just a convenience, it’s a cornerstone that keeps your application clean, modular, and efficient.

4. Recommended Packages

   Remember the headache of choosing companion packages in Express? With NestJS, that problem is greatly simplified. The framework not only recommends optimal packages but also provides official wrapper modules for seamless integration.

   Take Mongoose, for example. Instead of wiring it up manually, NestJS offers @nestjs/mongoose, a dedicated module that integrates perfectly with the framework’s architecture. Need validation? NestJS supports class-validator and class-transformer out of the box. Need security? There’s built-in support for tools like helmet. Want API documentation? The @nestjs/swagger module automatically generates a complete OpenAPI specification from your controllers and DTOs, no need to handwrite specs.

   By curating and wrapping popular libraries, NestJS saves developers from decision fatigue and ensures best practices are followed by default.

5. Community & Documentation

   Back in 2020, there was no ChatGPT to turn to when you got stuck. The first lifeline was always documentation. Thankfully, NestJS provides one of the most beginner-friendly documentations out there. It’s structured almost like a step-by-step guide, yet it doesn’t shy away from diving deep into technical details when needed.

   The second lifeline was, of course, the community. The NestJS Discord server has been active for years, and asking questions there often brings direct answers from experienced developers, including some of the core contributors themselves. The combination of high-quality documentation and a responsive community makes NestJS approachable for beginners while still powerful for advanced users.

Comparison with Other Frameworks

• Express: great for getting started quickly, but less structured as your application grows

  Express offers a high level of flexibility. For developers who already have strong patterns and architectural practices in place, Express can feel like the perfect choice. It’s lightweight and works especially well for small services or microservices that handle a single responsibility, such as authentication or login endpoints. However, without clear conventions, large-scale projects in Express can become difficult to maintain, especially for teams with varying levels of experience.

• Koa / Hapi / Fastify: flexible but less opinionated

  Similar to Express, frameworks like Koa, Hapi, and Fastify focus on flexibility and performance. They give developers freedom to choose how to structure their applications. While this can be powerful, it didn’t match what I needed at the time.

  An opinionated framework like NestJS provides more than just convenience, it creates consistency. For a new team member, onboarding becomes easier: just follow the documentation and established patterns. For experienced developers, the workflow remains consistent because everyone is aligned by the same architectural design. This shared structure reduces confusion, accelerates collaboration, and keeps projects maintainable as they scale.

Real-World Use Cases

Over the years, I’ve implemented NestJS in a wide range of backend systems: asset management, ticketing systems, auction platforms, e-commerce applications, university education systems, and more. Even projects requiring real-time capabilities, like the vessel tracker I worked on, were achievable thanks to WebSocket and Socket.IO support.

Scaling with NestJS is straightforward thanks to its modular architecture. In one project, the authentication feature became the most frequently accessed part of the system, since every login and token validation request passed through it.

Scaling up the entire application just to handle this load would have been wasteful. Instead, we were able to extract the AuthModule and run it as a separate service within the same NestJS ecosystem. That way, only the authentication workload was scaled independently, without touching the rest of the application.

This modular design makes NestJS highly adaptable, whether you’re building monoliths, microservices, or a hybrid architecture.

Lessons Learned Over the Years

• Consistent Code Conventions

  NestJS’s opinionated design enforces best practices by default. This means every project follows a familiar structure, regardless of when it was created or who worked on it. Switching between projects or even revisiting an old one, feels seamless because the folder organization and code patterns remain consistent. This consistency reduces cognitive load, speeds up onboarding, and helps teams maintain codebases more effectively over time.

• Easier Testing with Dependency Injection

  One of the most frustrating parts of writing tests is setting up all the services and dependencies you need. Thanks to NestJS’s built-in dependency injection system, this process becomes much simpler.

  With the @nestjs/testing package, you can create a TestingModule that automatically provides the required services and their dependencies. This makes it easy to instantiate only what you need for the test, without manually wiring everything together.

  Dependency Injection not only simplifies test setup but also encourages cleaner, more maintainable unit tests across your application.

• Faster Onboarding for New Developers

  When junior developers ask me which Node.js framework they should learn first, my answer is always NestJS. Several juniors I’ve mentored started with it, and they adapted quickly. The opinionated structure and clear documentation allowed them to focus less on setup and more on delivering features. In no time, they were completing the tasks I assigned with confidence.

Drawbacks of NestJS

• Steep Learning Curve at First

  It’s true! The first time you try NestJS, the learning curve can feel steep. Concepts like decorators, dependency injection, and other unfamiliar terms may seem overwhelming at the beginning.

  But don’t worry. NestJS is often described as “easy to learn, hard to master.” You can start building applications quickly without needing to fully understand every concept under the hood. For example, it’s enough to know what a decorator does without diving into its internals.

  As you grow more comfortable, NestJS reveals its depth. Exploring advanced concepts allows you to fine-tune performance, optimize architecture, and unlock the full potential of the framework.

• Quite a Bit of Boilerplate

  Unlike Express, where you can get a basic API running in just a few lines, NestJS requires more code upfront when starting a project. At first, this can feel like a lot of boilerplate.

  The good news is that NestJS provides a powerful CLI to help. Need to create a module? Just run nest g module <module-name>. Want a complete resource with controller and service? The CLI can generate that too.

  These tools make it easy to manage the initial code overhead, and the comprehensive CLI effectively offsets the boilerplate, allowing you to focus on building features rather than wiring up structure.

• Sometimes Feels Too “Opinionated”

  This really comes down to personal preference. Some developers see it as a drawback, while others see it as a strength. It’s a double-edged sword. There are moments when creating even a single module feels like a lot of coding, even with the CLI helping out. But once it’s set up, the structure is solid, maintainable, and consistent. That initial extra effort pays off in the long run, especially as projects grow larger or when new team members join.

Conclusion

If you ask me which Node.js backend framework I recommend, my answer is always NestJS. Even today, I continue to use it whenever the project ecosystem is Node.js.

If you face the same challenges I encountered back in 2020, chances are you’ll end up discovering NestJS at the end of your search. It’s ideal for building solid backends, quickly delivering MVPs, and scaling both vertically and horizontally.

After five years of experience with NestJS, I’m now preparing a starter template that makes it even easier to get a backend up and running for MVP projects. I’ll share the GitHub repository soon, so stay tuned.

Signal has become one of the most trusted messaging platforms in the world, well known for its strong emphasis on privacy and security. Unlike many other messaging apps, Signal implements end-to-end encryption by default, ensuring that no one—not even the Signal team—can access the content of your conversations. This commitment to security and user freedom is one of the main reasons why individuals, organizations, and even governments rely on Signal for secure communication.

Beyond being a secure messenger, Signal is also open source, which means its codebase is publicly available for anyone to review, audit, and even contribute to. This transparency not only builds trust but also allows developers to experiment with self-hosting their own Signal infrastructure.

However, while the idea of running your own Signal server sounds exciting, the reality is far from simple. As highlighted in SoftwareMill’s article, deploying the Signal server is highly complex, requiring significant technical knowledge, specific dependencies, and ongoing maintenance to keep it in sync with Signal’s rapid development cycle.

To make matters more complicated, if you search for tutorials online with the keyword “how to deploy signal server”, most of what you’ll find is outdated. Signal’s server code has evolved drastically over the years, rendering older guides nearly useless. Many of those instructions no longer apply to the current architecture or dependencies of Signal Server.

Despite all these challenges, I managed to successfully deploy the latest version of Signal Server (v20250822.0.0). If you are interested in deploying Signal on your own infrastructure—whether for research, personal use, or within your company—you don’t have to start from scratch. You can reach out to me for guidance and support in setting up your own secure Signal environment.

Before You Start

In recent years, Signal has shifted much of its infrastructure to rely heavily on cloud-based services. This transition makes sense, as it allows Signal to scale globally and handle millions of concurrent users with high availability. Many of the critical components that power Signal—such as messaging queues, storage layers, and push notification services—are tightly integrated with cloud platforms.

For anyone attempting to run Signal Server on their own, this introduces some important considerations. Even if your goal is to deploy Signal locally, you will still need access to several of these cloud services. The good news is that many providers offer a free tier, which can be leveraged to set up a working environment without incurring high costs. With some careful configuration, it is possible to replicate much of the production setup while staying within free usage limits.

If your objective is to run Signal in a fully local environment, things become more complicated. This typically requires either modifying third-party code or setting up self-hosted replacements for cloud services using tools like LocalStack. While this is certainly achievable, it adds significant complexity and can make maintenance much more difficult in the long run.

In this article, we will take a more practical approach: deploying the latest version of Signal Server without heavily modifying its dependencies or services. The focus will be on getting Signal up and running with minimal adjustments, making it possible for you to experiment with a self-hosted deployment while still understanding how Signal’s infrastructure pieces fit together.

Preparation & Requirements

Before diving into the deployment steps, it’s important to understand the foundational requirements for running Signal Server. A successful deployment doesn’t just depend on the main server itself. It involves hardware, multiple cloud services, domain configurations, and a variety of supporting components. Below are the key elements you’ll need to prepare:

• Hardware

  For this deployment, I used a VPS running Ubuntu 24 with specifications of 4 CPU cores and 8 GB RAM. This provides enough resources to handle the compilation, dependencies, and basic operation of Signal Server.

• Cloud Services

  Signal relies heavily on cloud infrastructure. In our setup, we will be using:

  • AWS (DynamoDB, S3, etc.)

  • GCP (Firebase, Google Cloud Storage, etc.)

  • Cloudflare for DNS and security layers

…and several other services that integrate into the overall system.

• Domain

  Signal itself makes use of multiple subdomains for different services. While chat.signal.org acts as the main messaging endpoint, other subdomains such as storage.signal.org, svr.signal.org, and various TURN servers support additional functionality. A proper domain setup is crucial to mirror this architecture in your self-hosted deployment.

• Other Services

  It’s important to note that the Signal Server is only the core service. Many smaller supporting services such as storage, push notifications, and real-time communication helpers must be integrated for the system to function correctly. We will explore these dependencies in more detail later in this guide.

Get the Source Code

Signal Server’s code is available on GitHub:

git clone https://github.com/signalapp/Signal-Server.git

After cloning, switch to the latest version first (in this case v20250822.0.0). You can find the available versions in the GitHub repository under the tags section.

git checkout -b latest v20250822.0.0
git log

commit dbbd9134455affb83b350bb2121e4c8dc39dac0b (HEAD -> latest, tag: v20250822.0.0)
Author: Ravi Khadiwala ravi@signal.org
Date:   Fri Aug 22 11:40:16 2025 -0500

    Allow downgrade on SQPR capability

Build and Run

Signal Server is written in Java, and the latest release requires Java 24 (Temurin distribution) along with Maven (mvn) for building the project. Before attempting to compile, make sure both Java and Maven are properly installed and configured in your environment, as mismatched versions or missing dependencies will cause the build process to fail.

cd Signal-Server
mvn clean install -DskipTests

Once the compilation is complete, you will find the generated TextSecureServer-20250822.0.0.jar file located in the service/target directory. This JAR file serves as the main executable for running the Signal Server. From this point onward, it becomes the core binary you’ll use to start and manage your self-hosted Signal instance. Try to run it:

java -jar service/target/TextSecureServer-20250822.0.0.jar server

After trying to run the server, I encountered the error:

no main manifest attribute, in service/target/TextSecureServer-20250822.0.0.jar.

After a moment of reflection (and questioning my life choices), I discovered the root cause: there is a module called spam-filter that points to a private repository — https://github.com/signalapp/Signal-Server/blob/main/spam-filter. Since this repository is private, we don’t have access to it.

It seems that this module is intentionally private because it contains critical features related to spam protection, including spamChecker, challengeConstraintChecker, registrationFraudChecker, registrationRecoveryChecker, and captchaClientSupplier.

To work around this limitation, we need to exclude the module by adding the build flag -Pexclude-spam-filter when compiling the application then run it again.

mvn clean install -DskipTests -Pexclude-spam-filter
java -jar service/target/TextSecureServer-20250822.0.0.jar server

It looks like this time it’s not the same error as before, but rather a missing credentials issue. Inside the service/config folder, there are two configuration files that we need to provide when running the JAR file:

• The first one is sample-secrets-bundle.yml, which we include using the flag:

    -Dsecrets.bundle.filename=sample-secrets-bundle.yml
  

• The second one is the main sample.yml file, which is appended at the end of the command after server.

So the full command to run Signal Server is:

java -Dsecrets.bundle.filename=sample-secrets-bundle.yml -jar service/target/TextSecureServer-20250822.0.0.jar server sample.yml

After solving that issue, I thought the server would finally run and be ready to use. But reality can be harsh. In fact, this was only the beginning of the Signal Server setup journey. What followed was a cycle of endless trial and error, challenge after challenge—so much so that I started questioning whether I had made the wrong choices in life.

Still, no matter how tough it gets, each obstacle has to be solved one by one—and with a sense of pride for every small victory along the way.

Server Configuration

Based on my review of the sample.yml and sample-secrets-bundle.yml files, here is a summary of the key configuration sections:

• Logging: This can be directed to the console. Integration with Datadog can be disabled (since it’s a paid service).

• Metrics: Can be directed either to the console or stored in a CSV file.

• TlsKeyStore: This can be left as default.

• Payments (Stripe, Braintree, Google Play Billing, Apple App Store, PaymentsService): Subscriptions and one-time donations can be left as default or ignored entirely if you don’t need payment integration.

• AppleDeviceCheck & DeviceCheck: Leave as default (their exact purpose is unclear for now, so we’ll leave them untouched).

• DynamoDB & DynamoDB Tables: This is the core configuration for Signal Server’s database. Proper setup is critical.

• pagedSingleUseKEMPreKeyStore: Used to store keys, which must be configured with AWS S3.

• Redis Clusters (cacheCluster, pubsub, pushSchedulerCluster, rateLimitersCluster, messageCache): These require Redis in cluster mode. Running this in the cloud can be expensive, so I configured a Redis cluster on a single VM instead (I’ll explain how to set this up later in another article).

• directoryV2: Can remain as default. This is related to the Contact Delivery Service.

• svr2, svrb, storageService, registrationService, keyTransparencyService: These are supporting services that work alongside the main Signal Server. We’ll discuss them in detail later.

• gcpAttachments & tus: Used for attachment uploads.

• apn & fcm: Required for push notifications.

• cdn & cdn3StorageManager: Handle profile pictures, attachments, and related media.

• dogstatsd & openTelemetry: These can be safely ignored.

• unidentifiedDelivery, zkConfig, callingZkConfig, backupsZkConfig: These are critical configurations because they are directly tied to libsignal. They must be set up properly.

• dynamicConfig: A dynamic configuration stored in AWS S3 that continuously syncs with the application. This is also very important.

Other Services

These are the supporting services that must also be set up for the main Signal Server to run properly. Each of these services has its own configuration, but for now, I’ll just summarize what they are and their functions. I may cover the detailed setup instructions in future articles.

• Registration Service: A core dependency that enables users to register. It handles the creation of registration sessions, which require users to verify their phone numbers.

• Storage Service: Essential for group functionality. Without this service, users cannot create groups or perform group-related activities.

• Coturn: Signal has migrated from self-hosted Coturn to Cloudflare’s TURN service. Fortunately, Cloudflare provides a monthly quota for free usage, and charges only once that quota is exceeded.

• Signal Calling Service: While the TURN server handles one-to-one calls, this service enables group calls and video calls. Without it, group calling would not be possible.

• Tus: Handles file uploads. Signal is transitioning from Google Cloud Storage (GCS) to this service. For now, you can override it with GCS and safely ignore it, since Tus needs to be deployed on Cloudflare Workers (a paid service).

• Contact Discovery Service: A resource-intensive service that requires Intel SGX. Its function is to map user contacts to determine whether they already have a Signal account.

• Secure Value Recovery v2: Another SGX-dependent service, responsible for verifying a user’s PIN during account recovery.

• Key Transparency Service: Protects against man-in-the-middle attacks by ensuring that the public key received by a client truly belongs to the intended user. It also provides auditability and prevents the server from manipulating keys.

With these services in place, you should have everything needed to run a functional Signal Server. Some services may not be explicitly listed here, as they are used primarily on the client side (mobile and desktop), so additional tracing may be required to identify any missing components.

But with that said, this marks the (hopefully final) milestone in setting up Signal Server. Here’s a screenshot of victory in this battle:

Setting up the latest version of Signal Server is far from a simple task. From dealing with private modules, cloud dependencies, and countless supporting services, the journey requires patience, persistence, and a deep dive into Signal’s evolving architecture. But in the end, the reward is worth it: the ability to run your very own self-hosted instance of one of the most secure messaging platforms in the world.

If you’re interested in deploying Signal Server for research, personal use, or within your organization, you don’t have to go through the same trial-and-error process I did. I can help you streamline the setup and get your own Signal Server running smoothly.

👉 Feel free to reach out to me if you’d like assistance with your Signal Server deployment.

Signal has always fascinated me, not only because of its focus on privacy, but also because it’s fully open source. This means you’re free to dive into the source code, learn how things work under the hood, and even compile your own version of the app.

In this post, I’ll walk you through how I compiled and ran the latest version of Signal Android (v7.55.0) on my local machine. This isn’t meant to be a super detailed tutorial, but more of a starting point if you’re curious about how Signal works behind the scenes.

Step 1: Get the Source Code

Signal Android’s code is available on GitHub:

git clone https://github.com/signalapp/Signal-Android.git

After cloning, switch to the latest version first (in this case v7.55.0). You can find the available versions in the GitHub repository under the tags section.

git checkout -b latest v7.55.0
git log

commit 8e9dc7895757f7e7bf7b2f3ac5b283371714caa5 (HEAD -> latest, tag: v7.55.0, origin/main, origin/HEAD, main)
Author: Michelle Tang mtang@signal.org
Date:   Wed Aug 27 16:09:44 2025 -0400

    Bump version to 7.55.0

Step 2: Open Android Studio

When you open the Signal Android project in Android Studio, the IDE runs a Gradle sync, which means it reads the project’s configuration files (build.gradle, settings.gradle, etc.) and sets up the project structure accordingly. During this process, Gradle also checks for any required libraries or plugins defined in the configuration. If those dependencies are not already available in your local cache, Android Studio will automatically download them from repositories such as Maven Central or Google’s Maven. That’s why you often see a “Sync” and “Downloading” process the first time you open the project or after clearing caches—it ensures the project has everything it needs to build and run correctly. As you can see in the screenshot below, just wait until the sync process finishes.

Step 3: Build the App

After the sync is complete, the first step is to build the project. This ensures that all the code and dependencies compile correctly and the project structure is set up properly. In Android Studio, you can build the project by going to the top menu and selecting Build → Make Project, or by using the shortcut Ctrl+F9 (Cmd+F9 on Mac). Building the project at this stage helps identify any missing dependencies, compilation errors, or configuration issues before you attempt to run the app.

Step 4: Run It Locally

Once the project builds successfully, you can run the app to see it in action. In Android Studio, click the Run button (the green triangle) in the toolbar, or use the shortcut Shift+F10 (on Windows/Linux) or Control+R (on Mac). You will then be prompted to select a target device, which can be either an Android emulator or a physical device connected via USB with developer mode enabled. Running the app allows you to verify that it launches correctly and that the initial setup is working before making any changes to the code.

After running the application, you can try registering a new account because the app has already been configured to connect to the Signal server. This setup allows you to test the app’s core features, such as sending and receiving messages, without needing any additional configuration. It’s a great way to verify that your local build is working correctly and that the connection to the server is properly established.

To check which version of Signal Android is currently installed on your device, open the app and navigate to Settings → Help. This section not only shows the app version but can also provide useful information for troubleshooting, ensuring that you are using the correct version, and confirming that your app is up to date before making any changes or updates.

Why This Matters

Compiling Signal yourself gives you:

• Transparency — you know exactly which version of the code you’re running.

• Learning — a chance to understand how a real-world secure messaging app is structured.

• Flexibility — the first step if you ever want to connect Signal Android to your own self-hosted Signal server.

What’s Next

In future posts, I’ll dive deeper into other parts of the ecosystem:

• Deploying a Signal Server

• Connecting your custom Android client

• and more…

This is just the beginning of exploring Signal from an open source and self-hosted perspective 🚀

Notes

This series is meant to document my journey in exploring and deploying Signal. If you’re also curious about running your own Signal server but don’t want to go through all the setup pain, I can help you get started. Just reach out!

What makes Signal special isn’t just the fact that it offers end-to-end encryption by default (although that’s already a big deal). For me, the real highlight is that Signal is fully open source—both the app and the server.

That’s important because it means anyone can audit the code, understand how it works, and even contribute to its development. There’s no “black box” or hidden trick in how your messages are handled. Compared to other chat apps owned by big corporations, Signal stands out as a privacy-first platform that is transparent by design.

As someone really passionate about open source, this resonates with me a lot. In Indonesia, it’s not very common to see local developers getting deeply involved with starting and maintaining open source projects, but tools like Signal show us what’s possible when a community comes together to build something meaningful.

In fact, discovering Signal is one of the reasons I became more interested in exploring how self-hosting could work for messaging platforms. Imagine running your own secure messaging server—having complete control over your data, while still using the same strong encryption that Signal is known for.

That’s where my curiosity started, and it’s a topic I’ll be writing more about in this series. In the next post, I’ll dive into what it actually takes to self-host Signal—the benefits, the challenges, and why it might be worth considering if privacy and data control matter to you.

One of the main reasons I decided to start this blog is to improve my communication skills. Writing is a great way for me to practice putting ideas into words, and I believe this will also help me in the future when I start creating content on platforms like YouTube.

Another thing I’m really passionate about right now is open source. In Indonesia, it’s quite common for developers to contribute as collaborators to projects, especially those started abroad, but it’s rare to see local developers initiating and maintaining their own open source projects. That’s something I want to change. My long-term goal is to dedicate more time to open source and eventually start projects that come from Indonesia and hopefully make an impact.

Besides those bigger goals, this blog will also serve as a personal space for me. I’ll use it to document my learning journey, share project experiences, and build my portfolio and personal brand along the way.

That’s it for a short introduction—thanks for stopping by, and nice to meet you!