Please follow these instructions, fill every question, and do every step. 🙏
I'm asking this because answering questions and solving problems in GitHub is what consumes most of the time.
I end up not being able to add new features, fix bugs, review pull requests, etc. as fast as I wish because I have to spend too much time handling questions.
All that, on top of all the incredible help provided by a bunch of community members, that give a lot of their time to come here and help others.
That's a lot of work, but if more users came to help others like them just a little bit more, it would be much less effort for them (and you and me 😅).
By asking questions in a structured way (following this) it will be much easier to help you.
And there's a high chance that you will find the solution along the way and you won't even have to submit it and wait for an answer. 😎
As there are too many questions, I'll have to discard and close the incomplete ones. That will allow me (and others) to focus on helping people like you that follow the whole process and help us help you. 🤓
- type:checkboxes
id:checks
attributes:
label:First Check
description:Please confirm and check all the following options.
options:
- label:I added a very descriptive title here.
required:true
- label:I used the GitHub search to find a similar question and didn't find it.
required:true
- label:I searched in the documentation/README.
required:true
- label:I already searched in Google "How to do X" and didn't find any information.
required:true
- label:I already read and followed all the tutorial in the docs/README and didn't find an answer.
required:true
- type:checkboxes
id:help
attributes:
label:Commit to Help
description:|
After submitting this, I commit to one of:
* Read open questions until I find 2 where I can help someone and add a comment to help there.
* I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future.
options:
- label:I commit to help with one of those options 👆
required:true
- type:textarea
id:example
attributes:
label:Example Code
description:|
Please add a self-contained, [minimal, reproducible, example](https://stackoverflow.com/help/minimal-reproducible-example) with your use case.
If I (or someone) can copy it, run it, and see it right away, there's a much higher chance I (or someone) will be able to help you.
placeholder:|
Write your example code here.
render:Text
validations:
required:true
- type:textarea
id:description
attributes:
label:Description
description:|
What is the problem, question, or error?
Write a short description telling me what you are doing, what you expect to happen, and what is currently happening.
placeholder:|
* Open the browser and call the endpoint `/`.
* It returns a JSON with `{"message": "Hello World"}`.
* But I expected it to return `{"message": "Hello Morty"}`.
validations:
required:true
- type:dropdown
id:os
attributes:
label:Operating System
description:What operating system are you on?
multiple:true
options:
- Linux
- Windows
- macOS
- Other
validations:
required:true
- type:textarea
id:os-details
attributes:
label:Operating System Details
description:You can add more details about your operating system here, in particular if you chose "Other".
validations:
required:true
- type:input
id:python-version
attributes:
label:Python Version
description:|
What Python version are you using?
You can find the Python version with:
```bash
python --version
```
validations:
required:true
- type:textarea
id:context
attributes:
label:Additional Context
description:Add any additional context information or screenshots you think are useful.
about:To suggest an idea or ask about a feature, please start with a question saying what you would like to achieve. There might be a way to do it already.
description:You are @tiangolo or he asked you directly to create an issue here. If not, check the other options. 👇
body:
- type:markdown
attributes:
value:|
Thanks for your interest in this project! 🚀
If you are not @tiangolo or he didn't ask you directly to create an issue here, please start the conversation in a [Question in GitHub Discussions](https://github.com/tiangolo/full-stack-fastapi-template/discussions/categories/questions) instead.
- type:checkboxes
id:privileged
attributes:
label:Privileged issue
description:Confirm that you are allowed to create an issue here.
options:
- label:I'm @tiangolo or he asked me directly to create an issue here.
"message": "Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues."
"message": "Assuming the original need was handled, this will be automatically closed now. But feel free to add more comments or create new issues or PRs."
},
"waiting": {
"delay": 2628000,
"message": "As this PR has been waiting for the original user for a while but seems to be inactive, it's now going to be closed. But if there's anyone interested, feel free to create a new PR.",
"reminder": {
"before": "P3D",
"message": "Heads-up: this will be closed in 3 days unless there's new activity."
}
},
"invalid": {
"delay": 0,
"message": "This was marked as invalid and will be closed now. If this is an error, please provide additional details."
If you have `pipx` and you didn't install `copier`, you can run it directly:
```bash
pipx run copier copy https://github.com/tiangolo/full-stack-fastapi-template my-awesome-project --trust
pipx run copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust
```
**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/tiangolo/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py) that updates your `.env` files.
**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.
### Input variables
### Input Variables
Copier will ask you for some data, you might want to have at hand before generating the project.
@@ -130,7 +195,7 @@ But don't worry, you can just update any of that in the `.env` files afterwards.
The input variables, with their default values (some auto generated) are:
-`project_name`: (default: `"FastAPI Project"`) The name of the project, shown to API users (in .env).
-`stack_name`: (default: `"fastapi-project"`) The name of the stack used for Docker Compose labels (no spaces) (in .env).
-`stack_name`: (default: `"fastapi-project"`) The name of the stack used for Docker Compose labels and project name (no spaces, no periods) (in .env).
-`secret_key`: (default: `"changethis"`) The secret key for the project, used for security, stored in .env, you can generate one with the method above.
-`first_superuser`: (default: `"admin@example.com"`) The email of the first superuser (in .env).
-`first_superuser_password`: (default: `"changethis"`) The password of the first superuser (in .env).
Security is very important for this project and its community. 🔒
Learn more about it below. 👇
## Versions
The latest version or release is supported.
You are encouraged to write tests for your application and update your versions frequently after ensuring that your tests are passing. This way you will benefit from the latest features, bug fixes, and **security fixes**.
## Reporting a Vulnerability
If you think you found a vulnerability, and even if you are not sure about it, please report it right away by sending an email to: security@tiangolo.com. Please try to be as explicit as possible, describing all the steps and example code to reproduce the security issue.
I (the author, [@tiangolo](https://twitter.com/tiangolo)) will review it thoroughly and get back to you.
## Public Discussions
Please restrain from publicly discussing a potential security vulnerability. 🙊
It's better to discuss privately and try to find a solution first, to limit the potential impact as much as possible.
* [Poetry](https://python-poetry.org/) for Python package and environment management.
* [uv](https://docs.astral.sh/uv/) for Python package and environment management.
## Local Development
## Docker Compose
*Start the stack with Docker Compose:
Start the local development environment with Docker Compose following the guide in [../development.md](../development.md).
```bash
docker compose up -d
```
## General Workflow
* Now you can open your browser and interact with these URLs:
Frontend, built with Docker, with routes handled based on the path: http://localhost
Backend, JSON based web API based on OpenAPI: http://localhost/api/
Automatic interactive documentation with Swagger UI (from the OpenAPI backend): http://localhost/docs
Adminer, database web administration: http://localhost:8080
Traefik UI, to see how the routes are being handled by the proxy: http://localhost:8090
**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.
To check the logs, run:
```bash
docker compose logs
```
To check the logs of a specific service, add the name of the service, e.g.:
```bash
docker compose logs backend
```
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.
## Backend local development, additional details
### General workflow
By default, the dependencies are managed with [Poetry](https://python-poetry.org/), go there and install it.
By default, the dependencies are managed with [uv](https://docs.astral.sh/uv/), go there and install it.
From `./backend/` you can install all the dependencies with:
```console
$poetry install
$uv sync
```
Then you can start a shell session with the new environment with:
Then you can activate the virtual environment with:
```console
$poetry shell
$source .venv/bin/activate
```
Make sure your editor is using the correct Python virtual environment.
Make sure your editor is using the correct Python virtual environment, with the interpreter at `backend/.venv/bin/python`.
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`.
### VS Code
## VS Code
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.
The setup is also already configured so you can run the tests through the VS Code Python tests tab.
### Docker Compose Override
## Docker Compose Override
During development, you can change Docker Compose settings that will only affect the local development environment in the file `docker-compose.override.yml`.
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.
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. 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 of the backend code. But during development, it allows you to iterate very fast.
For example, the directory with the backend code is synchronized in the Docker container, copying the code you change live to the directory inside the container. 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 of the backend code. But during development, it allows you to iterate very fast.
There is also 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 again:
There is also a command override that runs `fastapi run --reload` instead of the default `fastapi run`. 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 again:
```console
$ docker compose up -d
$ docker compose watch
```
There is also a commented out `command` override, you can uncomment it and comment the default one. It makes the backend container run a process that does "nothing", but keeps the container alive. That allows you to get inside your running container and execute commands inside, for example a Python interpreter to test installed dependencies, or start the development server that reloads when it detects changes.
@@ -88,10 +54,10 @@ There is also a commented out `command` override, you can uncomment it and comme
To get inside the container with a `bash` session you can start the stack with:
```console
$ docker compose up -d
$ docker compose watch
```
and then `exec` inside the running container:
and then in another terminal,`exec` inside the running container:
```console
$ docker compose exec backend bash
@@ -105,16 +71,16 @@ root@7f2607af31c3:/app#
that means that you are in a `bash` session inside your container, as a `root` user, under the `/app` directory, this directory has another directory called "app" inside, that's where your code lives inside the container: `/app/app`.
There you can use the script `/start-reload.sh` to run the debug live reloading server. You can run that script from inside the container with:
There you can use the `fastapi run --reload` command to run the debug live reloading server.
```console
$bash /start-reload.sh
$fastapi run --reload app/main.py
```
...it will look like:
```console
root@7f2607af31c3:/app# bash /start-reload.sh
root@7f2607af31c3:/app# fastapi run --reload app/main.py
```
and then hit enter. That runs the live reloading server that auto reloads when it detects code changes.
@@ -123,7 +89,7 @@ Nevertheless, if it doesn't detect a change but a syntax error, it will just sto
...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.
### Backend tests
## Backend tests
To test the backend run:
@@ -131,31 +97,31 @@ To test the backend run:
$ bash ./scripts/test.sh
```
The tests run with Pytest, modify and add tests to `./backend/app/tests/`.
The tests run with Pytest, modify and add tests to `./backend/tests/`.
If you use GitHub Actions the tests will run automatically.
#### Test running stack
### Test running stack
If your stack is already up and you just want to run the tests, you can use:
That `/app/tests-start.sh` script just calls `pytest` after making sure that the rest of the stack is running. If you need to pass extra arguments to `pytest`, you can pass them to that command and they will be forwarded.
That `/app/scripts/tests-start.sh` script just calls `pytest` after making sure that the rest of the stack is running. If you need to pass extra arguments to `pytest`, you can pass them to that command and they will be forwarded.
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.
### Migrations
## Migrations
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.
@@ -183,16 +149,24 @@ $ alembic revision --autogenerate -m "Add column last_name to User model"
$ alembic upgrade head
```
If you don't want to use migrations at all, uncomment the lines in the file at `./backend/app/db/init_db.py` that end in:
If you don't want to use migrations at all, uncomment the lines in the file at `./backend/app/core/db.py` that end in:
```python
SQLModel.metadata.create_all(engine)
```
and comment the line in the file `prestart.sh` that contains:
and comment the line in the file `scripts/prestart.sh` that contains:
```console
$ alembic upgrade head
```
If you don't want to start with the default models and want to remove them / modify them, from the beginning, without having any previous revision, you can remove the revision files (`.py` Python files) under `./backend/app/alembic/versions/`. And then create a first migration as described above.
## Email Templates
The email templates are in `./backend/app/email-templates/`. Here, there are two directories: `build` and `src`. The `src` directory contains the source files that are used to build the final email templates. The `build` directory contains the final email templates that are used by the application.
Before continuing, ensure you have the [MJML extension](https://marketplace.visualstudio.com/items?itemName=attilabuti.vscode-mjml) installed in your VS Code.
Once you have the MJML extension installed, you can create a new email template in the `src` directory. After creating the new email template and with the `.mjml` file open in your editor, open the command palette with `Ctrl+Shift+P` and search for `MJML: Export to HTML`. This will convert the `.mjml` file to a `.html` file and now you can save it in the build directory.
@@ -12,7 +12,7 @@ But you have to configure a couple things first. 🤓
* Have a remote server ready and available.
* Configure the DNS records of your domain to point to the IP of the server you just created.
* 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.
* 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.
* Install and configure [Docker](https://docs.docker.com/engine/install/) on the remote server (Docker Engine, not Docker Desktop).
*`PROJECT_NAME`: The name of the project, used in the API for the docs and emails.
*`STACK_NAME`: The name of the stack used for Docker Compose labels and project name, this should be different for `staging`, `production`, etc. You could use the same domain replacing dots with dashes, e.g. `fastapi-project-example-com` and `staging-fastapi-project-example-com`.
*`BACKEND_CORS_ORIGINS`: A list of allowed CORS origins separated by commas.
*`SECRET_KEY`: The secret key for the FastAPI project, used to sign tokens.
*`FIRST_SUPERUSER`: The email of the first superuser, this superuser will be the one that can create new users.
*`FIRST_SUPERUSER_PASSWORD`: The password of the first superuser.
*`USERS_OPEN_REGISTRATION`: Whether to allow open registration of new users.
*`SMTP_HOST`: The SMTP server host to send emails, this would come from your email provider (E.g. Mailgun, Sparkpost, Sendgrid, etc).
*`SMTP_USER`: The SMTP server user to send emails.
*`SMTP_PASSWORD`: The SMTP server password to send emails.
@@ -143,6 +144,13 @@ You can set several variables, like:
*`POSTGRES_DB`: The database name to use for this application. You can leave the default of `app`.
*`SENTRY_DSN`: The DSN for Sentry, if you are using it.
## GitHub Actions Environment Variables
There are some environment variables only used by GitHub Actions that you can configure:
*`LATEST_CHANGES`: Used by the GitHub Action [latest-changes](https://github.com/tiangolo/latest-changes) to automatically add release notes based on the PRs merged. It's a personal access token, read the docs for details.
*`SMOKESHOW_AUTH_KEY`: Used to handle and publish the code coverage using [Smokeshow](https://github.com/samuelcolvin/smokeshow), follow their instructions to create a (free) Smokeshow key.
### Generate secret keys
Some environment variables in the `.env` file have a default value of `changethis`.
@@ -175,22 +183,22 @@ There are already two environments configured, `staging` and `production`. 🚀
### Install GitHub Actions Runner
* On your remote server, if you are running as the `root` user, create a user for your GitHub Actions:
* On your remote server, create a user for your GitHub Actions:
```bash
adduser github
sudo adduser github
```
* Add Docker permissions to the `github` user:
```bash
usermod -aG docker github
sudo usermod -aG docker github
```
* Temporarily switch to the `github` user:
```bash
su - github
sudo su - github
```
* Go to the `github` user's home directory:
@@ -211,9 +219,15 @@ To make sure it runs on startup and continues running, you can install it as a s
exit
```
After you do it, you would be on the `root` user again. And you will be on the previous directory, belonging to the `root` user.
After you do it, you will be on the previous user again. And you will be on the previous directory, belonging to that user.
* Go to the `actions-runner` directory inside of the `github` user's home directory:
Before being able to go the `github` user directory, you need to become the `root` user (you might already be):
```bash
sudo su
```
* As the `root` user, go to the `actions-runner` directory inside of the `github` user's home directory:
```bash
cd /home/github/actions-runner
@@ -247,11 +261,15 @@ The current Github Actions workflows expect these secrets:
## Development in `localhost` with a custom domain
## Docker Compose
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`.
* Start the local stack with Docker Compose:
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.
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.
To configure it in your stack, follow the section **Change the development "domain"** below, using the domain `localhost.tiangolo.com`.
After performing those steps you should be able to open: http://localhost.tiangolo.com and it will be served by your stack in `localhost`.
Check all the corresponding available URLs in the section at the end.
## Development with a custom IP
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.
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`).
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.
* Open your `hosts` file with administrative privileges using a text editor:
* **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.
* **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`.
* 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`.
The new line might look like:
```
192.168.99.150 dev.example.com
```bash
docker compose watch
```
*Save the file.
* **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.
*Now you can open your browser and interact with these URLs:
...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.
Frontend, built with Docker, with routes handled based on the path: <http://localhost:5173>
To configure it in your stack, follow the section **Change the development "domain"** below, using the domain `dev.example.com`.
Backend, JSON based web API based on OpenAPI: <http://localhost:8000>
After performing those steps you should be able to open: http://dev.example.com and it will be server by your stack in `192.168.99.150`.
Automatic interactive documentation with Swagger UI (from the OpenAPI backend): <http://localhost:8000/docs>
Check all the corresponding available URLs in the section at the end.
Adminer, database web administration: <http://localhost:8080>
## Change the development "domain"
Traefik UI, to see how the routes are being handled by the proxy: <http://localhost:8090>
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.
**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.
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.
To check the logs, run (in another terminal):
* Open the file located at `./.env`. It would have a line like:
```
DOMAIN=localhost
```bash
docker compose logs
```
* Change it to the domain you are going to use, e.g.:
To check the logs of a specific service, add the name of the service, e.g.:
```bash
docker compose logs backend
```
## Mailcatcher
Mailcatcher is a simple SMTP server that catches all emails sent by the backend during local development. Instead of sending real emails, they are captured and displayed in a web interface.
This is useful for:
* Testing email functionality during development
* Verifying email content and formatting
* Debugging email-related functionality without sending real emails
The backend is automatically configured to use Mailcatcher when running with Docker Compose locally (SMTP on port 1025). All captured emails can be viewed at <http://localhost:1080>.
## Local Development
The Docker Compose files are configured so that each of the services is available in a different port in `localhost`.
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`.
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.
For example, you can stop that `frontend` service in the Docker Compose, in another terminal, run:
```bash
docker compose stop frontend
```
And then start the local frontend development server:
```bash
cd frontend
npm run dev
```
Or you could stop the `backend` Docker Compose service:
```bash
docker compose stop backend
```
And then you can run the local development server for the backend:
```bash
cd backend
fastapi dev app/main.py
```
## Docker Compose in `localhost.tiangolo.com`
When you start the Docker Compose stack, it uses `localhost` by default, with different ports for each service (backend, frontend, adminer, etc).
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.
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.
If you want to test that it's all working locally, you can edit the local `.env` file, and change:
```dotenv
DOMAIN=localhost.tiangolo.com
```
That variable will be used by the Docker Compose files.
That will be used by the Docker Compose files to configure the base domain for the services.
After that, you can restart your stack with:
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.
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.
After you update it, run again:
```bash
docker compose up -d
docker compose watch
```
and check all the corresponding available URLs in the section at the end.
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`.
## Docker Compose files and env vars
@@ -83,6 +118,12 @@ These Docker Compose files use the `.env` file containing configurations to be i
They also use some additional configurations taken from environment variables set in the scripts before calling the `docker compose` command.
After changing variables, make sure you restart the stack:
```bash
docker compose watch
```
## The .env file
The `.env` file is the one that contains all your configurations, generated keys and passwords, etc.
@@ -91,6 +132,52 @@ Depending on your workflow, you could want to exclude it from Git, for example i
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.
## Pre-commits and code linting
we are using a tool called [pre-commit](https://pre-commit.com/) for code linting and formatting.
When you install it, it runs right before making a commit in git. This way it ensures that the code is consistent and formatted even before it is committed.
You can find a file `.pre-commit-config.yaml` with configurations at the root of the project.
#### Install pre-commit to run automatically
`pre-commit` is already part of the dependencies of the project, but you could also install it globally if you prefer to, following [the official pre-commit docs](https://pre-commit.com/).
After having the `pre-commit` tool installed and available, you need to "install" it in the local repository, so that it runs automatically before each commit.
Using `uv`, you could do it with:
```bash
❯ uv run pre-commit install
pre-commit installed at .git/hooks/pre-commit
```
Now whenever you try to commit, e.g. with:
```bash
git commit
```
...pre-commit will run and check and format the code you are about to commit, and will ask you to add that code (stage it) with git again before committing.
Then you can `git add` the modified/fixed files again and now you can commit.
#### Running pre-commit hooks manually
you can also run `pre-commit` manually on all the files, you can do it using `uv` with:
```bash
❯ uv run pre-commit run --all-files
check for added large files..............................................Passed
- traefik.http.services.${STACK_NAME?Variable not set}-backend.loadbalancer.server.port=80
- traefik.http.services.${STACK_NAME?Variable not set}-backend.loadbalancer.server.port=8000
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-http.rule=Host(`${DOMAIN?Variable not set}`, `www.${DOMAIN?Variable not set}`) && PathPrefix(`/api`, `/docs`, `/redoc`)
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-http.rule=Host(`api.${DOMAIN?Variable not set}`)
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-http.entrypoints=http
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-https.rule=Host(`${DOMAIN?Variable not set}`, `www.${DOMAIN?Variable not set}`) && PathPrefix(`/api`, `/docs`, `/redoc`)
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-https.rule=Host(`api.${DOMAIN?Variable not set}`)
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-https.entrypoints=https
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-https.tls=true
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-https.tls.certresolver=le
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-http.middlewares=https-redirect,${STACK_NAME?Variable not set}-www-redirect
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-https.middlewares=${STACK_NAME?Variable not set}-www-redirect
# Enable redirection for HTTP and HTTPS
- traefik.http.routers.${STACK_NAME?Variable not set}-backend-http.middlewares=https-redirect
frontend:
image:'${DOCKER_IMAGE_FRONTEND?Variable not set}:${TAG-latest}'
@@ -96,7 +143,7 @@ services:
build:
context:./frontend
args:
- VITE_API_URL=https://${DOMAIN?Variable not set}
- VITE_API_URL=https://api.${DOMAIN?Variable not set}
- NODE_ENV=production
labels:
- traefik.enable=true
@@ -105,25 +152,16 @@ services:
- traefik.http.services.${STACK_NAME?Variable not set}-frontend.loadbalancer.server.port=80
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-http.rule=Host(`${DOMAIN?Variable not set}`, `www.${DOMAIN?Variable not set}`)
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-http.rule=Host(`dashboard.${DOMAIN?Variable not set}`)
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-http.entrypoints=http
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-https.rule=Host(`${DOMAIN?Variable not set}`, `www.${DOMAIN?Variable not set}`)
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-https.rule=Host(`dashboard.${DOMAIN?Variable not set}`)
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-https.entrypoints=https
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-https.tls=true
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-https.tls.certresolver=le
# Handle domain with and without "www" to redirect to only one
# To disable www redirection remove the next line
- traefik.http.middlewares.${STACK_NAME?Variable not set}-www-redirect.redirectregex.regex=^http(s)?://www.(${DOMAIN?Variable not set})/(.*)
# Redirect a domain with www to non-www
# To disable it remove the next line
- traefik.http.middlewares.${STACK_NAME?Variable not set}-www-redirect.redirectregex.replacement=http$${1}://${DOMAIN?Variable not set}/$${3}
# Middleware to redirect www, to disable it remove the next line
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-https.middlewares=${STACK_NAME?Variable not set}-www-redirect
# Middleware to redirect www, and redirect HTTP to HTTPS
# to disable www redirection remove the section: ${STACK_NAME?Variable not set}-www-redirect,
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-http.middlewares=https-redirect,${STACK_NAME?Variable not set}-www-redirect
# Enable redirection for HTTP and HTTPS
- traefik.http.routers.${STACK_NAME?Variable not set}-frontend-http.middlewares=https-redirect
The frontend is built with [Vite](https://vitejs.dev/), [React](https://reactjs.org/), [TypeScript](https://www.typescriptlang.org/), [TanStack Query](https://tanstack.com/query), [TanStack Router](https://tanstack.com/router) and [Chakra UI](https://chakra-ui.com/).
The frontend is built with [Vite](https://vitejs.dev/), [React](https://reactjs.org/), [TypeScript](https://www.typescriptlang.org/), [TanStack Query](https://tanstack.com/query), [TanStack Router](https://tanstack.com/router) and [Tailwind CSS](https://tailwindcss.com/).
## Frontend development
Before you begin, ensure that you have either the Node Version Manager (nvm) or Fast Node Manager (fnm) installed on your system.
Before you begin, ensure that you have either the Node Version Manager (nvm) or Fast Node Manager (fnm) installed on your system.
* To install fnm follow the [official fnm guide](https://github.com/Schniz/fnm#installation). If you prefer nvm, you can install it using the [official nvm guide](https://github.com/nvm-sh/nvm#installing-and-updating).
@@ -27,7 +27,7 @@ nvm install
```bash
# If using fnm
fnm use
fnm use
# If using nvm
nvm use
@@ -59,7 +59,7 @@ If you are developing an API-only app and want to remove the frontend, you can d
* In the `docker-compose.yml` file, remove the whole service / section `frontend`.
* In the `docker-compose.override.yml` file, remove the whole service / section `frontend`.
* In the `docker-compose.override.yml` file, remove the whole service / section `frontend` and `playwright`.
Done, you have a frontend-less (api-only) app. 🤓
@@ -74,16 +74,23 @@ But it would be only to clean them up, leaving them won't really have any effect
## Generate Client
### Automatically
* Activate the backend virtual environment.
* From the top level project directory, run the script:
```bash
./scripts/generate-client.sh
```
* Commit the changes.
### Manually
* Start the Docker Compose stack.
* Download the OpenAPI JSON file from `http://localhost/api/v1/openapi.json` and copy it to a new file `openapi.json` at the root of the `frontend` directory.
* To simplify the names in the generated frontend client code, modify the `openapi.json` file by running the following script:
```bash
node modify-openapi-operationids.js
```
* To generate the frontend client, run:
```bash
@@ -99,7 +106,7 @@ Notice that everytime the backend changes (changing the OpenAPI schema), you sho
If you want to use a remote API, you can set the environment variable `VITE_API_URL` to the URL of the remote API. For example, you can set it in the `frontend/.env` file:
```env
VITE_API_URL=https://my-remote-api.example.com
VITE_API_URL=https://api.my-domain.example.com
```
Then, when you run the frontend, it will use that URL as the base URL for the API.
@@ -114,4 +121,33 @@ The frontend code is structured as follows:
*`frontend/src/components` - The different components of the frontend.
*`frontend/src/hooks` - Custom hooks.
*`frontend/src/routes` - The different routes of the frontend which include the pages.
*`theme.tsx` - The Chakra UI custom theme.
## End-to-End Testing with Playwright
The frontend includes initial end-to-end tests using Playwright. To run the tests, you need to have the Docker Compose stack running. Start the stack with the following command:
```bash
docker compose up -d --wait backend
```
Then, you can run the tests with the following command:
```bash
npx playwright test
```
You can also run your tests in UI mode to see the browser and interact with it running:
```bash
npx playwright test --ui
```
To stop and remove the Docker Compose stack and clean the data created in tests, use the following command:
```bash
docker compose down -v
```
To update the tests, navigate to the tests directory and modify the existing test files or add new ones as needed.
For more information on writing and running Playwright tests, refer to the official [Playwright documentation](https://playwright.dev/docs/intro).
d="M 66.145833 0 A 66.145836 65.931923 0 0 0 0 65.931893 A 66.145836 65.931923 0 0 0 66.145833 131.86379 A 66.145836 65.931923 0 0 0 132.29167 65.931893 A 66.145836 65.931923 0 0 0 66.145833 0 z M 61.581771 29.853992 L 103.20042 29.853992 L 61.410205 59.222742 L 89.976937 59.222742 L 29.091248 102.00979 L 42.315763 72.641044 L 48.358289 59.222742 L 61.581771 29.853992 z "/>
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Sebastián Ramírez
github-actions[bot]
Alejandra
Ayman Al-Suleihi
dependabot[bot]
Martin
Sofie Van Landeghem
Motov Yurii
Mike Alvarino
Roland Takacs
Alex Rockhill
github-actions
Cassiano
Zhengyang Cui
Diego Tellez
Joel Pérez
Chris Handy
Christopher Markus
Nauanbek
Robert (Jamie) Munro
Boriss Jerjomkin
Ayoub Benaissa
Patrick Arminio
Tobias
Justin Perdok
Saltie
Muhammad Sameer Amin
Hmily
Chris
Waket Zheng
Hani Sabsoob
jjaakko
Elijah Rippeth
Abdul
Esteban Maya
Javier Álvarez
António Loureiro
jmondaud
Tomer Barletz
Craz1k0ek
Philipp Wurzer
Joel Gotsch
Bill Zhong
Leon Lowitzki
efonte
Santiago Gandolfo
Δ̷̨̧̡̭̺̙̞͖̖͕̰̥̙̯͙̞̯̗̔͌͐̿͊̌́̄̑̿̓̉̈̀͘͠λ̶͔͓̘̘̳͇̻̍̏͌̅̓̓͂̍̾̔͜λ̶̛̯̖̯̲̱͎̙͎̎̐͆͂̽̓̇́͌́̀̏̎̅͋̏̊͘λ̶̨̨̰̟̯̫̲̲̫̯̭̤̳̼̫͉̹̞́̐̒Δ̷̡̛̥̖͇͚͍͍̄̏̂͛̅̌͗̂̽̅̀͆̿̔̚͜
Dudi Levy
Salomon Popp
emmanuel
