About
This is a template for building a webapp using the following tech stack:
- Frontend:
- Vue.js - frontend JS framework
- Vue Router - frontend router for Vue
- TailwindCSS - CSS framework
- Axios - library for making API requests from the frontend
- Parcel - bundler used for frontend module resolution and asset optimization
- npm - node package manager for JavaScript packages
- Backend:
- Other:
- Caddy - webserver and reverse proxy used for serving static files and HTTP routing
- Dockerfile - recipes for building Docker images
- Docker Compose - 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 is used for preformance-optimized production deployments of your web application
- The development configuration is used during development 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):
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/ to try it out.
To stop the containers, run the following as root:
docker-compose -f production.docker-compose.yml down
Production Frontend Container
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.
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/.
Caddy is configured to forward any requests with the /api/-prefix to the backend-container.
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
in your browser.
The /robots.txt and /sitemap.xml files are served by Caddy, and are sourced from the /robots/-directory, where you should customize
them as necessary.
You can view the results at http://localhost:8000/robots.txt and
http://localhost:8000/sitemap.xml respectively.
Production Backend Container
The backend-container serves FastAPI-endpoints using uvicorn.
All HTTP requests requesting paths under /api/ are routed here by Caddy (which runs within the 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 access the endpoint at 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, which is auto-generated by FastAPI.
Development Configuration
The development configuration can be deployed using the development.docker-compose.yml file, by running (as root):
docker-compose -f development.docker-compose.yml up -d --build --force-recreate --remove-orphans
This starts three containers, called backend, parcel and frontend, and exposes the deployed web application on port 8000.
You can open a browser and navigate to http:localhost:8000/ to try it out.
To stop the containers, run the following as root:
docker-compose -f development.docker-compose.yml down
The development containers work very similarly to the production containers, with the exception that hot reloading of configuration and sourcecode files is enabled.
This means that when you modify the frontend or backend sourcecode while the development container is running, the changes are detected and applied automatically, restarting the containers is usually not required.
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
- the
<meta>-tags in/frontend/src/html/index.html - OG Image and favicon
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 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.
A placeholder OG image can be found at /frontend/assets/images/common/og-image.webp.
Robots and Sitemap
The /robots/robots.txt and /robots/sitemap.xml files are added to the frontend docker 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 can add or remove fonts here as necessary.
Configuration Files
Depending on the configuration you wish to customize, please refer to each component's relevant documentation.
TODOs / Roadmap
- Add sqlite/postgres containers
- Minify CSS in prod
- Add testing tools