TUSC - URL Shortener

An enterprise-grade, powerful and scalable URL shortener with integrated bio pages built using Spring Boot.

Table of Contents

• Overview
• Features
• Getting Started
  • Prerequisites
  • Local Setup
  • Deployment
  • Cloud Native Deployment
• SMS Configuration
• Use Cases
• Contributing
• License

---

Overview

This project is an enterprise-grade URL shortener and bio page application developed with Spring Boot. It provides a robust solution for shortening URLs and creating bio pages for users. The application is designed for scalability and includes features such as analytics, user management, and subscription plans.

Features

• Shorten URLs and create custom short URLs.
• Integrated bio pages for users.
• Analytics tracking for each shortened URL.
• User management with registration, login, and profile updates.
• Subscription plans for premium features.
• Rate limiting to prevent abuse.
• Forgot password and username recovery functionality.
• OPEN API 3.0 Complaint REST API set, with extensive docs.

Tech Stack:

• Java (JDK 21): The core programming language for the application.
• Maven 3: A build automation and project management tool. Used for managing dependencies and building the application.
• MySQL/Mariadb: Relational database management system used for data storage.
• Spring Boot: A framework that simplifies the development of Java applications, providing convention over configuration and a variety of built-in features.
• Logger (Logback): Logback is a logging framework for Java applications. It's the default logging framework in Spring Boot.
• Templating Engine (Thymeleaf): Thymeleaf is a modern server-side Java template engine for web and standalone environments. It is a well-integrated part of the Spring ecosystem.
• AJAX (Asynchronous JavaScript and XML): A technique for creating dynamic and interactive user interfaces. It allows updating parts of a web page without reloading the entire page.
• RESTful API: A standard architectural style for building web services. The application provides RESTful APIs for various functionalities.
• OpenAPI 3.0: A specification for building APIs that allows for describing, producing, consuming, and visualizing RESTful web services.
• Docker: A platform for developing, shipping, and running applications in containers. Used for containerizing the application.
• Git: A distributed version control system used for tracking changes in the source code.
• Kubernetes: A container orchestration platform used for automating the deployment, scaling, and management of containerized applications.
• Swagger UI: A tool that helps design, build, document, and consume RESTful APIs. It's often used with OpenAPI specifications.
• Tailwind CSS: A utility-first CSS framework that makes it easy to design and build modern, responsive user interfaces.
• Flowbite: A design system and UI toolkit for building responsive web applications.

---

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Java (JDK 11 or later)
• Maven
• MySQL
• Your favorite IDE (IntelliJ, Eclipse, etc.)

1-Click Local Installation Windows | Linux

Windows

1. Open a Command Prompt with administrator privileges.
2. Navigate to the project's installers folder.
3. Run the install.bat file by double-clicking on it or using the following command:

   1 lines
   Copy
   1install.bat
   

Linux

1. Navigate to the project's installers folder.
2. Run the install.sh using the following command:

   2 lines
   Copy
   1chmod +x install.sh
   2./install.sh
   

3. Follow the on-screen instructions.

Finally, Select Application Server : Tomcat/Wildfly

---

Local Setup

1. Clone the repository:

   2 lines
   Copy
   1git clone https://github.com/aamitn/URLShortener.git
   2cd URLShortener
   

2. Apply the Database Schema:

   Execute the provided create.sql file to set up the necessary tables and schema for the application. This script will also create the required database.

   1 lines
   Copy
   1mysql -u your_username -p{your_password} < create.sql
   

3. Update the application.properties file:

   • Update the application.properties file in the src/main/resources directory with your application configuration.

4. Build and run the application:

   1 lines
   Copy
   1mvn spring-boot:run
   

5. Access the application at http://localhost:8080

---

Deployment Setup

1. Build a deployable WAR:

   1 lines
   Copy
   1mvn clean install
   

2. Deploy the WAR:

   • Option 1: Manual Deployment

     Deploy the generated WAR file to your Tomcat server. Copy the WAR file to the webapps directory of your Tomcat installation.

     1 lines
     Copy
     1cp target/shorten.war /path/to/tomcat/webapps/
     

   • Option 2: Web Interface Upload

     Alternatively, if your Tomcat server provides a web interface for WAR file deployment, follow these steps:

     • Access the Tomcat Manager web interface at http://localhost:8080/manager/html (replace with your Tomcat server address).
     • Log in with your Tomcat manager credentials.
     • Navigate to the "WAR file to deploy" section.
     • Choose the shortener.war file using the file upload button.
     • Click the "Deploy" button.

3. Configure Variables on deployed war:

   Set environment variables for cloud-specific settings.

