Thorgate's Django template
Django project template that we use at Thorgate.
Best suited for medium-sized and bigger apps that use JavaScript and React for frontend or single page web applications.
(note that the primary repo is in Gitlab, with mirror in Github)
Features
-
Django-based backend
- Django
- Separate settings for different environments (local/staging/production)
- Python 3.6 or later
- [SPA] Accessible from port
3000for local development - [SPA-NEXT] Accessible from port
3000for local development
-
Frontend app with JavaScript (ES2015), React and Sass
- Latest JavaScript features from ES2015 and beyond, transpiled with Babel
- React for fast modular user interfaces
- Sass, PostCSS and Autoprefixer for more convenient styling
- Webpack is used to bundle and minify JavaScript and styles
- [SPA] Razzle for preconfigured isomorphic application
- [SPA] Accessible from port
8000for local development
-
Batteries
- Docker / Docker Compose integration
- Linting of Python, JavaScript and Sass code with Prospector, ESLint and stylelint
- Automated code-formatting using black and prettier
- py.test and coverage integration
- Deploy helpers, using Ansible
- Optional Kubernetes / ArgoCD deploy scaffold (experimental,
use_kubernetes), see Kubernetes / Helm deployment - Media files are stored in a CDN like S3 or Google Cloud Storage
- Out-of-the-box configuration for nginx, gunicorn and logrotate
- Includes PyCharm project config
Usage
To use this template, first ensure that you have Poetry available.
After that, you should:
- Install the requirements of the project template by running
poetry install - Activate the virtualenv created by poetry:
https://python-poetry.org/docs/managing-environments/#activating-the-environment
eval $(poetry env activate) -
Navigate to the directory where you'd like to create your project:
cd /home/my-awesome-projects/ -
Create a new project by executing:
cookiecutter dir/to/django-project-template/
It will ask you a few questions, e.g. project's name, python version and so on. For a reference of all the configuration options see CookiecutterVariables.md file.
To create isomorphic single-page application set frontend_style == spa. Then separate node application will be created supported by Razzle
After generation completes, you should deactivate virtual environment for cookiecutter, search for any TODOs in the code and make appropriate changes where needed.
See README.md in the generated project for instructions on how to set up your development environment.
Different frontend styles
SPA
Isomorphic Javascript single-page application rendered with node and backed by Django Rest Framework. Enabled with frontend_style == spa.
During development and production separate node container is used to run and serve assets if needed.
Translations are done with i18next and its companion library for React.
Webapp
React powered application rendered with Django templates. This is the default option. Enabled with frontend_style == webapp.
During development separate container is used to build assets. In production, node built with multi-stage image.
Translations are done with Django JavaScriptCatalog.
Kubernetes / Helm deployment
Experimental. Enable it with the use_kubernetes cookiecutter variable
(see CookiecutterVariables.adoc). It generates a helm_deploy/dev/
scaffold that deploys the project through ArgoCD on the Thorgate platform,
alongside the ansible flow rather than replacing it.
What gets generated
helm_deploy/dev/values.yamlandimages.yaml: config for thephoenixHelm chart.images.yamlis kept separate so argocd-image-updater can bump the image tag without touching the rest of the config.helm_deploy/dev/extra/: a kustomize overlay applied alongside the chart. It holds the namespace, a ConfigMap and the movetokubePostgres/PostgresUserCRs.k8_deploy/argocd/imageupdater-dev.yaml: the argocd-image-updaterImageUpdaterCR. It is applied by the platform into the central ArgoCD's namespace rather than into the app's own cluster.helm_deploy/dev/secrets/: gitignored plaintext Secret templates (registry pull creds, Django env, node env), pre-filled with generated random keys the same wayansible/host_vars/*/vault.ymlis. Fill in theREPLACE_MEplaceholders, runsecrets/seal.sh, and commit only the resulting SealedSecrets inextra/. See the generatedhelm_deploy/dev/secrets/README.md.
ArgoCD consumes these as one multi-source Application (the extra/ overlay,
the phoenix chart, and the repo's values). For the flow, the cluster
prerequisites, and how to run it on your own ArgoCD, see
docs/argocd-deployment.md.
For Thorgate projects there's nothing to set up by hand: the platform's
ApplicationSet discovers the repo once it's tagged argo-managed, and the
concrete wiring lives in Thorgate's internal gitops repository.
Conventions the scaffold depends on (don't regress these)
- The chart version in
values.yamlis pinned to an exact build, not the floating-devtag. The pinned build fixes init containers rendering with no image tag (:latest), which the registry never pushes, so pods would otherwise hang inInit:ImagePullBackOff. - SealedSecrets go in
extra/as plain, sync-waved resources (argocd.argoproj.io/sync-wave: "-1"), never as ArgoCD or Helm hooks. A hook resource is not tracked as part of the Application, and the default hook-delete-policy (BeforeHookCreation) deletes it before every sync, so an interrupted sync leaves the SealedSecret - and its derived Secret (for example the registry pull secret) - gone, and podsImagePullBackOffon their next restart. Sync-waves apply the Secret before the chart's wave-30 Deployment (same mechanism as the Postgres CRs below) while keeping it tracked and self-healed.helm_deploy/dev/secrets/seal.shstamps that annotation on everything it writes, so this holds by default. - The generated
.gitignoreignoreshelm_deploy/*/secrets/*.yaml, and git applies that nested.gitignoreinside this repo too. Adding a new plaintext template under{{cookiecutter.repo_name}}/helm_deploy/dev/secrets/therefore needsgit add -f, or it is silently skipped. - The movetokube operator provisions Postgres through sync-wave CRs, not helm
hooks, which would rotate the password on every sync. The platform's ArgoCD
config (
argocd-cm) gates the CR health onstatus.succeeded=true, so the chart's wave-30 resources wait for the database and its credentials Secret. - The branch in
k8_deploy/argocd/imageupdater-dev.yaml(allowTagsand the write-backbranch) comes from thedefault_git_branchglobal inextensions/tg_filters.py: it readsgit symbolic-refand falls back tomasterto match whathooks/post_gen_project.pychecks the new repo out as. If you change that hook's branch, keep the fallback in sync. - k8s object names and hostnames run through the
as_hostnamefilter (underscores become hyphens) for DNS-1123; postgres database/role names and image paths keep underscores.
Status / roadmap
This is pre-1.0, so chart values may move between Phoenix versions; prefer the
ansible flow for production until it settles. The confident_curie and
eager_cannon template-test projects have no k8s counterpart yet. The
circular_orbit project is meant to fill that role and run a full lifecycle
(deploy, cutover, a few image-updater cycles, token rotation) before this is
recommended for production.
Upgrading project template
First ensure you have a python3 interpreter with cookiecutter installed.
To upgrade an existing project, change the current working directory to the root of the project you want to upgrade. i.e. cd project-to-upgrade. Ensure your have not checked out the template branch.
Then run python ~/path/to/django-project-template/upgrade-template.py
This will make a commit to the branch template in your project with the updates to the project template. Then merge the template branch.
Applying codemods
First activate Python 3 interpreter with required dependencies and ensure docker is installed and working.
Change the current working directory to the root of the project you want to apply codemods for. i.e. cd project-to-upgrade.
Then run python ~/path/to/django-project-template/upgrade-template.py --apply-frontend-codemods
This will build custom docker image to update old frontend versions.
Docker images
The template uses our own images for CI runs. One for the template itself and a second one for generated projects. Both images are alpine based and contain python3, pip and some support packages. The images are published to repository container registry and also to docker hub.
The images are built in CI (from default branches only) and also updated every day via schedules.
Project CI Image
- Dockerfile-ci
- Image in repository registry:
registry.gitlab.com/thorgate-public/django-project-template/ci - Image in docker hub:
thorgate/django-template-ci - see online
Template CI Image:
- Dockerfile-base-ci
- Image in repository registry:
registry.gitlab.com/thorgate-public/django-project-template/base-ci - Image in docker hub:
thorgate/django-template-base-ci - see online