Building a Project Budget Manager with Django - Part 1: Project Setup and Structure

Introduction

Welcome to the Django Project Budget Manager tutorial series! This guide is designed for beginners who want to learn Django by building a practical project management application. We'll walk through each step in detail, explaining not just what to do, but why we're doing it.

Getting the Project Template

To get started quickly, you can use(create a copy of the project template in your github without commits) our project template from GitHub:

# Use the project template
https://github.com/ChrisDevCode-Technologies/django-starter.git

#Click "use template" button at the top right corner which will provide you with a copy of the project template

#clone the repository you created using the template
git clone https://github.com/your_github_username/django-starter.git

# Navigate to the project directory
cd django-starter

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Project Structure

Our project follows a clean and organized structure. Here's what each directory and file is for:

django-starter/
├── app/                    # Main application directory
│   ├── migrations/        # Database migrations
│   ├── static/           # Static files (CSS, JS, images)
│   ├── templates/        # HTML templates
│   ├── __init__.py      # Makes this directory a Python package
│   ├── admin.py         # Admin interface configuration
│   ├── apps.py          # App configuration
│   ├── forms.py         # Form definitions
│   ├── models.py        # Database models
│   ├── tests.py         # Unit tests
│   ├── urls.py          # URL routing for the app
│   └── views.py         # View functions/classes
├── config/               # Project configuration directory
│   ├── __init__.py
│   ├── asgi.py          # ASGI configuration for async servers
│   ├── settings.py      # Project settings
│   ├── urls.py          # Main URL routing
│   └── wsgi.py          # WSGI configuration for web servers
├── docs/                # Documentation directory
├── static/             # Project-level static files
├── templates/          # Project-level templates
├── .env               # Environment variables (create this)
├── .gitignore        # Git ignore file
├── manage.py         # Django management script
└── requirements.txt  # Project dependencies

Environment Setup

1. Create a .env file in your project root:

# .env
DEBUG=True
SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=sqlite:///db.sqlite3

1. Update settings.py to use environment variables:

# config/settings.py

import os
from pathlib import Path
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Build paths inside the project
BASE_DIR = Path(__file__).resolve().parent.parent

# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = os.getenv('SECRET_KEY')

# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = os.getenv('DEBUG', 'False') == 'True'

ALLOWED_HOSTS = os.getenv('ALLOWED_HOSTS', '').split(',')

# Application definition
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'app.apps.AppConfig',  # Our main application
]

# ... rest of the settings ...

URL Configuration

Let's set up the URL routing:

# config/urls.py

from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # Admin interface URLs
    path('admin/', admin.site.urls),

    # Our app URLs
    path('', include('app.urls')),
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

# app/urls.py

from django.urls import path
from . import views

app_name = 'app'  # Namespace for our URLs

urlpatterns = [
    # Home page
    path('', views.dashboard_view, name='dashboard'),

    # Project URLs
    path('projects/', views.project_list, name='project_list'),
    path('projects/create/', views.project_create, name='project_create'),
    path('projects/<int:pk>/', views.project_detail, name='project_detail'),

    # ... more URL patterns will be added later ...
]

Database Configuration

By default, we're using SQLite for development. The database configuration is in settings.py:

# config/settings.py

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

Static and Media Files

Configure static and media files in settings.py:

# config/settings.py

# Static files (CSS, JavaScript, Images)
STATIC_URL = '/static/'
STATICFILES_DIRS = [BASE_DIR / 'static']
STATIC_ROOT = BASE_DIR / 'staticfiles'

# Media files (User uploads)
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

Initial Setup Commands

Run these commands to set up your database and create a superuser:

# Make migrations
python manage.py makemigrations

# Apply migrations
python manage.py migrate

# Create a superuser (admin)
python manage.py createsuperuser

# Run the development server
python manage.py runserver

Testing the Setup

1. Visit http://127.0.0.1:8000/ - You should see the default landing page
2. Visit http://127.0.0.1:8000/admin/ - You should be able to log in with your superuser credentials

Next Steps

In Part 2, we'll create our database models and set up the Django admin interface. We'll define the structure for our projects, tasks, and user profiles.

Common Issues and Solutions

1. ModuleNotFoundError: No module named 'dotenv'

   • Solution: Run pip install python-dotenv

2. Database migration errors

   • Solution: Delete the db.sqlite3 file and all files in migrations folders (except __init__.py), then run migrations again

3. Static files not loading

   • Solution: Make sure DEBUG=True in development
   • Run python manage.py collectstatic

4. Import errors

   • Solution: Make sure your virtual environment is activated
   • Check that all requirements are installed: pip install -r requirements.txt

Additional Resources

• Official Django Documentation
• Django Project Template Source
• Python Virtual Environments Guide

Remember to never commit sensitive information like secret keys or database credentials to version control. Always use environment variables for such data.

---

Continue to Part 2: Authentication and Models to learn how to implement user authentication and create our data models.