4. Adjust Tomcat Configuration (Important):

   To ensure proper functionality, it's important to run the application on the root of the servlet container. If you're using Tomcat, add the following line to your server.xml configuration file within the <Host> section:

   1 lines
   Copy
   1<Context path="" docBase="shorten" reloadable="true"></Context>
   

   This ensures that the application runs on the root context path. Adjust the docBase attribute according to your deployment directory.

5. Start Tomcat:

   Start your Tomcat server.

   2 lines
   Copy
   1/path/to/tomcat/bin/startup.sh   # for Linux
   2/path/to/tomcat/bin/startup.bat  # for Windows
   

   Access the application at http://localhost:8080/.

6. Adjust Configuration (Optional): If you need to customize the application configuration after deployment, you can find the application.properties file within the deployed WAR file. THe file can be accesses as :

   1 lines
   Copy
   1vi /path/to/tomcat/webapps/shortener/WEB-INF/classes/application.properties
   

---

Cloud Native Deployment

To deploy the URL Shortener application on your cloud environment, follow the steps below:

Prerequisites

• Docker
• Docker Compose
• Kubernetes/K8s
• Minikube
• Helm

1. Clone the Repository:

   2 lines
   Copy
   1git clone https://github.com/your-username/URLShortener.git
   2cd URLShortener
   

2. Deploy Using Docker

• Build and Run Your Own Image:

  2 lines
  Copy
  1docker build -t shortener:latest .
  2docker run -p 8080:8080 -p 3306:3306 shortener:latest
  

OR

• Use Our Pre-built Image with Docker Compose:

  2 lines
  Copy
  1docker compose build
  2docker compose up
  

• Customizing Docker Compose Configuration:

  In the docker-compose.yml file, you can customize the build source for the Shortener service:

  7 lines
  Copy
  1# Build from docker hub image .Comment/Uncomment Below
  2image: nmpl/shortener:latest
  3
  4 # Build from local Dockerfile.Comment/Uncomment Below
  5 #   build:
  6 #     context: .
  7 #     dockerfile: Dockerfilekerfile
  

  Comment or uncomment the relevant lines based on whether you want to use the pre-built image from Docker Hub or build from the local Dockerfile.

3. Deploy Using K8s

• Setup Kubernetes Deployment and Service:

  2 lines
  Copy
  1cd k8s
  2kubectl apply -f deploy.yaml,service.yaml,data.yaml
  

• Expose the K8s service:

  1 lines
  Copy
  1kubectl port-forward service/shortener-app 8080:8080
  

  Access Application at http://localhost:8080

  OR If you're using minikube, run the below command to run the app:

  1 lines
  Copy
  1minikube service shortener-app
  

• Use the following command to monitor the deployment:

```plaintext

 kubectl get pods
```

4. Deploy Using Helm Chart

• Create Deployment from helm chart named "instance" , with a service named "instance-shortener-chart" :

  2 lines
  Copy
  1cd k8s
  2helm install instance shortener-chart/ --values shortener-chart/values.yaml
  

• Expose the K8s service:

  1 lines
  Copy
  1kubectl port-forward service/instance-shortener-chart 8080:8080
  

  OR If you're using minikube, run the below command to run the app:**

  1 lines
  Copy
  1minikube service shortener-app
  

• Use the following command to monitor the deployment:

```plaintext

 kubectl get pods
```

Wait until the pod is in the "Running" state.

• Access the Application

  Depending on your Kubernetes setup, you might need to get the external IP of the service:

  1 lines
  Copy
  1kubectl get service instance-shortener-chart
  

  Access your application using the provided external IP(from command output) or at : http://localhost:8080.

---

SMS Service Configuration

To configure the SMS service, you need to specify parameters related to the SMS provider in the application.properties file.

• Managed SMS Provider (Uses HttpSms API from https://httpsms.com/)

  • Generate API Key : https://httpsms.com/settings/
  • HttpSms API Docs : https://api.httpsms.com/

  3 lines
  Copy
  1sms.provider=managed
  2  managed.sms.api.key=your_managed_sms_api_key
  3  managed.sms.phone-number=123456789
  

• Self-hosted SMS Provider (Host our open source android-based SMS web gateway : https://api.httpsms.com/)

  4 lines
  Copy
  1sms.provider=selfhosted
  2selfhosted.gateway.url=https://your-smsgateway-url/index.php
  3selfhosted.device.id=your_device_id
  4selfhosted.hash=your_device_hash
  

---

App Health

Check application status from the /monitoring page at : http://localhost:8080/monitoring

Docs

Check application OpenAPI 3.0 compliant docs at: http://localhost:8080/docs-ui

---

Use Cases

1. Shorten URLs by visiting the URL Shortener page.
2. Access analytics for each shortened URL.
3. Create and manage bio pages in the Bio section.

---

Contributing

Contributions are welcome! Please follow the contribution guidelines.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

---

© Bitmutex Technologies | 2024