Hydra is a robust project template which uses Django 4 on the backend and HTMX, AlpineJS, and Tailwind on the frontend.
This combination of technologies means:
- You'll spend less time writing custom Javascript
- Keep frontend code near the locality of behavior
- You'll leverage the strengths of both Django and consise templates to render content quickly and easily
- You'll be easily able to extend this template for customized use cases
But perhaps the best thing about Hydra is that once you're familiar with it, it's just fun to use!
NOTE: For Mac systems, the following script will handle installing the entirety of the project, including the prerequisites below.
Run the following to complete installation:
git clone [email protected]:Lightmatter/django-hydra.git
./django-hydra/scripts/mac_intel_install.sh
It's recommended that you read the output of this script to ensure everything went smoothly, particularly if you are using Apple silicone (M1-based-mac).
The following items are required in order for Hydra to function:
- node:
- python3, although pyenv is recommended to manage versions
- bash (WSL2 or Cygwin recommended for windows users)
- postgres
- poetry virtual environment/package manager (requires python 3.11+)
- direnv handles activating your virtual env when you enter the project directory
- In order for poetry to run on the correct python version, you will want to make sure that python3 resolves to python 3.11 in your shell
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python3 -
n.b. if you are using a bash shell, you should run the version of this command in the macOS section above
- Make sure you upgrade to the latest, node (at least 18.x.x at time of writing), python (at least 3.11.1 at time of writing) and poetry (at least 1.3.1 at time of writing) versions
- if upgrading your poetry version, make sure you clear the caches
The following is the quickest path to get your project up and running, for more details on the project itself or more help getting started, visit Hydra's Documentation on Read the Docs
- Ensure that your git is properly setup with your username and email in order for the initial commit to have the correct log.
- Project names must be composed of lowercase alphanumeric characters only, with no spaces or special characters.
There are two main scripts that you need to know about in this template, create_new_project.sh
and setup_existing_project.sh
.
These both do pretty much what they say, however here is an expanded list of what each will do when run:
- Create a poetry/direnv virtual environment
- install python and js requirements (dev and regular) via poetry and npm (or optionally yarn)
- Create a database
- Run the django migrations
- Setup git
You should now follow the below guide depending on whether you are setting up a new project entirely, or getting spun up on a new one.
Run the below commands in order:
- Clone the template
$ git clone https://github.com/Lightmatter/django-hydra
- at the moment you will also want to do the following before running step 2:
$ cd django-hydra
$ cd ..
- While in the directory containing/directly above the django-hydra directory, use cookiecutter to create a new version of the project through the following command:
$ cookiecutter django-hydra
It will ask you the following questions about your project, with the default in brackets:
1.) Project Name (directory-friendly syntax) 2.) Verbose Project Name 3.) Repo Name 4.) Author Name 5.) Author Email 6.) Organization Name 7.) Project Description 8.) Domain Name 9.) Project Version
Once you've answered the prompts, your project will be created in the same directory as django-hydra
- Navigate into the project directory that you just created
$ cd <project_name>
You may see an error output initially (missing .env file) as you navigate into the directory. We'll create that .env file and complete project set up by running:
$ ./scripts/create_new_project.sh
- Run Django server with runserver_plus
$ ./manage.py runserver_plus
- In a new shell tab/window navigate to the project directory and run the vite server
$ npm run dev
- You will now be able to view the project at http://127.0.0.1:8000/ or http://localhost:8000
Run the below commands in order:
The recommended start pattern is described below. The setup_existing_project.sh command will
- install python and js requirements (dev and regular) via poetry and (or optionally yarn)
- create a database
- run the migrations
- and setup git
- Grant permissions to the
setup_existing_project.sh
$ chmod +x ./scripts/setup_existing_project.sh
- Execute the
setup_existing_project
script
$ ./scripts/setup_existing_project.sh
- Run Django server with runserver_plus
$ ./manage.py runserver_plus
- In a new shell tab/window navigate to the project directory and run the vite server with npm run dev
$ npm run dev
- You will now be able to view the project at http://127.0.0.1:8000/ or http://localhost:8000
To ensure that your template is working, you can run the test.sh
script.
The test.sh
will do a run of the template, and then run the django tests and prospector against it.
$ test.sh keepenv
Note If you do not pass the argument keepenv, it will delete the old virtualenvironment. If you want to do this, simply run
$ test.sh
This will be run automatically when you attempt to commit code but if you want to manually validate/fix your code syntax during development you can run
$ poetry run pre-commit run --all-files
Django tests can be run by running
$ pytest
The setup_existing_project.sh
and the create_new_project.sh
scripts will automatically install both the JavaScript and the Python dependencies, however if you need to install them yourself manually at a later date, you can run the below commands independently to do that.
$ npm install
$ ./scripts/setup_python.sh
but once that's been run the first time you can just run
$ poetry install
Before you may develop on the app itself you will need a .env
file. Provided in the template is a .env.example
which can be copy and pasted into a new .env file. It is worth noting that when a new project is created via create_new_project.sh
, the .env.example
will be copied to new instance under .env
. This template leverages this file using the dotenv JavaScript library as part of Vite.
Env vars are available in all settings file, more details here https://django-environ.readthedocs.io/en/latest/index.html
Env vars are available in all .js files and html script tags using the global var import.meta.env.{VARIABLE_NAME}, more details here https://vitejs.dev/guide/env-and-mode.html
This app uses webpack to compile/transpile assets. The app is equipped to be served from 127.0.0.1:8000
or localhost:8000
First run the python server
$ ./manage.py runserver_plus
Then in a new tab, run the vite server
$ npm run dev
This will be run automatically when you attempt to commit code but if you want to manually validate/fix your code syntax during development you can run
$ poetry run pre-commit run --all-files
This app is set up to use circleci, but could be extended to any build process. Circle will automatically run
$ poetry run pre-commit run --all-files
$ poetry run playwright install
$ poetry run coverage run --source='.' -m pytest