Django + Svelte + Postgres + Docker + Fly.io template

               

TODO

Why Svelte rendered in Django templates?

TODO

How does it work?

TODO

Tools, libraries, frameworks:

This setup has been tested with Python 3.11 and Node 16.

Backend

• Django + Django Rest Framework django djangorestframework
• django-extensions - useful utilities (e.g better shell)
• django-cors-headers - handling cross-origin requests
• psycopg - Postgres connector (needed in Docker container)
• drf-spectacular - open api documentation (swagger and redoc)
• gunicorn - production wsgi http server
• whitenoise - building and serving static files
• pipenv - venv and package management tool
• coverage - for code coverage reports and running unit tests
• mypy + djangorestframework-stubs - for better typing experience

Suggested packages:

• sentry-sdk - for error reporting in production
• django-debug-toolbar - for debugging purposes
• django-filter - enables filtering querysets with url parameters and more
• channels - websockets backend
• djangorestframework-simplejwt, dj-rest-auth, django-allauth, djoser - making auth easier
• django-import-export - import/export data from admin page
• django-ninja - API framework similar to Fast API but tied with Django
• factory-boy - creating test data (for unit tests and staging)
• freezegun - mocking time in unit tests
• pytest - alternative to built-in unittest
• playwright / selenium - for e2e testing

Useful materials:

• https://docs.djangoproject.com/en/5.0/
• https://github.com/wsvincent/awesome-django

Frontend

• Svelte svelte
• Typescript typescript
• sass - enables scss/sass support
• axios - http requests client
• vite - bundler
• vitest, @testing-library/svelte + additional packages - unit testing components
• pnpm - package manager

Suggested packages:

• UI libraries such as shadcn-svelte, TailwindCSS, Svelte Material UI, Smelte, Carbon Components Svelte, Svelte Materialify, Sveltestrap etc.
• @tanstack/svelte-query - for data fetching, caching and server state management

Useful materials:

• https://svelte.dev/docs
• https://github.com/TheComputerM/awesome-svelte

Development setup

Without Docker

Backend

Create a virtual environment and install dependencies from Pipfile with pipenv

cd backend

mkdir .venv

pipenv shell

pipenv run pip install --upgrade pip

pipenv install

If you are not using Docker, then you need to create a .env file in the backend directory and add the following variables:

SECRET_KEY=your_secret_key

If you have multiple Python interpreters installed and you want to use version specified in the Pipfile, then you can run commands prefixed with pipenv run, otherwise first one from the system path will be used.

pipenv run COMMAND

Run django application from cmd (or add new Django configuration if using Pycharm)

python manage.py runserver

Preparing (if there are any changes to db schema) and running migrations

python manage.py makemigrations

python manage.py migrate

Create superuser

python manage.py createsuperuser

Backend tests and coverage

cd backend

Run tests using Coverage instead of python manage.py test

coverage run manage.py test

Get report from coverage:

coverage report -m

Frontend

Install node dependencies. You may use npm instead of pnpm if you wish.

cd frontend

pnpm install

Run development server in second terminal (build script in watch mode)

pnpm dev

Frontend tests and coverage

cd frontend

Run tests and gather coverage report

pnpm run test

pnpm run coverage

Run tests with Vitest in watch mode

pnpm test:watch

With Docker

IMPORTANT: You need to change CRLF to LF in entrypoint-dev.sh, entrypoint-prod.sh and entrypoint-build.sh, otherwise build will fail because Linux uses different line endings than Windows. You can do this e.g. using Pycharm, choosing LF in Line Separator at the bottom bar. Other files are not affected by this issue.

Create env directory in project's root directory and add corresponding .env files with environment variables:

env/backend.env

SECRET_KEY=your_secret_key
DJANGO_SETTINGS_MODULE=core.settings.dev

DB_NAME=postgres
DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=postgres_db
DB_PORT=5432

env/frontend.env

CHOKIDAR_USEPOLLING=true
NODE_ENV=development
DOCKER=true

env/postgres.env

POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

Make sure Docker Engine is running.

Development configuration

While in root directory, build docker images and run them with docker-compose. This might take up to few minutes. Rebuilding image is crucial after installing new packages via pip or npm.

docker-compose up --build

Application should be up and running at http://127.0.0.1:8000. Frontend build server runs in the background, does not output anything to the browser.

If images had been installed and no additional packages have been installed, just run to start containers:

docker-compose up

Bringing down containers with optional -v flag removes all attached volumes and invalidates caches.

docker-compose down

To run commands in active container:

docker exec -it CONTAINER_NAME COMMAND

e.g.

docker exec -it backend python manage.py bash

Rebuilding individual containers instead of all of them

docker-compose build CONTAINER_NAME

docker-compose build CONTAINER_NAME --no-cache

Deployment

Useful links:

• Fly.io Docs
• Fly.io CLI
• Fly.io Dashboard

Launch

To configure and launch the app, run the fly launch command and follow the wizard. You need to provision a Postgres database before launching the app.

Environment variables

Set environment variables in Fly.io dashboard or via flyctl cli.

SECRET_KEY=...
PRODUCTION_HOST=<your_app_name>.fly.dev

fly secrets set VARIABLE=...

GitHub secrets

Obtain Fly.io API key and add it as a secret to your repository to enable continuous deployments.

fly auth token

Manual deployment

fly deploy

Connect to a running instance

fly ssh console

TO DO:

• Some prettier examples (Django + Svelte integration), description, how it works
• Setup with Nginx in production (?)