|
1 | 1 | # Tokyo Python Society Site - Overview Proposal |
2 | 2 |
|
3 | | -## Tools Used in Development |
| 3 | +# Getting Started |
4 | 4 |
|
5 | | -Language: Python 3.10 |
6 | | -Libraries: FastAPI |
7 | | -Database: Postgres (version to be determined) (10/29 currently not in use, installation not required) |
8 | | -Formatter: Black 22.8.0 |
9 | | -Testing: PyTest |
10 | | -Front: JavaScript, Reactjs, Nextjs |
| 5 | +## Requirements: |
11 | 6 |
|
12 | | -## Frontend |
13 | | -The frontend is compiled and bundled with Nextjs from a barebones template design. |
| 7 | +Python 3.10 |
| 8 | +NodeJS v14.15.0 and npm |
14 | 9 |
|
15 | | -For more information for design decisions and implementation please see `front/README.md` |
| 10 | +# Setting up the Backend |
16 | 11 |
|
17 | | -## Branch Information |
| 12 | +## Step 1 |
18 | 13 |
|
19 | | -- main |
20 | | -As of 10/29 we are committing directly to main, as the content is not yet ready to be opened up to the public to be worked on. |
| 14 | +Clone repository |
21 | 15 |
|
22 | | -- production |
23 | | -This is the production branch. Changes to this branch will ultimately affect the live site. |
24 | | -10/22: As of now, there is no production branch. It will not be ready until the site is at least somewhat presentable |
| 16 | +`git clone git@github.com:TokyoPython/tokyo-python-society-site.git` |
25 | 17 |
|
26 | | -- dev |
27 | | -This is the development branch. Changes to this branch are local. |
| 18 | +## Step 2 |
28 | 19 |
|
29 | | -## Setting Up the Environment (Back) |
| 20 | +Create Python virtual environment within the project root directory |
30 | 21 |
|
31 | | -1. Install Python 3.10 |
| 22 | +```bash |
| 23 | +$ cd tokyo-python-society-site |
32 | 24 |
|
33 | | -2. Create a virtual environment to install dependencies. |
34 | | -*I recommend venv as it is packaged with python.* |
35 | | -(venv documentation here https://docs.python.org/3/library/venv.html) |
36 | | - |
37 | | -``` |
38 | | -Example using venv (Windows) |
| 25 | +# Windows |
39 | 26 |
|
40 | 27 | $ python -m venv venv |
41 | 28 | $ source venv/Scripts/activate |
42 | 29 |
|
43 | | -Example using venv (MacOS/Linux) |
| 30 | +# MacOS/Linux |
44 | 31 |
|
45 | 32 | $ python -m venv venv |
46 | 33 | $ source venv/bin/activate |
| 34 | +``` |
| 35 | + |
| 36 | +If this succeeds, you should see (venv) or an indicator that you are in a virtual environment. |
| 37 | + |
| 38 | +## Step 3 - Install Dependencies |
47 | 39 |
|
| 40 | +`pip install -r requirements.txt` |
| 41 | + |
| 42 | +## Step 4 - Set Environment Variables |
| 43 | + |
| 44 | +In the same `back` directory, create an `.env` file and put environment variables into it. The bare minimum you will need to place inside of it is: |
| 45 | + |
| 46 | +```bash |
| 47 | +MEETUP_GRAPHQL_URL="https://api.meetup.com/gql" |
48 | 48 | ``` |
49 | 49 |
|
50 | | -After the above two lines, you should see (venv) or something similar in your terminal. |
| 50 | +## Step 5 - Check that the backend runs successfully |
| 51 | + |
| 52 | +In `back`, run the command `uvicorn main:app --reload` |
| 53 | + |
| 54 | +Side note: as the project grows, we may want to add other flags or commands to the above command. In order to avoid having to remember the command, there is also a `run.sh` script that can also optionally be run instead of `uvicorn main:app --reload` |
51 | 55 |
|
52 | | -3. While inside your virtual environment, run `pip install -r requirements.txt` |
| 56 | +Visit [http://127.0.0.1:8000/](http://127.0.0.1:8000/) from a browser or send a get request to the above URL. If you get a response with data |
53 | 57 |
|
54 | | -This will install everything needed to get the backend running. The core app consists of: |
55 | | -- Pytest |
56 | | -- FastAPI |
57 | | -- uvicorn |
58 | | -- psycopg2 |
59 | | -- sqlmodel |
60 | | -- dotenv |
| 58 | +```bash |
| 59 | +{ |
| 60 | +Hello: "World" |
| 61 | +} |
| 62 | +``` |
61 | 63 |
|
62 | | -Everything else seen in requirements.txt are dependencies of the above. |
| 64 | +You have successfully got the backend up and running. You may now begin contributing to the backend. |
63 | 65 |
|
64 | | -3. Install the appropriate code formatter. See `Tools` above for the formatter we use. |
| 66 | +# Setting up the Frontend |
65 | 67 |
|
66 | | -4. Set an .env file. The app will not run without this. It is not stored in source control for security reasons. Please see `back/readme.md` for more information. |
| 68 | +## Step 1 - Install Front Dependencies |
67 | 69 |
|
68 | | -## Running the App (Backend) |
| 70 | +Move to the front directory and run `npm install` |
69 | 71 |
|
70 | | -`uvicorn main:app --reload` |
| 72 | +```bash |
| 73 | +$ cd front |
| 74 | +$ npm install |
| 75 | +``` |
71 | 76 |
|
72 | | -## Checking to see that the app works as intended (Back) |
| 77 | +This will produce a `node_modules` directory with all dependencies. |
73 | 78 |
|
74 | | -Please complete the above steps before moving here. |
| 79 | +## Step 2 - Run the project in dev mode |
75 | 80 |
|
76 | | -Visit `http://127.0.0.1:8000` and you should see {"Hello": "World"} as a JSON response. If you do not, please ask the Python Society group for troubleshooting help. |
| 81 | +`npm run dev` |
77 | 82 |
|
78 | | -If you have gotten this far, then your backend has been set up for development. |
| 83 | +To check that the project runs successfully, go to [`http://localhost:3000/`](http://localhost:3000/) |
79 | 84 |
|
80 | | -## Seeing the endpoints |
| 85 | +## Finished |
81 | 86 |
|
82 | | -`http://127.0.0.1:8000/docs` |
| 87 | +The frontend and backend are successfully connected if there is meetup event information at the bottom of the page. It should be viewable even if you are running both the back and frontend locally. |
83 | 88 |
|
84 | | -^ Provided by Swagger UI |
| 89 | +You are now ready to begin developing on this project. |
85 | 90 |
|
86 | | -## Alternative API docs |
| 91 | +The `production` branch is the live production version of the site. When making changes and adding features, be sure to create a branch from `production`. |
87 | 92 |
|
88 | | -`http://127.0.0.1:8000/redoc` |
| 93 | +## Extra Information |
89 | 94 |
|
| 95 | +## Tools Used in Development |
90 | 96 |
|
| 97 | +Language: Python 3.10 |
| 98 | +Libraries: FastAPI |
| 99 | +Database: Postgres (version to be determined) (10/29 currently not in use, installation not required) |
| 100 | +Formatter: Black 22.8.0 |
| 101 | +Testing: PyTest |
| 102 | +Front: JavaScript, Reactjs, Nextjs |
| 103 | + |
| 104 | +## Frontend |
| 105 | +The frontend is compiled and bundled with Nextjs from a barebones template design. |
| 106 | + |
| 107 | +## Branch Information |
91 | 108 |
|
| 109 | +- production |
| 110 | +This is the production branch. Changes to this branch will ultimately affect the live site. It is currently locked down and must be modified via pull requests. A PR will trigger a github actions CI CD script where a build test happens. If build succeeds, merging to production is possible. Upon merge, another CI CD script takes the production bundle and uploads it to the live server. |
92 | 111 |
|
93 | | -## Setting Up the Environment (Front) |
94 | | -Create a .env.local file at `/front` and add `MEETUP_URL=http://localhost:8000` to the environment file. |
| 112 | +- dev |
| 113 | +As of 11/16/2022 there is no staging environment. I suppose the site won't get so complicated as to need both staging and production, however, things may change in the near future depending on how we want to evolve the web application. |
95 | 114 |
|
96 | | -The app will not work without being able to access the MEETUP_URL endpoint. |
| 115 | +## Viewing the endpoints |
97 | 116 |
|
98 | | -From the /front directory run `npm install` |
| 117 | +`http://127.0.0.1:8000/docs` |
99 | 118 |
|
100 | | -## Running the App (Front) |
101 | | -For development, run `npm run dev` |
102 | 119 |
|
103 | | -Then visit `http://localhost:3000` and verify that the page successfully loads. |
| 120 | +## Alternative API docs |
104 | 121 |
|
105 | | -The frontend and backend are successfully connected if there is meetup event information at the bottom of the page. |
| 122 | +`http://127.0.0.1:8000/redoc` |
0 commit comments