Hydra

About

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!

Prerequisites

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 git@github.com: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:
- npm
python3, although pyenv is recommended to manage versions
- cookiecutter
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

For Windows Users:

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

For Users With Existing Development Environments:

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

Quick Start

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

Before you create any projects with this template

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.

Setting up the project

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.

If you are setting up a new project from scratch

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

If you are settiing up a project that someone else created

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

Testing the Template

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

Testing/Validation within your Project

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

Installing

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.

Install JavaScript dependencies

$ npm install

Install Python Dependencies

$ ./scripts/setup_python.sh

but once that's been run the first time you can just run

$ poetry install

Configuring environment variables

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.

Accessing Environment Variables in Python

Env vars are available in all settings file, more details here https://django-environ.readthedocs.io/en/latest/index.html

Accessing Environment Variables in JavaScript/TypeScript

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

Running the local development servers

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

Deployment