Django Starter

A starter project for Django with Docker, PostgreSQL, HTMX, and more.

Quick Start

Prerequisites

Docker, Docker Compose, and uv installed on your machine.

Setup and Run

Clone the repository:

git clone https://github.com/yourusername/django-starter.git
cd django-starter

Install pre-commit hooks:
```
uv run pre-commit install
```
Set up environment variables: Simply copy-paste the .env.example and adjust where necessary. For generating a secret key, you can run this:
```
uv run python -c "import secrets; print(''.join(secrets.choice('abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_+)') for i in range(50)))"
```
Copy the output and paste it into the .env file.
Make startup scripts executable: In local development, these files are mounted so you need to make these executable. Not needed for production.
```
chmod +x start.sh
chmod +x entrypoint.sh
```
Start the Docker environment:
```
docker compose -f docker-compose.yml -f docker-compose.local.yml up --build
```
This will automatically apply migrations, create a superuser (if credentials are provided in the .env file), and collect static files.
Access the application:
- Visit http://localhost:8000 in your browser.

Development Workflow

Running Management Commands

While the entrypoint script handles initial setup tasks, you may need to run other management commands during development:

Make Migrations: After making changes to your models, run:
```
docker compose exec app python manage.py makemigrations
```

Apply Migrations: To apply new migrations:

docker compose exec app python manage.py migrate

Create Superuser: If you need to create a superuser manually:
```
docker compose exec app python manage.py createsuperuser
```
Run Tests:
```
docker compose exec app pytest
```

Collect Static Files:

docker compose exec app python manage.py collectstatic --noinput

Note that you could alias docker compose exec app python manage.py to dmanage by adding this to your Powershell profile (code $PROFILE):

function dmanage {
    param(
        [Parameter(ValueFromRemainingArguments=$true)]
        [string[]]$args
    )
    docker compose exec app python manage.py $args
}

Frontend Development

Install frontend dependencies:
```
cd node
npm install
```
Run Tailwind in watch mode:
```
npm run build
```

Minify CSS and collect static for production:

npm run minify
cd .. && docker compose exec app python manage.py collectstatic --noinput

Debugging

To debug the application with VSCode using Docker Compose:

Start Services in Debug Mode:

docker compose -f docker-compose.yml -f docker-compose.debug.yml up --build

Attach Debuggers in VSCode:
- Django App: Select 'Attach to App' and press F5.
- Celery Worker: Select 'Attach to Celery' and press F5.

Note: Both services will wait for the debugger to attach before starting.

This setup allows you to debug both the Django application and the Celery worker effectively.

Detailed Setup

Running Without Docker

If you prefer to run without Docker, you will need to set up a PostgreSQL database locally and update your .env file accordingly. Follow these steps:

Set up a PostgreSQL database locally.
Run migrations:
```
uv run python manage.py migrate
```
Create superuser:
```
uv run python manage.py createsuperuser
```
Run development server:
```
uv run python manage.py runserver
```

Email Setup

For email notifications to work, you need to:

Set up an email account and add the credentials to the .env file.
Set the domain your app is running on in the Django admin -> Sites -> Sites -> example.com.

If you want to use Google's SMTP server, you need to create an app password for the account you want to use and add it to the .env file.

Quality Checks

Run tests:
```
docker compose exec app pytest
```

Run code formatting:

uv run ruff check .
uv run ruff format --check .

Additional Information

Using Flowbite: Convert Tailwind classes to DaisyUI classes for consistent styling.
Environment Variables: Ensure all necessary environment variables are set in your .env file.

Troubleshooting

Database Issues: Ensure your Docker volumes are set up correctly to persist data.
Docker Logs: Use docker compose logs to view logs and troubleshoot issues.

jsnyde0/django-starter