feat: create proper README
This commit is contained in:
parent
19ee9da087
commit
664e585184
1 changed files with 117 additions and 23 deletions
140
README.md
140
README.md
|
|
@ -1,41 +1,135 @@
|
||||||
# TODO
|
|
||||||
|
|
||||||
In `index.html`: make parcel replace the hard-coded base URL (in the meta tags).
|
|
||||||
|
|
||||||
# About
|
# About
|
||||||
|
|
||||||
This is a template project for a webapp using the following tech stack:
|
This is a template for building a webapp using the following tech stack:
|
||||||
|
|
||||||
- **Frontend**:
|
- **Frontend**:
|
||||||
- Vue.js
|
- [Vue.js](https://vuejs.org/guide/introduction.html) - frontend JS framework
|
||||||
- TailwindCSS
|
- [Vue Router](https://router.vuejs.org/guide/) - frontend router for Vue
|
||||||
- Axios
|
- [TailwindCSS](https://tailwindcss.com/docs/configuration) - CSS framework
|
||||||
|
- [Axios](https://axios-http.com/docs/intro) - library for making API requests from the frontend
|
||||||
|
- [Parcel](/https://parceljs.org/docs/) - bundler used for frontend module resolution and asset optimization
|
||||||
|
- [npm](https://docs.npmjs.com/cli/v7/configuring-npm/package-json) - node package manager for JavaScript packages
|
||||||
- **Backend**:
|
- **Backend**:
|
||||||
- FastAPI (python)
|
- [FastAPI](https://fastapi.tiangolo.com/) - Python-framework for backend APIs
|
||||||
|
- [Uvicorn](https://www.uvicorn.org/) - Python-ASGI-server used to serve the FastAPI backend
|
||||||
- **Other**:
|
- **Other**:
|
||||||
- Caddy (webserver/reverse proxy)
|
- [Caddy](https://caddyserver.com/docs/) - webserver and reverse proxy used for serving static files and HTTP routing
|
||||||
- Parcel (bundler)
|
- [Dockerfile](https://docs.docker.com/engine/reference/builder/) - recipes for building Docker images
|
||||||
|
- [Docker Compose](https://docs.docker.com/compose/compose-file/) - used to deploy interconnected Docker containers for development and/or production
|
||||||
|
|
||||||
|
Two different configurations are provided and instanced using the docker-related files in this template repository:
|
||||||
|
|
||||||
|
- The [production configuration](#production-configuration) is used for preformance-optimized production deployments of your web application
|
||||||
|
- The [development configuration](#development-configuration) is used for development-deployments of your web application, providing features such as hot-reloading and debugging information
|
||||||
|
|
||||||
|
This should go without saying, but **do not serve the development configuration** on a public production server.
|
||||||
|
|
||||||
|
## Production Configuration
|
||||||
|
|
||||||
|
The production-ready configuration can be deployed using the `production.docker-compose.yml` file, by running (as root):
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker-compose -f production.docker-compose.yml up -d --force-recreate --build --remove-orphans
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Next up, the image copies over and bundles the frontend code and assets using Parcel.
|
||||||
|
|
||||||
|
Finally, it starts an instance of Caddy, which is a web server used to route HTTP traffic and serve static files.
|
||||||
|
|
||||||
|
The files bundled by Parcel are then served as static files by Caddy, with `/frontend/src/html/index.html` as the site root (served at
|
||||||
|
[http:localhost:8000/](http:localhost:8000/).
|
||||||
|
|
||||||
|
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,
|
||||||
|
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.
|
||||||
|
|
||||||
|
### 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)).
|
||||||
|
|
||||||
|
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/).
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Development Configuration
|
||||||
|
|
||||||
|
> **TODO:** implement
|
||||||
|
|
||||||
# Customization
|
# Customization
|
||||||
|
|
||||||
A number of default template files and assets for the frontend are already present in the repository.
|
A number of default configuration files and placeholder assets for the frontend are already present in the repository.
|
||||||
These include essential assets like a set of fonts, and a default favicon.
|
|
||||||
|
|
||||||
## Favicon
|
You should, at **minimum**, adjust the following things according to your requirements (otherwise things will not work as expected):
|
||||||
|
|
||||||
The standards for the correct favicons are annoying, many browser vendors use a different standard.
|
- [ ] `package.json`
|
||||||
|
- [ ] [robots.txt and sitemap.xml](#robots.txt-and-sitemap.xml)
|
||||||
|
- [ ] the `<meta>`-tags in `/frontend/src/html/index.html`
|
||||||
|
- [ ] [OG Image](#og-image) and [favicon](#favicon)
|
||||||
|
|
||||||
A quick and easy way to create a set of favicons with broad compatibility is to create your favicon as an `.svg`-file,
|
## Configuration Files
|
||||||
and then use [realfavicongenerator.net](https://realfavicongenerator.net/) to create a set of relevant files and HTML
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
### Favicon
|
||||||
|
|
||||||
|
The standards for accepted favicon formats are all over the place and, depending on browser- and OS-vendors, expect a different format.
|
||||||
|
|
||||||
|
A quick and easy way to create a set of favicons with broad compatibility is to create your favicon as an `.svg`/`.png`-file,
|
||||||
|
and then use [realfavicongenerator.net](https://realfavicongenerator.net/) to create a set of relevant files and HTML references
|
||||||
for your favicon.
|
for your favicon.
|
||||||
|
|
||||||
Place the generated icons into `/frontend/assets/images/common/` and be sure to adjust the generated HTML to point to
|
Place the generated icons into `/frontend/assets/images/common/favicon/` and be sure to adjust the generated HTML to point to
|
||||||
this path.
|
the files placed under this path. Parcel will resolve the paths accordingly.
|
||||||
|
|
||||||
## OG Image
|
For reference, I created `/frontend/assets/images/common/favicon/favicon.svg`, and uploaded it to the favicongenerator.
|
||||||
|
I placed the resulting files into `/frontend/assets/images/common/favicon/` and updated `/frontend/src/html/index.html` accordingly.
|
||||||
|
|
||||||
The OG image is served directly by Caddy, and thus needs to be placed into `/public/static/images/common/`,
|
### OG Image
|
||||||
ideally as a `.webp`-file.
|
|
||||||
|
|
||||||
The image's dimensions should be 1200 x 630 pixels, as according to the
|
The OG image should ideally be a `.webp`-file, and its dimensions should be at least 1200 x 630 pixels, as according to the
|
||||||
[OGP standard](https://developers.facebook.com/docs/sharing/webmasters/images/).
|
[OGP standard](https://developers.facebook.com/docs/sharing/webmasters/images/).
|
||||||
|
|
||||||
|
A placeholder OG image can be found at `/frontend/assets/images/common/og-image.webp`.
|
||||||
|
|
||||||
|
### robots.txt and sitemap.xml
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Both files are crucial for search engine visibility and SEO, so you should adjust them as necessary (depending on whether you want your site to be indexed).
|
||||||
|
|
||||||
|
### Fonts
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
# Roadmap
|
||||||
|
|
||||||
|
1. Add a development Docker configuration
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue