{"id":26219418,"url":"https://github.com/hngprojects/hng_boilerplate_java_web","last_synced_at":"2025-04-04T22:01:39.740Z","repository":{"id":249187732,"uuid":"827864278","full_name":"hngprojects/hng_boilerplate_java_web","owner":"hngprojects","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-02T22:33:34.000Z","size":3802,"stargazers_count":152,"open_issues_count":14,"forks_count":56,"subscribers_count":3,"default_branch":"dev","last_synced_at":"2025-03-28T21:01:29.859Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","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/hngprojects.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-07-12T14:43:12.000Z","updated_at":"2025-03-22T01:37:01.000Z","dependencies_parsed_at":"2025-02-26T14:25:16.093Z","dependency_job_id":"753dcabb-2be1-4098-b49d-3f1b32bd56ec","html_url":"https://github.com/hngprojects/hng_boilerplate_java_web","commit_stats":null,"previous_names":["hngprojects/hng_boilerplate_java_web"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hngprojects%2Fhng_boilerplate_java_web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hngprojects%2Fhng_boilerplate_java_web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hngprojects%2Fhng_boilerplate_java_web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hngprojects%2Fhng_boilerplate_java_web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hngprojects","download_url":"https://codeload.github.com/hngprojects/hng_boilerplate_java_web/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256093,"owners_count":20909240,"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","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":[],"created_at":"2025-03-12T14:17:56.118Z","updated_at":"2025-04-04T22:01:39.708Z","avatar_url":"https://github.com/hngprojects.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [App Name] Integration Guide\n\n## Overview of this project\n\n[Description]\n\n## Folder Structure\n\n```\n|--- .mvn\n|--- src\n|    |--- main\n|         |--- java\n|             |---hng_java_boilerplate\n|                 |---\u003cfeature implementations\u003e\n|                 |---Program.java\n|             |---utils\n|         |--- resources\n|             |--- static\n|             |--- templates\n|             |--- application.properties\n|    |--- test\n|         |--- java\n|             |---hng_java_boilerplate\n|                 |---\u003cimplementations tests\u003e\n|--- .gitignore\n|--- mvnw\n|--- mvnw.cmd\n|--- README.md\n```\n\n## Getting started\n\nEnsure you have your computer setup correctly for development by installing the following\n\n- Java 17 or higher\n- Install Java SDK/JDK\n- Use your favourite IDE or Text editor\n\n## Contribution Guide\n\n#### If you don't have git on your machine, [install it](https://docs.github.com/en/get-started/quickstart/set-up-git).\n\n## Fork this repository\n\nFork this repository by clicking on the fork button on the top of this page.\nThis will create a copy of this repository in your account.\n\n## Clone the repository\n\n\u003cimg align=\"right\" width=\"300\" src=\"https://firstcontributions.github.io/assets/Readme/clone.png\" alt=\"clone this repository\" /\u003e\n\nNow clone the forked repository to your machine. Go to your GitHub account, open the forked repository, click on the code button and then click the _copy to clipboard_ icon.\n\nOpen a terminal and run the following git command:\n\n```bash\ngit clone \"url you just copied\"\n```\n\nwhere \"url you just copied\" (without the quotation marks) is the url to this repository (your fork of this project). See the previous steps to obtain the url.\n\n\u003cimg align=\"right\" width=\"300\" src=\"https://firstcontributions.github.io/assets/Readme/copy-to-clipboard.png\" alt=\"copy URL to clipboard\" /\u003e\n\nFor example:\n\n```bash\ngit clone git@github.com:this-is-you/hng_project.git\n```\n\nwhere `this-is-you` is your GitHub username. Here you're copying the contents of the first-contributions repository on GitHub to your computer.\n\n## Create a branch\n\nChange to the repository directory on your computer (if you are not already there):\n\n```bash\ncd hng_project\n```\n\nNow create a branch using the `git switch` command:\n\n```bash\ngit switch -c your-new-branch-name\n```\n\nFor example:\n\n```bash\ngit switch -c add-alonzo-church\n```\n\n### Make Changes\n\nMake your changes to the codebase. Ensure your code follows the project's coding standards and guidelines.\n\n### Run Tests\n\nRun the existing tests to ensure your changes do not break anything. If you added new functionality, write corresponding tests and run them.\n\n## commit those changes\n\nNow open `Contributors.md` file in a text editor, add your name to it. Don't add it at the beginning or end of the file. Put it anywhere in between. Now, save the file.\n\n\u003cimg align=\"right\" width=\"450\" src=\"https://firstcontributions.github.io/assets/Readme/git-status.png\" alt=\"git status\" /\u003e\n\nIf you go to the project directory and execute the command `git status`, you'll see there are changes.\n\nAdd those changes to the branch you just created using the `git add` command:\n\n## Push changes to GitHub\n\nPush your changes using the command `git push`:\n\n```bash\ngit push -u origin your-branch-name\n```\n\nreplacing `your-branch-name` with the name of the branch you created earlier.\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003cstrong\u003eIf you get any errors while pushing, click here:\u003c/strong\u003e \u003c/summary\u003e\n\n- ### Authentication Error\n     \u003cpre\u003eremote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.\n  remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information.\n  fatal: Authentication failed for 'https://github.com/\u003cyour-username\u003e/first-contributions.git/'\u003c/pre\u003e\n  Go to [GitHub's tutorial](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) on generating and configuring an SSH key to your account.\n\n\u003c/details\u003e\n\n## Submit your changes for review into Staging\n\nIf you go to your repository on GitHub, you'll see a `Compare \u0026 pull request` button. Click on that button.\n\n\u003cimg style=\"float: right;\" src=\"https://firstcontributions.github.io/assets/Readme/compare-and-pull.png\" alt=\"create a pull request\" /\u003e\n\nNow submit the pull request.\n\n\u003cimg style=\"float: right;\" src=\"https://firstcontributions.github.io/assets/Readme/submit-pull-request.png\" alt=\"submit pull request\" /\u003e\n\nSoon your changes will be merged into the staging branch of this project. You will get a notification email once the changes have been merged.\n\n## Setup Instructions\n\n### 1. Clone the Repository\n\nFirst, clone the repository to your local machine using Git.\n\n```sh\ngit clone https://github.com/your-username/[app-name].git\ncd [app-name]\n```\n\n### 2. Install Dependencies\n\nOpening the project in your dev environment should automatically restore all your dependencies.\nYou can also install dependencies by running the following `mavin` command in your root folder.\n\n```sh\nmvn dependency:resolve\n```\n### 3. set up database\n- Ensure PostgreSQL is installed and running\n- Create a new database in the database\n`CREATE DATABASE {database_name}`\n- Flyway Migrations\n  - migration files should be placed in the `src/main/resources/db/migration` directory\n  - Each migration file should follow the naming convention `V\u003cversion\u003e__\u003cdescription\u003e.sql.` e.g\n    -  `V1__init_database.sql`\n    -  `V2__create_users_table.sql`\n\n  - sample migration file\n```sql\n-- V1__create_users_table.sql\nCREATE TABLE users (\nid VARCHAR(255) PRIMARY KEY,\nname VARCHAR(255) NOT NULL,\nemail VARCHAR(255) NOT NULL UNIQUE\n);\n\n-- V2__create_profiles_table.sql\nCREATE TABLE profiles (\nid VARCHAR(255) PRIMARY KEY,\nfirst_name VARCHAR(255),\nlast_name VARCHAR(255),\nphone VARCHAR(255),\navatar_url VARCHAR(255)\n);\n\n-- V3__create_products_table.sql\nCREATE TABLE products (\nid VARCHAR(255) PRIMARY KEY,\nname VARCHAR(255) NOT NULL,\ndescription TEXT,\nuser_id VARCHAR(255) NOT NULL,\nFOREIGN KEY (user_id) REFERENCES users(id)\n);\n\n-- V4__create_organisations_table.sql\nCREATE TABLE organisations (\nid VARCHAR(255) PRIMARY KEY,\nname VARCHAR(255) NOT NULL,\ndescription TEXT\n);\n\n-- Many-to-Many Relationship Table\nCREATE TABLE user_organisation (\nuser_id VARCHAR(255) NOT NULL,\norganisation_id VARCHAR(255) NOT NULL,\nPRIMARY KEY (user_id, organisation_id),\nFOREIGN KEY (user_id) REFERENCES users(id),\nFOREIGN KEY (organisation_id) REFERENCES organisations(id)\n);\n```\n\n  - update the `application.properties` file with your database credentials and configure flyway\n```html\n\u003c!-- database configuration--\u003e\nspring.datasource.url=jdbc:{connection_string}\nspring.datasource.username=your_username\nspring.datasource.password=your_password\n\n\u003c!-- flyway configuration--\u003e\nspring.flyway.enabled=true\nspring.flyway.locations=classpath:db/migration\nspring.flyway.user={database_username}\nspring.flyway.password={database_password}\n```\n  - Apply migrations\n  `./mvnw flyway:migrate`\n\n### 4. Run the Development Server\n\nPress `F5` on your keyboard to run the application in debug mode for your Vscode or use whatever your IDE requires (You may need to open a .java file to trigger this).\n\n### 5. Verify the Setup\n\nDepending on the IDE/code editor, you should be greeted with a Hello world text when you navigate to `localhost:8080`.\n\n#### test endpoint using curl or postman\n- using curl (user_one_id: id of the user created in the database) \n  `curl -X GET http://localhost:8080/api/v1/users/user_one_id`\n- Using Postman\n  - Open Postman\n  - Create a new GET request to curl -X GET http://localhost:8080/api/v1/users/user_one_id\n  - send the request and verify the response\n- Expected Response\n```json\n  {\n  \"name\": \"John Doe\",\n  \"id\": \"some-user-id\",\n  \"email\": \"johndoe@example.com\",\n  \"profile\": {\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"phone\": \"1234567890\",\n    \"avatar_url\": \"http://example.com/avatar.jpg\"\n   },\n  \"organisations\": [\n    {\n    \"org_id\": \"some-org-id-1\",\n    \"name\": \"Some Org\",\n    \"description\": \"Some Org Description\"\n    },\n    {\n    \"org_id\": \"some-other-org-id-2\",\n    \"name\": \"Some Other Org\",\n    \"description\": \"Some Other Org Description\"\n    }\n  ],\n  \"products\": [\n    {\n    \"product_id\": \"some-product-id\",\n    \"name\": \"Some Product\",\n    \"description\": \"Some Product Description\"\n    },\n    {\n    \"product_id\": \"some-other-product-id\",\n    \"name\": \"Some Other Product\",\n    \"description\": \"Some Other Product Description\"\n    }\n  ]\n }\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhngprojects%2Fhng_boilerplate_java_web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhngprojects%2Fhng_boilerplate_java_web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhngprojects%2Fhng_boilerplate_java_web/lists"}