You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: backend/README.md
+9-43
Original file line number
Diff line number
Diff line change
@@ -5,45 +5,11 @@
5
5
*[Docker](https://www.docker.com/).
6
6
*[Poetry](https://python-poetry.org/) for Python package and environment management.
7
7
8
-
## Local Development
8
+
## Docker Compose
9
9
10
-
*Start the stack with Docker Compose:
10
+
Start the local development environment with Docker Compose following the guide in [../development.md](../development.md).
11
11
12
-
```bash
13
-
docker compose up -d
14
-
```
15
-
16
-
* Now you can open your browser and interact with these URLs:
17
-
18
-
Frontend, built with Docker, with routes handled based on the path: http://localhost
19
-
20
-
Backend, JSON based web API based on OpenAPI: http://localhost/api/
21
-
22
-
Automatic interactive documentation with Swagger UI (from the OpenAPI backend): http://localhost/docs
23
-
24
-
Adminer, database web administration: http://localhost:8080
25
-
26
-
Traefik UI, to see how the routes are being handled by the proxy: http://localhost:8090
27
-
28
-
**Note**: The first time you start your stack, it might take a minute for it to be ready. While the backend waits for the database to be ready and configures everything. You can check the logs to monitor it.
29
-
30
-
To check the logs, run:
31
-
32
-
```bash
33
-
docker compose logs
34
-
```
35
-
36
-
To check the logs of a specific service, add the name of the service, e.g.:
37
-
38
-
```bash
39
-
docker compose logs backend
40
-
```
41
-
42
-
If your Docker is not running in `localhost` (the URLs above wouldn't work) you would need to use the IP or domain where your Docker is running.
43
-
44
-
## Backend local development, additional details
45
-
46
-
### General workflow
12
+
## General Workflow
47
13
48
14
By default, the dependencies are managed with [Poetry](https://python-poetry.org/), go there and install it.
49
15
@@ -63,13 +29,13 @@ Make sure your editor is using the correct Python virtual environment.
63
29
64
30
Modify or add SQLModel models for data and SQL tables in `./backend/app/models.py`, API endpoints in `./backend/app/api/`, CRUD (Create, Read, Update, Delete) utils in `./backend/app/crud.py`.
65
31
66
-
###VS Code
32
+
## VS Code
67
33
68
34
There are already configurations in place to run the backend through the VS Code debugger, so that you can use breakpoints, pause and explore variables, etc.
69
35
70
36
The setup is also already configured so you can run the tests through the VS Code Python tests tab.
71
37
72
-
###Docker Compose Override
38
+
## Docker Compose Override
73
39
74
40
During development, you can change Docker Compose settings that will only affect the local development environment in the file `docker-compose.override.yml`.
75
41
@@ -123,7 +89,7 @@ Nevertheless, if it doesn't detect a change but a syntax error, it will just sto
123
89
124
90
...this previous detail is what makes it useful to have the container alive doing nothing and then, in a Bash session, make it run the live reload server.
125
91
126
-
###Backend tests
92
+
## Backend tests
127
93
128
94
To test the backend run:
129
95
@@ -135,7 +101,7 @@ The tests run with Pytest, modify and add tests to `./backend/app/tests/`.
135
101
136
102
If you use GitHub Actions the tests will run automatically.
137
103
138
-
####Test running stack
104
+
### Test running stack
139
105
140
106
If your stack is already up and you just want to run the tests, you can use:
141
107
@@ -151,11 +117,11 @@ For example, to stop on first error:
When the tests are run, a file `htmlcov/index.html` is generated, you can open it in your browser to see the coverage of the tests.
157
123
158
-
###Migrations
124
+
## Migrations
159
125
160
126
As during local development your app directory is mounted as a volume inside the container, you can also run the migrations with `alembic` commands inside the container and the migration code will be in your app directory (instead of being only inside the container). So you can add it to your git repository.
Copy file name to clipboardExpand all lines: deployment.md
+7-7
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ But you have to configure a couple things first. 🤓
12
12
13
13
* Have a remote server ready and available.
14
14
* Configure the DNS records of your domain to point to the IP of the server you just created.
15
-
* Configure a wildcard subdomain for your domain, so that you can have multiple subdomains for different services, e.g. `*.fastapi-project.example.com`. This will be useful for accessing different components, like `traefik.fastapi-project.example.com`, `adminer.fastapi-project.example.com`, etc. And also for `staging`, like `staging.fastapi-project.example.com`, `staging.adminer.fastapi-project.example.com`, etc.
15
+
* Configure a wildcard subdomain for your domain, so that you can have multiple subdomains for different services, e.g. `*.fastapi-project.example.com`. This will be useful for accessing different components, like `dashboard.fastapi-project.example.com`, `api.fastapi-project.example.com`, `traefik.fastapi-project.example.com`, `adminer.fastapi-project.example.com`, etc. And also for `staging`, like `dashboard.staging.fastapi-project.example.com`, `adminer.staging..fastapi-project.example.com`, etc.
16
16
* Install and configure [Docker](https://docs.docker.com/engine/install/) on the remote server (Docker Engine, not Docker Desktop).
Copy file name to clipboardExpand all lines: development.md
+74-46
Original file line number
Diff line number
Diff line change
@@ -1,78 +1,100 @@
1
1
# FastAPI Project - Development
2
2
3
-
## Development in `localhost` with a custom domain
3
+
## Docker Compose
4
4
5
-
You might want to use something different than `localhost` as the domain. For example, if you are having problems with cookies that need a subdomain, and Chrome is not allowing you to use `localhost`.
5
+
* Start the local stack with Docker Compose:
6
6
7
-
In that case, you have two options: you could use the instructions to modify your system `hosts` file with the instructions below in **Development with a custom IP** or you can just use `localhost.tiangolo.com`, it is set up to point to `localhost` (to the IP `127.0.0.1`) and all its subdomains too. And as it is an actual domain, the browsers will store the cookies you set during development, etc.
8
-
9
-
If you used the default CORS enabled domains while generating the project, `localhost.tiangolo.com` was configured to be allowed. If you didn't, you will need to add it to the list in the variable `BACKEND_CORS_ORIGINS` in the `.env` file.
10
-
11
-
To configure it in your stack, follow the section **Change the development "domain"** below, using the domain `localhost.tiangolo.com`.
7
+
```bash
8
+
docker compose up -d
9
+
```
12
10
13
-
After performing those steps you should be able to open: http://localhost.tiangolo.comand it will be served by your stack in `localhost`.
11
+
* Now you can open your browser and interact with these URLs:
14
12
15
-
Check all the corresponding available URLs in the section at the end.
13
+
Frontend, built with Docker, with routes handled based on the path: http://localhost:5173
16
14
17
-
## Development with a custom IP
15
+
Backend, JSON based web API based on OpenAPI: http://localhost:8000
18
16
19
-
If you are running Docker in an IP address different than `127.0.0.1` (`localhost`), you will need to perform some additional steps. That will be the case if you are running a custom Virtual Machine or your Docker is located in a different machine in your network.
17
+
Automatic interactive documentation with Swagger UI (from the OpenAPI backend): http://localhost:8000/docs
20
18
21
-
In that case, you will need to use a fake local domain (`dev.example.com`) and make your computer think that the domain is served by the custom IP (e.g. `192.168.99.150`).
19
+
Adminer, database web administration: http://localhost:8080
22
20
23
-
If you have a custom domain like that, you need to add it to the list in the variable `BACKEND_CORS_ORIGINS` in the `.env` file.
21
+
Traefik UI, to see how the routes are being handled by the proxy: http://localhost:8090
24
22
25
-
* Open your `hosts` file with administrative privileges using a text editor:
23
+
**Note**: The first time you start your stack, it might take a minute for it to be ready. While the backend waits for the database to be ready and configures everything. You can check the logs to monitor it.
26
24
27
-
***Note for Windows**: If you are in Windows, open the main Windows menu, search for "notepad", right click on it, and select the option "open as Administrator" or similar. Then click the "File" menu, "Open file", go to the directory `c:\Windows\System32\Drivers\etc\`, select the option to show "All files" instead of only "Text (.txt) files", and open the `hosts` file.
28
-
***Note for Mac and Linux**: Your `hosts` file is probably located at `/etc/hosts`, you can edit it in a terminal running `sudo nano /etc/hosts`.
25
+
To check the logs, run:
29
26
30
-
* Additional to the contents it might have, add a new line with the custom IP (e.g. `192.168.99.150`) a space character, and your fake local domain: `dev.example.com`.
27
+
```bash
28
+
docker compose logs
29
+
```
31
30
32
-
The new line might look like:
31
+
To check the logs of a specific service, add the name of the service, e.g.:
33
32
34
-
```
35
-
192.168.99.150 dev.example.com
33
+
```bash
34
+
docker compose logs backend
36
35
```
37
36
38
-
* Save the file.
39
-
***Note for Windows**: Make sure you save the file as "All files", without an extension of `.txt`. By default, Windows tries to add the extension. Make sure the file is saved as is, without extension.
37
+
## Local Development
40
38
41
-
...that will make your computer think that the fake local domain is served by that custom IP, and when you open that URL in your browser, it will talk directly to your locally running server when it is asked to go to `dev.example.com` and think that it is a remote server while it is actually running in your computer.
39
+
The Docker Compose files are configured so that each of the services is available in a different port in `localhost`.
42
40
43
-
To configure it in your stack, follow the section **Change the development "domain"** below, using the domain `dev.example.com`.
41
+
For the backend and frontend, they use the same port that would be used by their local development server, so, the backend is at `http://localhost:8000` and the frontend at `http://localhost:5173`.
44
42
45
-
After performing those steps you should be able to open: http://dev.example.comand it will be server by your stack in `192.168.99.150`.
43
+
This way, you could turn off a Docker Compose service and start its local development service, and everything would keep working, because it all uses the same ports.
46
44
47
-
Check all the corresponding available URLs in the section at the end.
45
+
For example, you can stop that `frontend` service in the Docker Compose:
48
46
49
-
## Change the development "domain"
47
+
```bash
48
+
docker compose stop frontend
49
+
```
50
50
51
-
If you need to use your local stack with a different domain than `localhost`, you need to make sure the domain you use points to the IP where your stack is set up.
51
+
And then start the local frontend development server:
52
52
53
-
To simplify your Docker Compose setup, for example, so that the API docs (Swagger UI) knows where is your API, you should let it know you are using that domain for development.
53
+
```bash
54
+
cd frontend
55
+
npm run dev
56
+
```
54
57
55
-
* Open the file located at `./.env`. It would have a line like:
58
+
Or you could stop the `backend` Docker Compose service:
56
59
57
-
```
58
-
DOMAIN=localhost
60
+
```bash
61
+
docker compose stop backend
59
62
```
60
63
61
-
* Change it to the domain you are going to use, e.g.:
64
+
And then you can run the local development server for the backend:
62
65
66
+
```bash
67
+
cd backend
68
+
fastapi dev app/main.py
63
69
```
70
+
71
+
## Docker Compose in `localhost.tiangolo.com`
72
+
73
+
When you start the Docker Compose stack, it uses `localhost` by default, with different ports for each service (backend, frontend, adminer, etc).
74
+
75
+
When you deploy it to production (or staging), it will deploy each service in a different subdomain, like `api.example.com` for the backend and `dashboard.example.com` for the frontend.
76
+
77
+
In the guide about [deployment](deployment.md) you can read about Traefik, the configured proxy. That's the component in charge of transmitting traffic to each service based on the subdomain.
78
+
79
+
If you want to test that it's all working locally, you can edit the local `.env` file, and change:
80
+
81
+
```dotenv
64
82
DOMAIN=localhost.tiangolo.com
65
83
```
66
84
67
-
That variable will be used by the Docker Compose files.
85
+
That will be used by the Docker Compose files to configure the base domain for the services.
68
86
69
-
After that, you can restart your stack with:
87
+
Traefik will use this to transmit traffic at `api.localhost.tiangolo.com` to the backend, and traffic at `dashboard.localhost.tiangolo.com` to the frontend.
88
+
89
+
The domain `localhost.tiangolo.com` is a special domain that is configured (with all its subdomains) to point to `127.0.0.1`. This way you can use that for your local development.
90
+
91
+
After you update it, run again:
70
92
71
93
```bash
72
94
docker compose up -d
73
95
```
74
96
75
-
and check all the corresponding available URLs in the section at the end.
97
+
When deploying, for example in production, the main Traefik is configured outside of the Docker Compose files. For local development, there's an included Traefik in `docker-compose.override.yml`, just to let you test that the domains work as expected, for example with `api.localhost.tiangolo.com` and `dashboard.localhost.tiangolo.com`.
76
98
77
99
## Docker Compose files and env vars
78
100
@@ -84,6 +106,12 @@ These Docker Compose files use the `.env` file containing configurations to be i
84
106
85
107
They also use some additional configurations taken from environment variables set in the scripts before calling the `docker compose` command.
86
108
109
+
After changing variables, make sure you restart the stack:
110
+
111
+
```bash
112
+
docker compose up -d
113
+
```
114
+
87
115
## The .env file
88
116
89
117
The `.env` file is the one that contains all your configurations, generated keys and passwords, etc.
@@ -92,7 +120,7 @@ Depending on your workflow, you could want to exclude it from Git, for example i
92
120
93
121
One way to do it could be to add each environment variable to your CI/CD system, and updating the `docker-compose.yml` file to read that specific env var instead of reading the `.env` file.
94
122
95
-
###Pre-commits and code linting
123
+
## Pre-commits and code linting
96
124
97
125
we are using a tool called [pre-commit](https://pre-commit.com/) for code linting and formatting.
98
126
@@ -146,29 +174,29 @@ The production or staging URLs would use these same paths, but with your own dom
0 commit comments