Tutorials

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.

Hi there, builder! Let’s get started 👋

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.

easyShip requires Java version 21 or greater and an npm version compatible with the setup.

Java Project Structure:

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:

  • directory-line /account -> Handles Authentication, Google Login, and Registration flows
  • directory-line /payment -> Manages payment integrations
  • directory-line /core -> Your product's core logic
  • directory-line /ai -> Integration with OpenAI
  • directory-line /email -> Email configuration and management

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.

Tip: After running the demo, you can follow this guide to deploy your project in just 10 minutes!

Ship In 10 Minutes 🚀

easyShip provides a fully functional demo project (yes, it's easyShip itself!) available in the repository. You can deploy it in just 10 minutes.

What the Demo Includes:

  • Login flow with predefined login credentials and Google login
  • Registration flow email verification
  • A landing page with essential sections: Hero, Problem, FAQ, and Pricing
To use the registration flow and Google login, make sure to configure your Email and Google account in the Google Developer Console using the docs here. If you prefer, the login flow works right out of the box without any setup!

Get Started in 3 Simple Steps:

  1. Clone the Repository:git clone repo
  2. Navigate to the Root Directory: Open your terminal in the downloaded project's root folder.
  3. Run the Application: Execute the following command:
./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.

Deploy Your Demo to a Real Host Provider:

  1. Select a Hosting Provider: Navigate to your favorite provider. For example, Koyeb is one of the easiest options to get started with.
  2. Link Your Account: Connect your hosting provider account with your GitHub account to access your repositories.
  3. Deploy the Service: Deploy your demo project directly from the selected repository using the hosting provider's deployment tools.

That's it! Your demo project is now up and running on a real host. Explore the features and start shipping faster.

Creating a Page

Creating a new page with easyShip is as simple as copy-pasting!

Steps to Create a New Page:

  1. Create a New Controller: Add a new controller class. Here’s an example:
    @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.


  2. Use Pre-Built Components: Copy and paste pre-built components (e.g., the Hero section) into your page.

  3. Customize the Content: Update the content to suit your Micro SaaS needs.

  4. Access Your Page: Open your browser and navigate to http://localhost:8080/your-awesome-path.

That’s it! Your page is live and ready to showcase your awesome ideas.

Remember: Everytime you build a new page or change some CSS in your html file, you need to run npm run build:css command in your /src/main/frontend directory!

Handling Payments

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.

Tip: Stripe requires you to have Terms of Service and License pages on your website to accept payments. Always double-check legal requirements with your local advisor or reliable sources.

Steps to Set Up Payments

  1. Create a Product:

    Go to your Stripe dashboard and create a product.

    Creating a product
  2. Create a Payment Link:

    Generate a Payment Link for the product you just created.

    Creating a Payment Link
  3. Create a Secret Key:

    Generate a Secret Key in your Stripe dashboard to authenticate API calls.

    Creating a Secret Key

That’s it! Your Stripe account and API key is setup!

After completing the setup, configure your Stripe settings to test the flow. See Payments. Also, remember to use Test mode while testing locally.
Enlarged image

Privacy Policy with AI

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!

Tip: Always review the generated documents with a legal advisor before using them.

Features

Our boilerplate provides essential tools to streamline your workflow and power your Micro SaaS effortlessly!

Authentication

easyShip comes with built-in authentication flows, including email login, a registration process, and social login with Google.

Tip: Want to secure an endpoint and make it require authentication? Simply add @PreAuthorize("hasRole('USER')") to the controller method and define your endpoint in the SecurityConfiguration.java class.

Testing Email Login

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.

Testing Registration

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!

Social Login with Google

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.

Creating a project in Google Cloud

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."

Creating credentials in Google Cloud

4. Select "Web application" as the application type. Your configuration should look similar to this:

Google OAuth Client ID configuration details
Enlarged image

Database

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.

Managing Database Tables

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.

Production Database Configuration

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

Switching Between MySQL and PostgreSQL

By default, easyShip includes the MySQL dependency. If you'd like to use PostgreSQL instead:

  1. Uncomment the PostgreSQL dependency in your pom.xml file.
  2. Comment out the MySQL dependency.
  3. Search for <!-- PostgreSQL Database Dependency --> in your pom.xml to locate it quickly.
  4. In 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!

Email

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.

Configuring Your Email Provider

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]

Extending Email Functionality

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.

AI Integration

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.

How It Works

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!

Configuration

To get started, set the following property in your application.properties file:

openai.api.key=${OPENAI_API_KEY:YOUR_OPEN_AI_API_KEY}

Getting Your OpenAI API Key

If you don't yet have an API key, note that it's different from a ChatGPT Plus subscription. Follow these steps:

  1. Visit the OpenAI platform documentation at platform.openai.com/docs/overview.
  2. Sign up for an account, if you haven't already.
  3. Add funds to your account (e.g., a $5 top-up can last for weeks for testing purposes).

Payment

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.

Testing

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!

Remember: In your local environment, the endpoint secret is generated when you start listening with Stripe CLI. Add this value to your application-dev.properties file while testing locally.

Components

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/componentsdirectory, 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.

To build pages with these prebuilt components, see the Creating a Page tutorials for guidance.

Hero

The hero section is designed to grab attention with a bold message and clear call-to-action buttons.

Hero component

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.

Pricing

The pricing component is a clean and flexible Tailwind-based design that works well for most use cases.

Pricing component

Need more pricing plans? Simply duplicate the card component in the code to create additional options effortlessly!

Pricing trio component

Problem

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.

Problem component

Testimonial

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.

Testimonial component

FAQ

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.

FAQ component

Features

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.

Features component

Features Listicle

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.

Features Listicle component