diff --git a/README.md b/README.md index f24bea3..0dc7466 100644 --- a/README.md +++ b/README.md @@ -35,13 +35,10 @@ docker-compose -f production.docker-compose.yml up -d --force-recreate --build - This starts two containers, called `backend` and `frontend`, and exposes the deployed web application on port `8000`. You can open a browser and navigate to [http:localhost:8000/](http:localhost:8000/) to try it out. -- `production.frontend.Dockerfile` -- `production.backend.Dockerfile` - ### Production Frontend Container -The `frontend` production Docker image is created according to `production.frontend.Dockerfile`. -It's based on Debian and initially installs Caddy, as well as NodeJS, and creates a non-root-user to run Caddy as. +The `frontend` production Docker image is built according to `production.frontend.Dockerfile`. +It is based on Debian and initially installs Caddy, as well as npm, and creates a non-root-user to run Caddy as. Next up, the image copies over and bundles the frontend code and assets using Parcel. @@ -52,22 +49,25 @@ The files bundled by Parcel are then served as static files by Caddy, with `/fro Caddy is configured to forward any requests with the `/api/`-prefix to the [backend-container](#production-backend-container). -Because Parcel renames files when bundling them, Caddy is also configured to serve unbundled static files. -All files and folder under the `/public/static/` directory are copied into the image and served under the `/static/`-prefix by Caddy, +Because Parcel renames files when bundling them, Caddy is also configured to serve unbundled static files in this template. +All files and folders under the `/public/static/` directory are copied into the image and served under the `/static/`-prefix by Caddy, without being bundled (and renamed) by Parcel. For example: the file `/public/static/images/tux.svg` can be accessed at [http://localhost:8000/static/images/tux.svg](http://localhost:8000/static/images/tux.svg) in your browser. -Requests for `/robots.txt` and `/sitemap.xml` are routed to the respective files under the `/robots/`-directory, where you should modify them as necessary. +The `/robots.txt` and `/sitemap.xml` files are served by Caddy, and are sourced from the `/robots/`-directory, where you should [customize](#customization) +them as necessary. +You can view the results at [http://localhost:8000/robots.txt](http://localhost:8000/robots.txt) and +[http://localhost:8000/sitemap.xml](http://localhost:8000/sitemap.xml) respectively. ### Production Backend Container The `backend`-container serves FastAPI-endpoints using [uvicorn](https://www.uvicorn.org/). -All HTTP requests accessing paths under `/api/` are sent here by Caddy (which runs within the [frontend-container](#production-frontend-container)). +All HTTP requests requesting paths under `/api/` are routed here by Caddy (which runs within the [frontend-container](#production-frontend-container)). Uvicorn's root path is configured such that the backend code does not need to include the `/api/`-prefix of the route. As an example, take a look at the `hello()`-endpoint declared in `/backend/main.py`: in the code, it is declared at `/hello/`, -but in the browser, you must access the endpoint at [http://localhost:8000/api/hello/](http://localhost:8000/api/hello/). +but in the browser, you access the endpoint at [http://localhost:8000/api/hello/](http://localhost:8000/api/hello/). This prevents repetition when writing your endpoint code and allows you to access the interactive Swagger API documentation at [http://localhost:8000/api/docs](http://localhost:8000/api/docs), which is auto-generated by FastAPI. @@ -83,14 +83,10 @@ A number of default configuration files and placeholder assets for the frontend You should, at **minimum**, adjust the following things according to your requirements (otherwise things will not work as expected): - [ ] `package.json` -- [ ] [robots.txt and sitemap.xml](#robots.txt-and-sitemap.xml) +- [ ] [robots.txt and sitemap.xml](#robots-and-sitemap) - [ ] the ``-tags in `/frontend/src/html/index.html` - [ ] [OG Image](#og-image) and [favicon](#favicon) -## Configuration Files - -Depending on the configuration you wish to customize, please refer to each component's [relevant documentation](#about). - ## Assets The template in this repo provides and references some placeholder-assets which you should replace with your own. @@ -116,7 +112,7 @@ The OG image should ideally be a `.webp`-file, and its dimensions should be at l A placeholder OG image can be found at `/frontend/assets/images/common/og-image.webp`. -### robots.txt and sitemap.xml +### Robots and Sitemap The `/robots/robots.txt` and `/robots/sitemap.xml` files are added to the [frontend docker container](#production-frontend-container) and served at the site root upon deployment. @@ -128,8 +124,13 @@ Both files are crucial for search engine visibility and SEO, so you should adjus Static font files are stored under `/frontend/assets/fonts/` and declared for use in CSS within `/frontend/src/css/fonts.css`. The added font families can be accessed using TailwindCSS after configuring them inside `tailwind.config.js`. -You should add your own fonts here as necessary. +You can add or remove fonts here as necessary. -# Roadmap +## Configuration Files + +Depending on the configuration you wish to customize, please refer to each component's [relevant documentation](#about). + +# TODOs / Roadmap 1. Add a development Docker configuration +2. Minify CSS in prod