|
1 |
| -# Full Stack FastAPI Template |
2 |
| - |
3 |
| -<a href="https://github.com/fastapi/full-stack-fastapi-template/actions?query=workflow%3ATest" target="_blank"><img src="https://github.com/fastapi/full-stack-fastapi-template/workflows/Test/badge.svg" alt="Test"></a> |
4 |
| -<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/fastapi/full-stack-fastapi-template" target="_blank"><img src="https://coverage-badge.samuelcolvin.workers.dev/fastapi/full-stack-fastapi-template.svg" alt="Coverage"></a> |
5 |
| - |
6 |
| -## Technology Stack and Features |
7 |
| - |
8 |
| -- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) for the Python backend API. |
9 |
| - - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) for the Python SQL database interactions (ORM). |
10 |
| - - 🔍 [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management. |
11 |
| - - 💾 [PostgreSQL](https://www.postgresql.org) as the SQL database. |
12 |
| -- 🚀 [React](https://react.dev) for the frontend. |
13 |
| - - 💃 Using TypeScript, hooks, Vite, and other parts of a modern frontend stack. |
14 |
| - - 🎨 [Chakra UI](https://chakra-ui.com) for the frontend components. |
15 |
| - - 🤖 An automatically generated frontend client. |
16 |
| - - 🧪 [Playwright](https://playwright.dev) for End-to-End testing. |
17 |
| - - 🦇 Dark mode support. |
18 |
| -- 🐋 [Docker Compose](https://www.docker.com) for development and production. |
19 |
| -- 🔒 Secure password hashing by default. |
20 |
| -- 🔑 JWT (JSON Web Token) authentication. |
21 |
| -- 📫 Email based password recovery. |
22 |
| -- ✅ Tests with [Pytest](https://pytest.org). |
23 |
| -- 📞 [Traefik](https://traefik.io) as a reverse proxy / load balancer. |
24 |
| -- 🚢 Deployment instructions using Docker Compose, including how to set up a frontend Traefik proxy to handle automatic HTTPS certificates. |
25 |
| -- 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions. |
26 |
| - |
27 |
| -### Dashboard Login |
28 |
| - |
29 |
| -[](https://github.com/fastapi/full-stack-fastapi-template) |
30 |
| - |
31 |
| -### Dashboard - Admin |
32 |
| - |
33 |
| -[](https://github.com/fastapi/full-stack-fastapi-template) |
34 |
| - |
35 |
| -### Dashboard - Create User |
36 |
| - |
37 |
| -[](https://github.com/fastapi/full-stack-fastapi-template) |
38 |
| - |
39 |
| -### Dashboard - Items |
40 |
| - |
41 |
| -[](https://github.com/fastapi/full-stack-fastapi-template) |
42 |
| - |
43 |
| -### Dashboard - User Settings |
44 |
| - |
45 |
| -[](https://github.com/fastapi/full-stack-fastapi-template) |
46 |
| - |
47 |
| -### Dashboard - Dark Mode |
48 |
| - |
49 |
| -[](https://github.com/fastapi/full-stack-fastapi-template) |
50 |
| - |
51 |
| -### Interactive API Documentation |
52 |
| - |
53 |
| -[](https://github.com/fastapi/full-stack-fastapi-template) |
54 |
| - |
55 |
| -## How To Use It |
56 |
| - |
57 |
| -You can **just fork or clone** this repository and use it as is. |
58 |
| - |
59 |
| -✨ It just works. ✨ |
60 |
| - |
61 |
| -### How to Use a Private Repository |
62 |
| - |
63 |
| -If you want to have a private repository, GitHub won't allow you to simply fork it as it doesn't allow changing the visibility of forks. |
64 |
| - |
65 |
| -But you can do the following: |
66 |
| - |
67 |
| -- Create a new GitHub repo, for example `my-full-stack`. |
68 |
| -- Clone this repository manually, set the name with the name of the project you want to use, for example `my-full-stack`: |
69 |
| - |
70 |
| -```bash |
71 |
| -git clone [email protected]:fastapi/full-stack-fastapi-template.git my-full-stack |
72 |
| -``` |
73 |
| - |
74 |
| -- Enter into the new directory: |
75 |
| - |
76 |
| -```bash |
77 |
| -cd my-full-stack |
78 |
| -``` |
79 |
| - |
80 |
| -- Set the new origin to your new repository, copy it from the GitHub interface, for example: |
81 |
| - |
82 |
| -```bash |
83 |
| -git remote set-url origin [email protected]:octocat/my-full-stack.git |
84 |
| -``` |
85 |
| - |
86 |
| -- Add this repo as another "remote" to allow you to get updates later: |
87 |
| - |
88 |
| -```bash |
89 |
| -git remote add upstream [email protected]:fastapi/full-stack-fastapi-template.git |
90 |
| -``` |
91 |
| - |
92 |
| -- Push the code to your new repository: |
93 |
| - |
94 |
| -```bash |
95 |
| -git push -u origin master |
96 |
| -``` |
97 |
| - |
98 |
| -### Update From the Original Template |
99 |
| - |
100 |
| -After cloning the repository, and after doing changes, you might want to get the latest changes from this original template. |
101 |
| - |
102 |
| -- Make sure you added the original repository as a remote, you can check it with: |
103 |
| - |
104 |
| -```bash |
105 |
| -git remote -v |
106 |
| - |
107 |
| -origin [email protected]:octocat/my-full-stack.git (fetch) |
108 |
| -origin [email protected]:octocat/my-full-stack.git (push) |
109 |
| -upstream [email protected]:fastapi/full-stack-fastapi-template.git (fetch) |
110 |
| -upstream [email protected]:fastapi/full-stack-fastapi-template.git (push) |
111 |
| -``` |
112 |
| - |
113 |
| -- Pull the latest changes without merging: |
114 |
| - |
115 |
| -```bash |
116 |
| -git pull --no-commit upstream master |
117 |
| -``` |
118 |
| - |
119 |
| -This will download the latest changes from this template without committing them, that way you can check everything is right before committing. |
120 |
| - |
121 |
| -- If there are conflicts, solve them in your editor. |
122 |
| - |
123 |
| -- Once you are done, commit the changes: |
124 |
| - |
125 |
| -```bash |
126 |
| -git merge --continue |
127 |
| -``` |
128 |
| - |
129 |
| -### Configure |
130 |
| - |
131 |
| -You can then update configs in the `.env` files to customize your configurations. |
132 |
| - |
133 |
| -Before deploying it, make sure you change at least the values for: |
134 |
| - |
135 |
| -- `SECRET_KEY` |
136 |
| -- `FIRST_SUPERUSER_PASSWORD` |
137 |
| -- `POSTGRES_PASSWORD` |
138 |
| - |
139 |
| -You can (and should) pass these as environment variables from secrets. |
140 |
| - |
141 |
| -Read the [deployment.md](./deployment.md) docs for more details. |
142 |
| - |
143 |
| -### Generate Secret Keys |
144 |
| - |
145 |
| -Some environment variables in the `.env` file have a default value of `changethis`. |
146 |
| - |
147 |
| -You have to change them with a secret key, to generate secret keys you can run the following command: |
148 |
| - |
149 |
| -```bash |
150 |
| -python -c "import secrets; print(secrets.token_urlsafe(32))" |
151 |
| -``` |
152 |
| - |
153 |
| -Copy the content and use that as password / secret key. And run that again to generate another secure key. |
154 |
| - |
155 |
| -## How To Use It - Alternative With Copier |
156 |
| - |
157 |
| -This repository also supports generating a new project using [Copier](https://copier.readthedocs.io). |
158 |
| - |
159 |
| -It will copy all the files, ask you configuration questions, and update the `.env` files with your answers. |
160 |
| - |
161 |
| -### Install Copier |
162 |
| - |
163 |
| -You can install Copier with: |
164 |
| - |
165 |
| -```bash |
166 |
| -pip install copier |
167 |
| -``` |
168 |
| - |
169 |
| -Or better, if you have [`pipx`](https://pipx.pypa.io/), you can run it with: |
170 |
| - |
171 |
| -```bash |
172 |
| -pipx install copier |
173 |
| -``` |
174 |
| - |
175 |
| -**Note**: If you have `pipx`, installing copier is optional, you could run it directly. |
176 |
| - |
177 |
| -### Generate a Project With Copier |
178 |
| - |
179 |
| -Decide a name for your new project's directory, you will use it below. For example, `my-awesome-project`. |
180 |
| - |
181 |
| -Go to the directory that will be the parent of your project, and run the command with your project's name: |
182 |
| - |
183 |
| -```bash |
184 |
| -copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust |
185 |
| -``` |
186 |
| - |
187 |
| -If you have `pipx` and you didn't install `copier`, you can run it directly: |
188 |
| - |
189 |
| -```bash |
190 |
| -pipx run copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust |
191 |
| -``` |
192 |
| - |
193 |
| -**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/fastapi/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py) that updates your `.env` files. |
194 |
| - |
195 |
| -### Input Variables |
196 |
| - |
197 |
| -Copier will ask you for some data, you might want to have at hand before generating the project. |
198 |
| - |
199 |
| -But don't worry, you can just update any of that in the `.env` files afterwards. |
200 |
| - |
201 |
| -The input variables, with their default values (some auto generated) are: |
202 |
| - |
203 |
| -- `project_name`: (default: `"FastAPI Project"`) The name of the project, shown to API users (in .env). |
204 |
| -- `stack_name`: (default: `"fastapi-project"`) The name of the stack used for Docker Compose labels and project name (no spaces, no periods) (in .env). |
205 |
| -- `secret_key`: (default: `"changethis"`) The secret key for the project, used for security, stored in .env, you can generate one with the method above. |
206 |
| -- `first_superuser`: (default: `"[email protected]"`) The email of the first superuser (in .env). |
207 |
| -- `first_superuser_password`: (default: `"changethis"`) The password of the first superuser (in .env). |
208 |
| -- `smtp_host`: (default: "") The SMTP server host to send emails, you can set it later in .env. |
209 |
| -- `smtp_user`: (default: "") The SMTP server user to send emails, you can set it later in .env. |
210 |
| -- `smtp_password`: (default: "") The SMTP server password to send emails, you can set it later in .env. |
211 |
| -- `emails_from_email`: (default: `"[email protected]"`) The email account to send emails from, you can set it later in .env. |
212 |
| -- `postgres_password`: (default: `"changethis"`) The password for the PostgreSQL database, stored in .env, you can generate one with the method above. |
213 |
| -- `sentry_dsn`: (default: "") The DSN for Sentry, if you are using it, you can set it later in .env. |
214 |
| - |
215 |
| -## Backend Development |
216 |
| - |
217 |
| -Backend docs: [backend/README.md](./backend/README.md). |
218 |
| - |
219 |
| -## Frontend Development |
220 |
| - |
221 |
| -Frontend docs: [frontend/README.md](./frontend/README.md). |
222 |
| - |
223 |
| -## Deployment |
224 |
| - |
225 |
| -Deployment docs: [deployment.md](./deployment.md). |
226 |
| - |
227 |
| -## Development |
228 |
| - |
229 |
| -General development docs: [development.md](./development.md). |
230 |
| - |
231 |
| -This includes using Docker Compose, custom local domains, `.env` configurations, etc. |
232 |
| - |
233 |
| -## Release Notes |
234 |
| - |
235 |
| -Check the file [release-notes.md](./release-notes.md). |
236 |
| - |
237 |
| -## License |
238 |
| - |
239 |
| -The Full Stack FastAPI Template is licensed under the terms of the MIT license. |
| 1 | +Mosaic, a project for CS4800 Software Engineering |
0 commit comments