# About

This is a template for building a webapp using the following tech stack:

- **Frontend**:
    - [Vue.js](https://vuejs.org/guide/introduction.html) - frontend JS framework
    - [Vue Router](https://router.vuejs.org/guide/) - frontend router for Vue
    - [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**:
    - [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**:
    - [Caddy](https://caddyserver.com/docs/) - webserver and reverse proxy used for serving static files and HTTP routing
    - [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

A number of default configuration files and placeholder assets for the frontend are already present in the repository.

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)
- [ ] the `<meta>`-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.

### 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.

Place the generated icons into `/frontend/assets/images/common/favicon/` and be sure to adjust the generated HTML to point to
the files placed under this path. Parcel will resolve the paths accordingly.

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.

### OG Image

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/).

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