From ce042afd22924f0286fef0b8be745c931ba3f669 Mon Sep 17 00:00:00 2001 From: Terence Lo Date: Fri, 28 Mar 2025 17:55:46 -0700 Subject: [PATCH] add quickstart environments guide to docs --- mkdocs/docs/developer/devops.md | 2 + mkdocs/docs/developer/installation.md | 9 +- mkdocs/docs/developer/quickstart-guide.md | 120 ++++++++++++++++++++++ mkdocs/docs/index.md | 2 +- mkdocs/mkdocs.yml | 1 + 5 files changed, 129 insertions(+), 5 deletions(-) create mode 100644 mkdocs/docs/developer/quickstart-guide.md diff --git a/mkdocs/docs/developer/devops.md b/mkdocs/docs/developer/devops.md index 1ea17704..68014d91 100644 --- a/mkdocs/docs/developer/devops.md +++ b/mkdocs/docs/developer/devops.md @@ -117,6 +117,8 @@ Of note, however, is the `dev.env.example` file. This file is only a sample, but #### Staging +You can view the staging environment with the following URL: [https://civictechjobs-stage.vrms.io/](https://civictechjobs-stage.vrms.io/) + The main stage file is `docker-compose.stage.yml`. This docker compose file sets up a staging environment in our local machine. The following is a brief overview of how the stage environment is set up: diff --git a/mkdocs/docs/developer/installation.md b/mkdocs/docs/developer/installation.md index 1ef1f274..414ee17d 100644 --- a/mkdocs/docs/developer/installation.md +++ b/mkdocs/docs/developer/installation.md @@ -126,7 +126,8 @@ This will utilize superuser permissions to change the user and group ownership o [Git Documentation](https://git-scm.com/doc)
[Docker Documentation](https://docs.docker.com/)
-[Frontend Architecture](https://hackforla.github.io/CivicTechJobs/developer/frontend/)
-[Backend Architecture](https://hackforla.github.io/CivicTechJobs/developer/backend/)
-[DevOps Architecture](https://hackforla.github.io/CivicTechJobs/developer/devops/)
-[GitHub Architecture](https://hackforla.github.io/CivicTechJobs/developer/backend/)
+[Quickstart Guide](developer/quickstart-guide)
+[Frontend Architecture](developer/frontend/)
+[Backend Architecture](developer/backend/)
+[DevOps Architecture](developer/devops/)
+[GitHub Architecture](developer/backend/)
diff --git a/mkdocs/docs/developer/quickstart-guide.md b/mkdocs/docs/developer/quickstart-guide.md new file mode 100644 index 00000000..29a3b587 --- /dev/null +++ b/mkdocs/docs/developer/quickstart-guide.md @@ -0,0 +1,120 @@ +# Quickstart Guide + +This is a quickstart guide with instructions for how to get the various environments of the application up and running on your machine. + +Before doing any of these, make sure to first follow the [Installation Instructions](developer/installation/). + +## How to run the app in development mode + +First, make sure that `dev.env` is in the `dev` folder with the correct variables. + +Start the application in development mode: +```sh +docker compose up --watch +``` + +Test client with this URL: +``` +http://localhost:5175 +``` + +Test server with these URLs: +``` +http://localhost:8000/api/opportunities/ + +http://localhost:8000/api/healthcheck +``` +- If you request a non-existent api endpoint, eg. `localhost:8000/api/asdf`, it should return an API error response JSON: + - `{"error": "API endpoint not found", "status_code": 404, "message": "The requested API endpoint does not exist"}` + +## Run the app in dev mode without Docker + +Make sure you have python, poetry, node.js, and npm installed on your machine. + +Steps to run the **backend** without docker: + +1. In a terminal, navigate to the backend folder with `cd backend`. +2. Inside this folder, run the backend dev server start command below. +3. The server should be running on `localhost:8000` now. + +Backend dev server start command: +```sh +poetry run python manage.py runserver localhost:8000 +``` + +
+ +Steps to run the **frontend** without docker: + +1. In a separate terminal, navigate to the frontend folder with `cd frontend`. +2. Inside this folder, run the frontend dev server start command below. +3. The client dev server should be running on `localhost:5175` now. + +Frontend dev server start command: +```sh +npm run dev +``` + +## Local Django ADMIN url and credentials + +Use the below to log in to your local django server admin portal: + +``` +http://localhost:8000/admin/ +``` +- This should work with and without docker + +Create an admin user with: +``` +python manage.py createsuperuser +``` +- It will prompt you to enter a username, email, and password to create an admin user. Make sure to write these down +- You can now use these credentials to log into your local server's admin portal. +- These credentials are saved into your local postgres instance database, so if this data ever gets deleted or reset, you will have to create an admin user again. +- Reference: [Writing your first Django app, part 2 | Django documentation | Django](https://docs.djangoproject.com/en/5.1/intro/tutorial02/#introducing-the-django-admin) + + +## Mkdocs + +Start mkdocs development server: + +```sh +docker compose -f docker-compose.docs.yml up --watch +``` + +- Test with: `http://localhost:8005/CivicTechJobs/` + + +## Backend - Linting script + +Run these commands inside the `/backend` folder, in the following order: + +``` +poetry install +poetry run isort . +poetry run black . +poetry run flake8 +``` + +- These should ideally be run before making a PR +- `isort`: sorts the import statements +- `black`: automatically formats python code +- `flake8`: lints python code + + +## Staging environment + +You can view the staging deployment with the following URL: [https://civictechjobs-stage.vrms.io/](https://civictechjobs-stage.vrms.io/) + +How to run the stage environment locally: + +1. Make sure you have a `stage.env` file inside the `/stage` folder of your local repository. It should be configured with the correct variables. +2. Run the staging environment in your local machine: + +``` +docker compose -f docker-compose.stage.yml up +``` + +Notes: +- [Feature: Set up stage environment in docker by LoTerence · Pull Request #613 · hackforla/CivicTechJobs · GitHub](https://github.com/hackforla/CivicTechJobs/pull/613) + diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md index a257179f..ae2e653d 100644 --- a/mkdocs/docs/index.md +++ b/mkdocs/docs/index.md @@ -20,7 +20,7 @@ CTJ will tackle key challenges in project recruitment and organizational sustain Yes, there are recruitment issues on project boards. However, the process is cumbersome and involves multiple steps to match candidates with the right roles. -Read more about what lead up to us developing this project, at our [History](History) page. +Read more about what lead up to us developing this project, at our [History](misc/history) page. ### So how is this different? diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index e8fce130..d08ce736 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -30,6 +30,7 @@ nav: - GitHub Architecture: developer/github.md - Git branch Structure: developer/git-branch-structure.md - Installation Instructions: developer/installation.md + - Quickstart Guide: developer/quickstart-guide.md - MkDocs Architecture: developer/mkdocs-architecture.md - MkDocs - Documentation Guide: developer/mkdocs-guide.md - MkDocs - How to Edit: developer/mkdocs-edit-instructions.md