Welcome to the easyShip docs! Here, you'll find step-by-step guides to help you get started and make the most of this boilerplate.
easyShip provides a robust boilerplate built with Java, powered by Spring Boot and Thymeleaf on the backend. On the frontend, it features TailwindCSS and Daisy UI for clean and responsive design.
Java has long been seen as overkill for small projects, but with Spring Boot’s support, it becomes an efficient tool for bootstrapping even small-scale SaaS projects. However, many developers, whether new to programming, students, or corporate engineers, often struggle with shipping end-to-end products.
As an indie developer who spent 10 years working in corporate environments, I’ve learned that building real-world products can feel overwhelming. You focus on one feature, like Authentication, only to get stuck on Payments. Or you manage to handle Payments but then hit a wall with Social Login or AI integration. I’ve been there—failing multiple times—before bringing all my experience into easyShip.
Let’s skip the distractions and hit the ground running. Here’s how you can get started:
git clone https://github.com/easyship-pro/starter.git
git remove remote origin
cd starter
./mvnw spring-boot:run -Dspring-boot.run.profiles=demo
That’s it! Now navigate to localhost:8080 and explore the demo. From here, you can start building pages, debugging your product, or deploying it to production.
The project follows a standard Java/Maven structure with additional features like a /src/main/frontend
directory
to handle npm configurations for your frontend.
Key packages include:
Use different profiles like default
, dev
, or demo
to run the app. For local development, use the application-dev.properties
file and
seed your database with data-dev.sql
.
easyShip provides a fully functional demo project (yes, it's easyShip itself!) available in the repository. You can deploy it in just 10 minutes.
git clone repo
./mvnw spring-boot:run -Dspring-boot.run.profiles=demo
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------< com.backstarter:api >-------------------------
[INFO] Building backstarter 0.0.1-SNAPSHOT
[INFO] from pom.xml
Started BackstarterApiApplication in 2.014 seconds (process running for 2.201)
Now you can access the demo project locally at localhost:8080.
You can also navigate to localhost:8080/login
and log in using the default credentials: test@easyship.pro
and password 1234.
That's it! Your demo project is now up and running on a real host. Explore the features and start shipping faster.
Creating a new page with easyShip is as simple as copy-pasting!
@Controller
public class YourAwesomeListingController {
@GetMapping("/your-awesome-path")
public String listAwesomeThings(Model model) {
return "your-awesome-component";
}
}
The your-awesome-component
is an HTML file located in the src/resources/templates
folder.
You can use pre-built components from the src/resources/components
folder to build your page.
That’s it! Your page is live and ready to showcase your awesome ideas.
npm run build:css
command in your /src/main/frontend
directory!
easyShip comes with Stripe integrated. In this tutorial, we’ll set up a Payment Link step-by-step, including creating a product and a Payment Link for simplicity.
Go to your Stripe dashboard and create a product.
Generate a Payment Link for the product you just created.
Generate a Secret Key in your Stripe dashboard to authenticate API calls.
That’s it! Your Stripe account and API key is setup!
Privacy Policy & Terms of Service are mandatory when setting up a Stripe account or any other purposes.
easyShip boilerplate includes AI prompts to help you generate these overwhelming documents in minutes.
Go to the src/resources/templates/prompt
directory to find the prompt files (.prompt) for creating your License Agreement, Terms of Service, and Privacy Policy. Simply add your business details, use ChatGPT with these prompts, and you'll be up & running!
Our boilerplate provides essential tools to streamline your workflow and power your Micro SaaS effortlessly!
easyShip comes with built-in authentication flows, including email login, a registration process, and social login with Google.
@PreAuthorize("hasRole('USER')")
to the controller method and define your endpoint in the
SecurityConfiguration.java
class.
No setup is needed to test email login! Simply run the following commands (ensure you have Java 21 installed):
git pull repo
./mvnw spring-boot:run -Dspring-boot.run.profiles=demo
Once the application is running, navigate to
localhost:8080/login
.
Use the pre-defined credentials from data-demo.sql
to log in.
The password is encrypted but set to 1234 for demo purposes.
You can access the registration flow at localhost:8080/account/registration . By default, this flow sends a six-digit email verification code for account activation.
If you’d like to skip email verification, you can modify the flow to remove this step.
Alternatively, configure your email settings in
application.properties
to enable full functionality.
Both options are flexible, so feel free to adapt them based on your requirements!
easyShip also comes with Google login integrated. With minimal configuration, you can enable it with no code!
You need to set up an OAuth Client ID in Google Cloud Console (takes about 5 minutes).
1. Visit Google Cloud Console and log in if you haven't already.
2. Create a new project (if you don't already have one).
3. Navigate to your project, create a credential, and select "OAuth Client ID."
4. Select "Web application" as the application type. Your configuration should look similar to this:
easyShip comes with built-in database integration to get you started quickly. When you run the
application in
demo or development mode, an in-memory H2 database is automatically set up. You can manage the data
through
the data-dev.sql
or data-demo.sql
files, which already include test data
for features
like login.
Database tables are defined by entity classes. For example:
UserEntity.java
: Manages the users table.VerificationTokenEntity.java
: Stores six-digit verification codes for registration
and password recovery flows.
Need more tables? Just add them to your entity classes and populate test data in the respective SQL files to fit your needs.
To use a production database, configure the following properties in your application.properties
file:
#################################################
# MySQL Configuration
# Replace with your database details
spring.datasource.url=jdbc:mysql://your_db_address:your_db_port/your_database_name
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
By default, easyShip includes the MySQL dependency. If you'd like to use PostgreSQL instead:
pom.xml
file.<!-- PostgreSQL Database Dependency -->
in your
pom.xml
to locate it quickly.
application.properties
, change the following property to the Postgre as spring.datasource.driver-class-name=org.postgresql.Driver
Both databases are supported, so choose what works best for your project!
Emails are managed using a pre-configured JavaMailSender.java
.
For example, the EmailService.java
class demonstrates its usage in the registration
flow.
This service utilizes pre-built email templates located in the templates
or components
directory.
Most email providers offer SMTP configuration options. Use these details to update the following
properties in your
application.properties
file:
spring.mail.host=[SMTP_HOST]
spring.mail.port=[SMTP_PORT]
spring.mail.username=[YOUR_EMAIL]
spring.mail.password=[YOUR_PASSWORD]
You can add new methods to EmailService
to support additional email flows, such as
campaign emails
or other custom use cases for your micro SaaS.
easyShip comes pre-integrated with OpenAI. While the implementation isn't overly complex or magical, it simplifies the process, saving you from the common hurdles of making a successful request for the first time.
The OpenAIAdapter.java
handles requests and parses responses from ChatGPT.
You can find example usage in the ChatbotDemoService.java
class. Extend these classes
to meet your specific needs!
To get started, set the following property in your application.properties
file:
openai.api.key=${OPENAI_API_KEY:YOUR_OPEN_AI_API_KEY}
If you don't yet have an API key, note that it's different from a ChatGPT Plus subscription. Follow these steps:
easyShip comes pre-integrated with Stripe. A webhook is ready for you to manage your payments or subscriptions.
In StripeWebhookController.java
, you can see how the logic for events is handled. You'll find
handlePaymentSucceeded
, handleSubscriptionUpdated
, and handleSubscriptionDeleted
methods, which are the most common ones.
handlePaymentSucceeded
, which corresponds to the "buy" operation made by customers, updates the
users
table's "paid" field, enabling you to determine paid users. You can easily extend this to
subscriptions, as the related events are already handled.
All you need to configure is updating the following properties in the application.properties
file:
stripe.apiKey=your_stripe_api_key
stripe.endpointSecret=your_stripe_endpoint_secret
Remember, you can always use production keys in application.properties
and use
application-dev.properties
for development purposes.
For testing, download and install the Stripe CLI.
Run the following commands in separate terminals after logging in:
stripe listen --forward-to localhost:8080/stripe/webhook
stripe trigger invoice.payment_succeeded
After that, your Webhook will receive the request. You can put a breakpoint and debug the code using Debugger!
application-dev.properties
file while testing locally.
Explore the reusable components provided by easyShip to build consistent and efficient UIs.
Here in this section you'll find different components to build your Micro Saas: Hero, Problem, Pricing, FAQ, Footer, and Header.
You don't need to worry much about what's going under the hood. Just find these components under
src/resources/components
directory, copy & paste them to your own page under src/resources/templates
for Thymeleaf to be able to resolve from. Then the rest is just creating a Controller and returning the file view name.
The header component includes the navigation bar, logo, and other essential elements. It's fully responsive and easy to customize to fit your brand's identity.
Simply replace the default logo with your own brand logo in SVG format.
Prefer using an image instead? No problem! Images can be served from
src/resources/static/png
,
/svg
, or even a new directory of your choice.
The hero section is designed to grab attention with a bold message and clear call-to-action buttons.
As one of the most critical sections of your page, the hero helps you make a strong first impression and connect with your audience. Use it effectively to showcase your product and encourage users to act.
The pricing component is a clean and flexible Tailwind-based design that works well for most use cases.
Need more pricing plans? Simply duplicate the card component in the code to create additional options effortlessly!
The problem section is designed to hook your audience with a concise and impactful statement. Clearly define the problem that your product or SaaS solves—this helps your audience feel understood and reassures them that your solution is tailored to their needs.
This section is often overlooked on many websites, but it's crucial for connecting with your audience and highlighting why your product matters. A well-crafted problem statement can significantly boost the appeal of your offering.
The testimonial component is perfect for showcasing customer reviews and building trust with your audience. Many developers start with a silent launch or beta release to gather early feedback, and testimonials collected during this phase can be invaluable.
Don’t worry if you don’t have reviews or testimonials yet—every product starts without them! Focus on refining your product, and the positive feedback will follow in time.
The FAQ (Frequently Asked Questions) component is a great way to address common user questions and concerns upfront. It helps build confidence in your product by providing clear and concise answers to potential queries.
Even if you’re just starting out, consider adding a few questions you think your users might have. Over time, as you interact with your audience, you can refine and expand this section to reflect their real concerns and feedback.
The features component is designed to highlight the key aspects of your product or SaaS. It’s a perfect way to showcase what makes your offering unique and why your users will love it.
Use this section to clearly explain the benefits and functionality of your product. Whether it's speed, ease of use, or innovative solutions, make sure your features are communicated in a way that resonates with your audience.
Don’t overload the section—focus on a few standout features that provide the most value to your users. You can always expand later as your product grows.
The Features Listicle component is an ideal way to present your product's highlights in a clean, easy-to-read format. By breaking down your features into a list, you make it simple for users to understand the value your product provides.
Use this component to focus on the most impactful aspects of your product. Each list item can briefly explain a feature, supported by icons or short descriptions to make the information visually engaging.
This format works best when you need to communicate a lot of information without overwhelming your audience. Keep the list concise, and prioritize clarity and readability.
The Featured On component is a great way to highlight the platforms where your product or SaaS has been showcased. Featuring logos of trusted platforms like Reddit, Product Hunt, and Twitter adds credibility and builds trust with your audience.
Don’t worry—this doesn’t need to be a big thing! You can share your product on these platforms in a humble and approachable way. Even small mentions or early-stage feedback can be valuable to include here.
You can easily customize this component by adding logos of other platforms that are relevant to your audience. Whether it’s tech blogs, review sites, or social media platforms, tailor the section to reflect where your product has been recognized.