From 663fae5e5625b37fb2e73870af37d760e83e1a3f Mon Sep 17 00:00:00 2001 From: Devon Hillard Date: Mon, 30 Oct 2023 18:39:29 -0600 Subject: [PATCH] Write a good "How to use this to build your app" guide Fixes #28 --- QUICKSTART.md | 33 +++++++++++++++++++++++++++++++++ README.md | 5 +++++ 2 files changed, 38 insertions(+) create mode 100644 QUICKSTART.md diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..d706700 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,33 @@ +# Quickstart Guide + +## Prerequisites + - Java Development Kit (JDK) 17 or later + +## Quick Note + +This Framework is intended to be copied and used as a template for new projects. It is not intended to be used as a dependency. + +While it would be nice to vend this as a library through Maven or Gradle, I don't belive it's possible to do so. In order for this framework to be useful (for my needs) it needs to provide the front end pages, JS, and set Spring configurations. + +If anyone knows a way to do this as a dependancy, please let me knowm, or submit a PR. + + +## Getting Started + +1. Download this project as a zip file and extract it to a new folder. +2. Open the project in your favorite IDE. I use VSCode. +3. Copy the `src/main/resources/application-local.yml-example` file to `src/main/resources/application-local.yml` +4. Edit the `src/main/resources/application-local.yml` file to set your configurations for things like SMTP server, Facebook or Google OAuth information, etc. If you need to override any defaults from `application.yml` you can do so here. +5. Create the local database: `docker run -p 127.0.0.1:3306:3306 --name springuserframework -e MARIADB_ROOT_PASSWORD=springuserroot -e MARIADB_DATABASE=springuser -e MARIADB_USER=springuser -e MARIADB_PASSWORD=springuser -d mariadb:latest` +6. If you are using a public hostname for OAuth (Google or Facebook), you will need to setup an [ngrok tunnel](https://medium.com/@Demipo/exposing-a-local-spring-boot-app-with-ngrok-819250ef75f) or [CloudFlare tunnel](https://vitobotta.com/2022/02/27/free-ngrok-alternative-with-cloudflare-tunnels/) +7. Run the project. You can do this from the command line with `./gradlew bootRun` +8. Open a browser and go to `http://localhost:8080` to see the home page. +9. If things are working, you can now develop your own application on top of this framework + + +## Bugs, Gaps, Questions +If you find any issues, gaps in documentation or features, or have any questions, please open an issue on GitHub! + + + +Back to [README.md](README.md) diff --git a/README.md b/README.md index 00a62ed..f8b5720 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,11 @@ The framework provides support for the following features: ## How To Get Started +### Quickstart Guide +You can jump right in and get started by following the [Quickstart Guide](QUICKSTART.md). + +For more information, read on. + ### Configuring Your Local Environment There is an example configuration file in /src/main/resources called application-local.yml-example. By default this project's gradle bootRun command runs Spring using the "local" profile. So you can just copy that file to application-local.yml and replace the values (keys, URLs, etc..) with your values. If you are using a different profile to run (such as default) you will just need to ensure the same configs are in place in your active configuration file(s).