{"id":26707311,"url":"https://github.com/aamitn/urlshortener","last_synced_at":"2025-10-06T20:05:40.893Z","repository":{"id":222554818,"uuid":"751495825","full_name":"aamitn/URLShortener","owner":"aamitn","description":"A powerful and scalable URL shortener with integrated bio pages built using Spring Boot.","archived":false,"fork":false,"pushed_at":"2024-03-02T16:02:39.000Z","size":135247,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T06:32:33.031Z","etag":null,"topics":["open-api-v3","spring-boot"],"latest_commit_sha":null,"homepage":"https://github.com/aamitn/URLShortener","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aamitn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-01T18:12:33.000Z","updated_at":"2024-12-08T05:37:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"60e1286e-0fe1-4a10-8a6d-8236a1ea5777","html_url":"https://github.com/aamitn/URLShortener","commit_stats":null,"previous_names":["aamitn/urlshortener"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/aamitn/URLShortener","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aamitn%2FURLShortener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aamitn%2FURLShortener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aamitn%2FURLShortener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aamitn%2FURLShortener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aamitn","download_url":"https://codeload.github.com/aamitn/URLShortener/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aamitn%2FURLShortener/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278671745,"owners_count":26025745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["open-api-v3","spring-boot"],"created_at":"2025-03-27T06:28:32.626Z","updated_at":"2025-10-06T20:05:40.873Z","avatar_url":"https://github.com/aamitn.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"## \u003cimg src=\"https://i.ibb.co/4MFScFw/tusc-logo.png\" width=\"20%\" alt=\"\"\u003e **TUSC - The URL Shortener Company**\n\n[![buddy pipeline](https://app.buddy.works/amitnandileo-2/urlshortener/pipelines/pipeline/483649/badge.svg?token=fb16d4ceb25aaee899aeebeb8f9d57239dd800defc2afb65a0176c36d32bd464)](https://app.buddy.works/amitnandileo-2/urlshortener/pipelines/pipeline/483649)  \n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)[![GitHub last commit](https://img.shields.io/github/last-commit/aamitn/URLShortener.svg)](https://github.com/aamitn/URLShortener/commits/main)[![GitHub issues](https://img.shields.io/github/issues/aamitn/URLShortener.svg)](https://github.com/aamitn/URLShortener/issues)[![GitHub pull requests](https://img.shields.io/github/issues-pr/aamitn/URLShortener.svg)](https://github.com/aamitn/URLShortener/pulls)[![GitHub contributors](https://img.shields.io/github/contributors/aamitn/URLShortener.svg)](https://github.com/aamitn/URLShortener/graphs/contributors)  \n[![Twitter](https://img.shields.io/twitter/url/https/github.com/yourusername/your-repo.svg?style=social)](https://twitter.com/intent/tweet?url=https%3A%2F%2Fgithub.com%2Faamitn%2FURLShortener\u0026text=Check%20out%20this%20awesome%20URL%20Shortener%20and%20Bio%20Page%20Application\u0026via=yourtwitterhandle)\n[![Docker Image Size](https://badgen.net/docker/size/trueosiris/godaddypy?icon=docker\u0026label=image%20size)](https://hub.docker.com/r/nmpl/shortener)\n\nAn enterprise-grade, powerful and scalable URL shortener with integrated bio pages built using Spring Boot.\n\n\u003ctable\u003e\u003ctbody\u003e\u003ctr\u003e\u003ctd\u003eMaven Package\u003c/td\u003e\u003ctd\u003e\u003ca href=\"https://github.com/aamitn/URLShortener/packages/2069528\"\u003eGithub Packages - com.bitmutex.shortener\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003ctr\u003e\u003ctd\u003eDocker Image\u003c/td\u003e\u003ctd\u003e\u003ca href=\"https://hub.docker.com/r/nmpl/shortener\"\u003eDockerHub - nmpl/shortener:latest\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/tbody\u003e\u003c/table\u003e\n\n## Table of Contents\n\n*   [Overview](#overview)\n*   [Features](#features)\n*   [Getting Started](#getting-started)\n    *   [Prerequisites](#prerequisites)\n    *   [Local Setup](#local-setup)\n    *   [Deployment](#deployment)\n    *   [Cloud Native Deployment](#cloud-native-deployment)\n*   [SMS Configuration](#sms-service-configuration)  \n*   [Use Cases](#use-cases)\n*   [Contributing](#contributing)\n*   [License](#license)\n***\n## Overview\n\nThis 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.\n\n## Features\n\n*   Shorten URLs and create custom short URLs.\n*   Integrated bio pages for users.\n*   Analytics tracking for each shortened URL.\n*   User management with registration, login, and profile updates.\n*   Subscription plans for premium features.\n*   Rate limiting to prevent abuse.\n*   Forgot password and username recovery functionality.\n*   OPEN API 3.0 Complaint REST API set, with extensive docs.\n\n## Tech Stack:\n\n* Java (JDK 21): The core programming language for the application.\n* Maven 3: A build automation and project management tool. Used for managing dependencies and building the application.\n* MySQL/Mariadb: Relational database management system used for data storage.\n* Spring Boot: A framework that simplifies the development of Java applications, providing convention over configuration and a variety of built-in features.\n* Logger (Logback): Logback is a logging framework for Java applications. It's the default logging framework in Spring Boot.\n* 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.\n* 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.\n* RESTful API: A standard architectural style for building web services. The application provides RESTful APIs for various functionalities.\n* OpenAPI 3.0: A specification for building APIs that allows for describing, producing, consuming, and visualizing RESTful web services.\n* Docker: A platform for developing, shipping, and running applications in containers. Used for containerizing the application.\n* Git: A distributed version control system used for tracking changes in the source code.\n* Kubernetes: A container orchestration platform used for automating the deployment, scaling, and management of containerized applications.\n* Swagger UI: A tool that helps design, build, document, and consume RESTful APIs. It's often used with OpenAPI specifications.\n* Tailwind CSS: A utility-first CSS framework that makes it easy to design and build modern, responsive user interfaces.\n* Flowbite: A design system and UI toolkit for building responsive web applications.\n\n***\n\n## Getting Started\n\n### Prerequisites\n\nBefore you begin, ensure you have the following installed:\n\n*   Java (JDK 11 or later)\n*   Maven\n*   MySQL\n*   Your favorite IDE (IntelliJ, Eclipse, etc.)\n\n\n###  1-Click Local Installation \u003ca href=\"https://github.com/aamitn/URLShortener/releases/download/final/install.cmd\"\u003eWindows\u003c/a\u003e | \u003ca href=\"https://github.com/aamitn/URLShortener/releases/download/final/install.sh\"\u003eLinux\u003c/a\u003e \n\n### Windows\n1. Open a Command Prompt with administrator privileges.\n2. Navigate to the project's `installers` folder.\n3. Run the `install.bat` file by double-clicking on it or using the following command:\n   ```batch\n   install.bat\n\n### Linux\n1. Navigate to the project's installers folder.\n2. Run the `install.sh` using the following command:\n   ```bash\n   chmod +x install.sh\n   ./install.sh\n3. Follow the on-screen instructions.\n\n##### Finally, Select Application Server : Tomcat/Wildfly\n\n***\n\n### Local Setup\n\n1.  Clone the repository:\n\n    ```plaintext\n    git clone https://github.com/aamitn/URLShortener.git\n    cd URLShortener\n    ```\n\n2.  **Apply the Database Schema:**\n\n    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.\n\n    ```plaintext\n    mysql -u your_username -p{your_password} \u003c create.sql\n    ```\n    \n3.  Update the application.properties file:\n\n    * Update the `application.properties` file in the src/main/resources directory with your application configuration.\n\n4.  Build and run the application: \n\n    ```plaintext\n    mvn spring-boot:run\n    ```\n\n5.  Access the application at http://localhost:8080\n\n***\n\n### Deployment Setup\n\n1.  **Build a deployable WAR:**\n\n    ```plaintext\n    mvn clean install\n    ```\n\n2.  **Deploy the WAR:**\n    *   **Option 1: Manual Deployment**\n\n        Deploy the generated WAR file to your Tomcat server. Copy the WAR file to the `webapps` directory of your Tomcat installation.\n\n        ```plaintext\n        cp target/shorten.war /path/to/tomcat/webapps/\n        ```\n\n    *   **Option 2: Web Interface Upload**\n\n        Alternatively, if your Tomcat server provides a web interface for WAR file deployment, follow these steps:\n\n        *   Access the Tomcat Manager web interface at `http://localhost:8080/manager/html` (replace with your Tomcat server address).\n        *   Log in with your Tomcat manager credentials.\n        *   Navigate to the \"WAR file to deploy\" section.\n        *   Choose the `shortener.war` file using the file upload button.\n        *   Click the \"Deploy\" button.\n3.  **Configure Variables on deployed war:**\n\n    Set environment variables for cloud-specific settings.\n\n4.  **Adjust Tomcat Configuration (Important):**\n\n    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 `\u003cHost\u003e` section:\n\n    ```xml\n    \u003cContext path=\"\" docBase=\"shorten\" reloadable=\"true\"\u003e\u003c/Context\u003e\n    ```\n\n    This ensures that the application runs on the root context path. Adjust the `docBase` attribute according to your deployment directory.\n\n5.  **Start Tomcat:**\n\n    Start your Tomcat server.\n\n    ```plaintext\n    /path/to/tomcat/bin/startup.sh   # for Linux\n    /path/to/tomcat/bin/startup.bat  # for Windows\n    ```\n\n    Access the application at `http://localhost:8080/`.\n\n6.  **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 :\n\n    ```plaintext\n    vi /path/to/tomcat/webapps/shortener/WEB-INF/classes/application.properties\n    ```\n***\n\n### Cloud Native Deployment\n\nTo deploy the URL Shortener application on your cloud environment, follow the steps below:\n\n**Prerequisites**\n\n*   [Docker](https://www.docker.com/get-started)\n*   [Docker Compose](https://docs.docker.com/compose/install/)\n*   [Kubernetes/K8s](https://kubernetes.io/docs/setup/)\n*   [Minikube](https://minikube.sigs.k8s.io/docs/start/)\n*   [Helm](https://helm.sh/docs/intro/install/)\n\n1.  **Clone the Repository:**\n\n    ```plaintext\n    git clone https://github.com/your-username/URLShortener.git\n    cd URLShortener\n    ```\n2.  ***Deploy Using Docker***\n\n*    Build and Run Your Own Image:\n\n        ```plaintext\n        docker build -t shortener:latest .\n        docker run -p 8080:8080 -p 3306:3306 shortener:latest\n        ```\n     \n\u003cp style=\"text-align: center;\"\u003e OR \u003c/p\u003e\n\n*  Use Our Pre-built Image with Docker Compose:\n\n    ```plaintext\n    docker compose build\n    docker compose up\n    ```\n\n*   Customizing Docker Compose Configuration:\n\n    In the `docker-compose.yml` file, you can customize the build source for the Shortener service:\n\n    ```plaintext\n    # Build from docker hub image .Comment/Uncomment Below\n    image: nmpl/shortener:latest\n    \n     # Build from local Dockerfile.Comment/Uncomment Below\n     #   build:\n     #     context: .\n     #     dockerfile: Dockerfilekerfile\n    ```\n\n    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.\n\n\n3.  ***Deploy Using K8s***\n\n*   Setup Kubernetes Deployment and Service:\n\n     ```plaintext\n     cd k8s\n     kubectl apply -f deploy.yaml,service.yaml,data.yaml\n    ```\n\n*   Expose the K8s service:\n\n     ```plaintext\n     kubectl port-forward service/shortener-app 8080:8080   \n    ```\n    Access Application at http://localhost:8080\n    \u003ccenter\u003eOR\u003c/center\u003e\n    If you're using minikube, run the below command to run the app:\n\n    ```plaintext\n     minikube service shortener-app   \n    ```\n    \n*    Use the following command to monitor the deployment:\n\n    ```plaintext\n     kubectl get pods\n    ```\n   \n\n4.  ***Deploy Using Helm Chart***\n\n*   Create Deployment from helm chart named \"instance\" , with a service named \"instance-shortener-chart\" :\n\n     ```plaintext\n     cd k8s\n     helm install instance shortener-chart/ --values shortener-chart/values.yaml\n    ```\n\n*   Expose the K8s service:\n\n     ```plaintext\n     kubectl port-forward service/instance-shortener-chart 8080:8080\n    ```\n\n    \u003ccenter\u003eOR\u003c/center\u003e\n    If you're using minikube, run the below command to run the app:**\n\n    ```plaintext\n     minikube service shortener-app   \n    ```\n\n*    Use the following command to monitor the deployment:\n\n    ```plaintext\n     kubectl get pods\n    ```\n\n    Wait until the pod is in the \"Running\" state.\n\n*   Access the Application\n\n    Depending on your Kubernetes setup, you might need to get the external IP of the service:\n\n    ```plaintext\n     kubectl get service instance-shortener-chart\n    ```\n\n    Access your application using the provided external IP(from command output) or at : http://localhost:8080.\n\n***\n\n### SMS Service Configuration\n\nTo configure the SMS service, you need to specify parameters related to the SMS provider in the `application.properties` file.\n\n* #### Managed SMS Provider (Uses HttpSms API from https://httpsms.com/)\n  * Generate API Key : https://httpsms.com/settings/\n  * HttpSms API Docs : https://api.httpsms.com/\n\n  ```properties\n    sms.provider=managed\n    managed.sms.api.key=your_managed_sms_api_key\n    managed.sms.phone-number=123456789\n  \n* #### Self-hosted SMS Provider (Host our open source android-based SMS web gateway : https://api.httpsms.com/)\n\n    ```properties\n    sms.provider=selfhosted\n    selfhosted.gateway.url=https://your-smsgateway-url/index.php\n    selfhosted.device.id=your_device_id\n    selfhosted.hash=your_device_hash\n\n***\n  \n### App Health\nCheck application status from the /monitoring page at :  http://localhost:8080/monitoring\n### Docs\nCheck application OpenAPI 3.0 compliant docs at: http://localhost:8080/docs-ui\n\n***\n\n### Use Cases\n\n1.  Shorten URLs by visiting the URL Shortener page.\n2.  Access analytics for each shortened URL.\n3.  Create and manage bio pages in the Bio section.\n\n***\n\n### Contributing\n\nContributions are welcome! Please follow the contribution guidelines.\n\n### License\n\nThis project is licensed under the MIT License - see the LICENSE.md file for details.\n\n***\n\u003cp style=\"text-align: center;\"\u003e\u0026copy; Bitmutex Technologies | 2024\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faamitn%2Furlshortener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faamitn%2Furlshortener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faamitn%2Furlshortener/lists"}