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
This is a template application for a FARM stack. FARM stands for FastAPI, React, MongoDB.
@@ -15,20 +13,24 @@ The project is composed of :
15
13
16
14
## Running the application locally for development
17
15
18
-
To run the application manually in a terminal, see both the [backend](backend/README.md) and [frontend](frontend/README.md)'s READMEs.
16
+
To run the application manually in a terminal, see both the [backend](backend/README.md) and [frontend](frontend/README.md)'s READMEs for instructions.
19
17
20
18
## Running the application with Docker
21
19
22
-
The project contains Docker configuration files to run the application through Docker. The Docker configuration is largely adapted from Tiangolo's [Full stack FastAPI cookiecutter](https://github.com/tiangolo/full-stack-fastapi-postgresql) project.
20
+
The project contains Docker configuration files to run the application with Docker compose. Two docker-compose files are provided with configuration for `dev` and for `production` environments. The Docker configuration is largely adapted from Tiangolo's [Full stack FastAPI cookiecutter](https://github.com/tiangolo/full-stack-fastapi-postgresql) project.
23
21
24
22
### Local development with Docker
25
23
24
+
The local development file for docker is [docker-compose.yml](./docker-compose.yml).
25
+
26
26
Start the stack with Docker Compose:
27
27
28
28
```bash
29
-
docker-compose up -d
29
+
dockercompose up -d --build
30
30
```
31
31
32
+
The `--build` arg can be omitted after the images have been built at least once.
33
+
32
34
Now you can open your browser and interact with these URLs:
33
35
34
36
* Frontend, served with vite with hot reload of code: http://localhost
@@ -44,70 +46,56 @@ Now you can open your browser and interact with these URLs:
44
46
Once the stack is up, to check the logs, run:
45
47
46
48
```bash
47
-
docker-compose logs
49
+
dockercompose logs
48
50
```
49
51
50
52
To check the logs of a specific service, add the name of the service, e.g.:
51
53
52
54
```bash
53
-
docker-compose logs backend
55
+
dockercompose logs backend
54
56
```
55
57
56
-
### Docker Compose Override
58
+
### Docker Compose settings for development
57
59
58
-
During development, you can change Docker Compose settings that will only affect the local development environment, in the file `docker-compose.override.yml`.
59
-
60
-
The changes to that file only affect the local development environment, not the production environment. So, you can add *temporary* changes that help the development workflow.
61
-
62
-
For example, the directory with the backend code is mounted as a Docker "host volume", mapping the code you change live to the directory inside the container. Same for the frontend code. That allows you to test your changes right away, without having to build the Docker image again. It should only be done during development, for production, you should build the Docker image with a recent version and stable version of the code.
60
+
When running the application with docker in development, both the frontend and backend directories are mounted as volumes to their corresponding docker containers to enable hot reload of code changes. This allows you to test your changes right away, without having to build the Docker image again. It should only be done during development, for production you should build the Docker image with a recent and stable version of the code.
63
61
64
62
For the backend, there is a command override that runs `/start-reload.sh` (included in the base image) instead of the default `/start.sh` (also included in the base image). It starts a single server process (instead of multiple, as would be for production) and reloads the process whenever the code changes. Have in mind that if you have a syntax error and save the Python file, it will break and exit, and the container will stop. After that, you can restart the container by fixing the error and running the `docker-compose up -d` command again. The backend [Dockerfile](backend/Dockerfile) is in the backend directory.
65
63
66
-
For the frontend, a different Dockerfile is used in the `docker-compose.override.yml`. In development, the frontend docker container starts with the `npm run dev -- --host` command, while in production the frontend app is built and the app is served by an nginx server. The [nginx configuration file](frontend/nginx.conf) is in the frontend dir.
64
+
For the frontend, when in development, the frontend docker container starts with the `npm run dev -- --host` command, while in production the frontend app is built into static files and the app is served by an nginx server. The [nginx configuration file](frontend/nginx.conf) is in the frontend dir.
67
65
68
66
### Accessing the containers
69
67
70
68
To get inside a container with a `bash` session you can start the stack with:
71
69
72
70
```console
73
-
$ docker-compose up -d
71
+
$ dockercompose up -d
74
72
```
75
73
76
74
and then `exec` inside the running container:
77
75
78
76
```console
79
-
$ docker-compose exec backend bash
77
+
$ dockercompose exec backend bash
80
78
```
81
79
82
80
This will give you access to a bash session in the `backend` container. Change the name of the container to the one you want to access.
83
81
84
-
## Deployment
85
-
86
-
Deployment to a Docker Swarm mode cluster should be possible, but it has not been tested. Refer to Tiangolo's [Full stack FastAPI cookiecutter](https://github.com/tiangolo/full-stack-fastapi-postgresql) project documentation for information on how to manage deployment and how to configure the Traefik proxy with constraints and such. The <ahref="https://dockerswarm.rocks"target="_blank">DockerSwarm.rocks</a> tutorials are also a good place to look for info.
87
82
88
-
## Docker Compose files and env vars
83
+
###Docker Compose settings for production
89
84
90
-
There is a main `docker-compose.yml` file with all the configurations that apply to the whole stack, it is used automatically by `docker-compose`.
85
+
The [docker-compose-prod.yml](./docker-compose.prod.yml) file contains the configuration to run the application with docker in a production environment, on a host server. To run the application with this file, run
91
86
92
-
And there's also a `docker-compose.override.yml` with overrides for development, for example to mount the source code as a volume. It is used automatically by `docker-compose` to apply overrides on top of `docker-compose.yml`.
93
-
94
-
These Docker Compose files use the [.env](./.env) file containing configurations to be injected as environment variables in the containers.
95
-
96
-
They also use some additional configurations taken from environment variables set in the scripts before calling the `docker-compose` command.
97
-
98
-
It is all designed to support several "stages", like development, building, testing, and deployment. Also, allowing the deployment to different environments like staging and production.
99
-
100
-
They are designed to have the minimum repetition of code and configurations, so that if you need to change something, you have to change it in the minimum amount of places. That's why files use environment variables that get auto-expanded. That way, if for example, you want to use a different domain, you can call the `docker-compose` command with a different `DOMAIN` environment variable instead of having to change the domain in several places inside the Docker Compose files.
87
+
```console
88
+
docker compose -f docker-compose.prod.yml up -d
89
+
```
101
90
102
-
Also, if you want to have another deployment environment, say `preprod`, you just have to change environment variables, but you can keep using the same Docker Compose files.
91
+
**Note:** This will not work out of the box, mainly because the `docker-compose-prod.yml` configures a traefik proxy with ssl enabled that will try to fetch ssl certificates from Let's Encrypt, which will not work unless you specify a valid hostname accessible on the internet. However, to deploy the application in production on a server, you only need to set the required env variables in the [.env](./.env) file.
103
92
104
-
### The .env file
93
+
### Docker Compose files and env vars
105
94
106
-
The [.env](./.env) file is the one that contains all your configurations, generated keys and passwords, etc.
95
+
Both the [docker-compose.yml](./docker-compose.yml) and [docker-compose-prod.yml](./docker-compose.prod.yml) files use the [.env](./.env) file containing configurations to be injected as environment variables in the containers.
107
96
108
-
Depending on your workflow, you could want to exclude it from Git, for example if your project is public. In that case, you would have to make sure to set up a way for your CI tools to obtain it while building or deploying your project.
97
+
The docker-compose files are designed to support several environments (i.e. development, building, testing, production) simply by setting the appropriate variable values in the `.env` file.
109
98
110
-
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.
99
+
The [.env](./.env) file contains all the configuration variables. The values set in the `.env` file will override those that are set in the frontend and backend `.env` files for local development. For exemple, the backend app also has a [.env.dev](backend/.env.dev) file which is read to populate the backend's [config](backend/app/config/config.py) module. When the application is run with docker though, the env variables in the projet root's [.env](./.env) file will override the env variables set in the backend and frontend's respective .env files. In order to be able to keep working both with docker and manually, you only have to make sure that the required variables are set both in the root `.env` file, and in the backend and frontend `.env` files.
111
100
112
-
**Note** that in order to have both the backend and frontend app be able to run locally without docker, those apps also expect to find env variables in their respective directory. For exemple, the backend app also has a [.env.dev](backend/.env.dev) file which is read to populate the backend's [config](backend/app/config/config.py) module. When the application is run with docker though, the env variables in the projet root's [.env](./.env) file will override the env variables set in the backend and frontend's respective .env files.
113
-
In order to be able to keep working both with docker and manually, you only have to make sure that the required variables are set both in the root `.env` file, and in the backend and frontend `.env` files.
101
+
The `.env` file that is commited to the github repository contains example values which are ok to use for testing and development, but which should be changed when running the application in production (admin passwords, secret keys, client ids, etc.). During deployment in production, the .env file is replaced with one containing the appropriate values.
Copy file name to clipboardExpand all lines: backend/README.md
+10Lines changed: 10 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -31,6 +31,16 @@ Navigate to `http://localhost:8000/api/v1/` to access the root API path.
31
31
Navigate to `http://localhost:8000/docs` to access the API's documentation.
32
32
Navigate to `http://localhost:8000/redoc` to access the API's alternative doc built with ReDoc.
33
33
34
+
## Running the tests
35
+
36
+
Run
37
+
38
+
```console
39
+
pytest
40
+
```
41
+
42
+
to run the unit test for the backend app.
43
+
34
44
## Configuration
35
45
36
46
The project uses Pydantic's settings management through FastAPI. Documentation on how the settings work is availabe [here](https://fastapi.tiangolo.com/advanced/settings/).
0 commit comments