DEV Community: Teemu Virta

Building a Portfolio Site with Django REST API and Vanilla JavaScript

Teemu Virta — Wed, 31 Dec 2025 09:12:32 +0000

Building a personal portfolio site is a rite of passage for developers. Instead of reaching for a heavy frontend framework, I decided to keep things simple: Django REST Framework for the backend API, vanilla JavaScript for dynamic content, and CSS variables for theming. Here's how I built teemu.tech.

What You'll Learn

By the end of this article, you'll understand how to:

Structure a Django project with split settings for development and production
Build a REST API that serves content to a JavaScript frontend
Implement a light/dark theme toggle using CSS variables
Add privacy-friendly analytics with GDPR compliance
Build a responsive mobile navigation system
Set up automated deployment with GitHub Actions

Architecture Overview

The site follows an API-driven architecture. Django serves HTML templates as shells, then JavaScript fetches data from REST endpoints to populate the content dynamically.

┌─────────────────────────────────────────────────────────────┐
│                        Browser                               │
├─────────────────────────────────────────────────────────────┤
│  HTML Templates          JavaScript (fetch)                  │
│  ┌─────────────┐        ┌──────────────────┐                │
│  │ index.html  │───────>│ GET /api/blog/   │                │
│  │ blog.html   │        │ GET /api/projects│                │
│  │ etc.        │        │ GET /api/settings│                │
│  └─────────────┘        └────────┬─────────┘                │
└──────────────────────────────────┼──────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────┐
│                    Django Backend                            │
├─────────────────────────────────────────────────────────────┤
│  Django REST Framework          Analytics Middleware         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ /api/blog/   │  │ /api/projects│  │ /api/settings│       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
│         │                 │                 │                │
│         ▼                 ▼                 ▼                │
│  ┌─────────────────────────────────────────────────┐        │
│  │     SQLite (local) / MySQL (production)          │        │
│  └─────────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────────┘

This approach gives you the best of both worlds: Django handles data, authentication, and admin; JavaScript handles dynamic rendering without page reloads.

Tech Stack

Layer	Technology
Backend	Django 5.x, Django REST Framework
Frontend	Vanilla JavaScript, CSS3 with CSS Variables
Database	SQLite (local), MySQL (production)
Markdown	Python-Markdown with Pygments syntax highlighting
Analytics	Custom Django analytics + Plausible (optional)
Deployment	PythonAnywhere
CI/CD	GitHub Actions

Project Structure

The project uses Django's app-based organization with four main apps:

teemu_tech/
├── config/                   # Project configuration
│   ├── settings/
│   │   ├── base.py          # Shared settings
│   │   ├── local.py         # Development (DEBUG=True, SQLite)
│   │   └── production.py    # Production (DEBUG=False, MySQL)
│   ├── urls.py
│   └── wsgi.py
│
├── apps/
│   ├── portfolio/           # Projects/work items
│   ├── blog/                # Blog posts with markdown
│   ├── core/                # Site settings, frontend routes
│   └── analytics/           # Page views, stats, admin dashboard
│
├── templates/               # Django HTML templates
├── static/                  # CSS, JS, images
└── manage.py

Split Settings Pattern

Instead of one monolithic settings file, I split configuration across three files. The base file contains shared settings:

# config/settings/base.py
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent.parent

INSTALLED_APPS = [
    'django.contrib.admin',
    # ... django apps
    'rest_framework',
    'apps.portfolio',
    'apps.core',
    'apps.blog',
    'apps.analytics',
]

MIDDLEWARE = [
    # ... standard middleware
    'apps.analytics.middleware.AnalyticsMiddleware',  # Track page views
]

# Analytics settings
ANALYTICS_ENABLED = True
ANALYTICS_EXCLUDE_PATHS = ['/admin/', '/api/', '/static/', '/media/']

Local development extends base with debug settings:

# config/settings/local.py
from .base import *

SECRET_KEY = 'django-insecure-dev-key-change-in-production'
DEBUG = True
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

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

Production adds security headers, MySQL, and reads secrets from environment variables:

# config/settings/production.py
from .base import *
import os

SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')
DEBUG = False
ALLOWED_HOSTS = ['teemu.tech', 'www.teemu.tech']

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST'),
    }
}

# Security settings
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

# Plausible Analytics (privacy-friendly external service)
PLAUSIBLE_DOMAIN = 'teemu.tech'

When running commands, specify which settings to use:

# Development
python manage.py runserver --settings=config.settings.local

# Production
python manage.py migrate --settings=config.settings.production

Building the REST API

Models

The site has several main models. Here's the BlogPost model with markdown support and view tracking:

# apps/blog/models.py
from django.db import models
import markdown

class BlogPost(models.Model):
    title = models.CharField(max_length=200)
    slug = models.SlugField(max_length=200, unique=True)
    content = models.TextField(help_text="Markdown content")
    tags = models.CharField(max_length=200, blank=True)
    is_published = models.BooleanField(default=False, db_index=True)
    published_at = models.DateTimeField(blank=True, null=True, db_index=True)
    view_count = models.PositiveIntegerField(default=0, db_index=True)

    @property
    def content_html(self):
        """Render markdown to HTML with syntax highlighting."""
        md = markdown.Markdown(extensions=[
            'fenced_code',
            'codehilite',
            'tables',
        ])
        return md.convert(self.content)

Serializers

I use separate serializers for list and detail views to control what data gets sent:

# apps/blog/serializers.py
from rest_framework import serializers
from .models import BlogPost

class BlogPostListSerializer(serializers.ModelSerializer):
    """Minimal data for listing pages."""
    tags = serializers.ListField(source='tags_list', read_only=True)

    class Meta:
        model = BlogPost
        fields = ['id', 'title', 'slug', 'excerpt', 'tags', 'published_at']


class BlogPostDetailSerializer(serializers.ModelSerializer):
    """Full data including rendered HTML and view count."""
    content_html = serializers.ReadOnlyField()

    class Meta:
        model = BlogPost
        fields = ['id', 'title', 'slug', 'content_html', 'tags', 
                  'published_at', 'view_count']

Views with View Count Tracking

The detail view increments view counts with session-based duplicate prevention:

# apps/blog/views.py
from django.db.models import F
from rest_framework import generics
from .models import BlogPost
from .serializers import BlogPostListSerializer, BlogPostDetailSerializer

class BlogPostDetailView(generics.RetrieveAPIView):
    serializer_class = BlogPostDetailSerializer
    lookup_field = 'slug'

    def get_queryset(self):
        return BlogPost.objects.filter(is_published=True)

    def retrieve(self, request, *args, **kwargs):
        """Override to increment view count with duplicate prevention."""
        response = super().retrieve(request, *args, **kwargs)
        instance = self.get_object()

        # Session-based duplicate prevention
        viewed_posts = request.session.get('viewed_posts', [])
        if instance.pk not in viewed_posts:
            # Increment using F() to avoid race conditions
            BlogPost.objects.filter(pk=instance.pk).update(
                view_count=F('view_count') + 1
            )
            viewed_posts.append(instance.pk)
            request.session['viewed_posts'] = viewed_posts

        return response

Privacy-Friendly Analytics

I built a custom analytics system that respects user privacy while providing useful insights.

The Analytics Models

# apps/analytics/models.py
from django.db import models
from django.utils import timezone

class PageView(models.Model):
    """Individual page view with anonymized data."""
    path = models.CharField(max_length=500, db_index=True)
    timestamp = models.DateTimeField(default=timezone.now, db_index=True)
    ip_hash = models.CharField(max_length=64, blank=True)  # Hashed, not raw IP
    session_id = models.CharField(max_length=64, blank=True, db_index=True)
    user_agent = models.CharField(max_length=500, blank=True)
    referrer = models.URLField(max_length=500, blank=True)


class DailyStats(models.Model):
    """Aggregated daily statistics for performance."""
    date = models.DateField(unique=True, db_index=True)
    total_views = models.PositiveIntegerField(default=0)
    unique_visitors = models.PositiveIntegerField(default=0)
    top_pages = models.JSONField(default=list)
    top_referrers = models.JSONField(default=list)


class ContentStats(models.Model):
    """View statistics for specific content."""
    content_type = models.CharField(max_length=20)  # 'blog' or 'project'
    content_id = models.PositiveIntegerField()
    content_title = models.CharField(max_length=200)
    view_count = models.PositiveIntegerField(default=0)
    last_viewed = models.DateTimeField(blank=True, null=True)

Middleware for Automatic Tracking

The middleware automatically tracks page views while filtering out bots and static files:

# apps/analytics/middleware.py
from django.utils.deprecation import MiddlewareMixin
from .models import PageView
from .utils import get_client_ip, hash_ip, should_track_request

class AnalyticsMiddleware(MiddlewareMixin):
    def process_response(self, request, response):
        # Only track successful GET requests
        if request.method != 'GET' or not (200 <= response.status_code < 300):
            return response

        if not should_track_request(request):
            return response

        # Hash IP with daily salt for privacy
        client_ip = get_client_ip(request)
        ip_hash = hash_ip(client_ip)

        PageView.objects.create(
            path=request.path,
            ip_hash=ip_hash,
            session_id=request.session.session_key or '',
            user_agent=request.META.get('HTTP_USER_AGENT', '')[:500],
            referrer=request.META.get('HTTP_REFERER', '')[:500],
        )

        return response

Privacy-First IP Hashing

IPs are hashed with a daily salt, making long-term tracking impossible while allowing same-day unique visitor detection:

# apps/analytics/utils.py
import hashlib
from datetime import date
from django.conf import settings

def get_daily_salt():
    """Generate a daily salt for IP hashing."""
    secret = settings.SECRET_KEY[:20]
    today = date.today().isoformat()
    return f"{secret}-{today}"

def hash_ip(ip_address):
    """Hash IP with daily salt for privacy."""
    if not ip_address:
        return ''
    salt = get_daily_salt()
    combined = f"{ip_address}-{salt}"
    return hashlib.sha256(combined.encode()).hexdigest()

Bot Detection

The system filters out common crawlers and bots:

BOT_PATTERNS = [
    r'bot', r'crawler', r'spider', r'googlebot', r'bingbot',
    r'curl', r'wget', r'python-requests', r'headless',
]

def is_bot(user_agent):
    if not user_agent:
        return True
    return any(re.search(p, user_agent, re.I) for p in BOT_PATTERNS)

Admin Dashboard

The analytics app includes a custom admin dashboard with Chart.js visualizations showing daily views, top pages, and top referrers.

Mobile Navigation

The site features an off-canvas mobile menu that slides in from the right:

HTML Structure

<nav class="nav">
    <a href="/" class="nav-logo">TEEMU VIRTA</a>
    <button class="nav-toggle" onclick="toggleMobileMenu()">
        <span></span>
        <span></span>
        <span></span>
    </button>
    <div class="nav-links">
        <a href="/#skills">Skills</a>
        <a href="/#blog">Blog</a>
        <a href="/#about">About</a>
    </div>
    <button class="theme-toggle" onclick="toggleTheme()">...</button>
</nav>
<div class="nav-overlay" onclick="closeMobileMenu()"></div>

CSS for the Slide-in Menu

@media (max-width: 768px) {
    .nav-toggle {
        display: flex;
    }

    .nav-links {
        position: fixed;
        top: 0;
        right: 0;
        width: 280px;
        height: 100vh;
        background: var(--bg-secondary);
        flex-direction: column;
        padding: 80px 30px;
        transform: translateX(100%);
        transition: transform 0.3s ease;
        z-index: 99;
    }

    .nav-links.active {
        transform: translateX(0);
    }

    .nav-overlay.active {
        display: block;
        opacity: 1;
    }

    body.menu-open {
        overflow: hidden;
    }
}

JavaScript for Menu Control

function toggleMobileMenu() {
    const navToggle = document.querySelector('.nav-toggle');
    const navLinks = document.querySelector('.nav-links');
    const navOverlay = document.querySelector('.nav-overlay');

    navToggle.classList.toggle('active');
    navLinks.classList.toggle('active');
    navOverlay.classList.toggle('active');
    document.body.classList.toggle('menu-open');
}

function closeMobileMenu() {
    // Remove all active classes
    document.querySelector('.nav-toggle').classList.remove('active');
    document.querySelector('.nav-links').classList.remove('active');
    document.querySelector('.nav-overlay').classList.remove('active');
    document.body.classList.remove('menu-open');
}

// Close menu on scroll
window.addEventListener('scroll', function() {
    if (document.body.classList.contains('menu-open')) {
        closeMobileMenu();
    }
}, { passive: true });

Frontend: Dynamic Content Loading

The HTML templates are shells that JavaScript populates. Here's how the blog section works:

<!-- templates/index.html -->
<section id="blog" class="blog-section">
    <div class="blog-grid" id="blog-grid">
        <div class="loading">Loading articles...</div>
    </div>
</section>

JavaScript fetches from the API and renders the content:

// Fetch blog posts and render cards
fetch('/api/blog/')
    .then(response => response.json())
    .then(posts => {
        const grid = document.getElementById('blog-grid');
        grid.innerHTML = '';

        posts.slice(0, 3).forEach(post => {
            const card = document.createElement('a');
            card.href = `/blog/${post.slug}/`;
            card.className = 'blog-card';

            // Format the date
            const date = new Date(post.published_at);
            const formattedDate = date.toLocaleDateString('en-US', { 
                year: 'numeric', 
                month: 'short', 
                day: 'numeric' 
            });

            card.innerHTML = `
                <p class="blog-card-date">${formattedDate}</p>
                <h3 class="blog-card-title">${post.title}</h3>
                <p class="blog-card-excerpt">${post.excerpt || ''}</p>
            `;
            grid.appendChild(card);
        });
    });

Light/Dark Theme Toggle

The theme system uses CSS variables. Define colors once, override them for light mode:

/* static/css/style.css */
:root {
    --bg-primary: #0a0a0a;
    --bg-secondary: #111111;
    --text-primary: #ffffff;
    --text-secondary: #888888;
    --accent: #00d9ff;
}

/* Light theme overrides */
[data-theme="light"] {
    --bg-primary: #ffffff;
    --bg-secondary: #f5f5f5;
    --text-primary: #1a1a1a;
    --text-secondary: #666666;
    --accent: #0099cc;
}

body {
    background: var(--bg-primary);
    color: var(--text-primary);
}

The toggle function switches themes and persists the choice:

function toggleTheme() {
    const current = document.documentElement.getAttribute('data-theme') || 'dark';
    const next = current === 'dark' ? 'light' : 'dark';
    document.documentElement.setAttribute('data-theme', next);
    localStorage.setItem('theme', next);
}

To prevent a flash of the wrong theme on page load, add this script in the <head> before CSS loads:

<script>
    (function() {
        const theme = localStorage.getItem('theme') || 'dark';
        document.documentElement.setAttribute('data-theme', theme);
    })();
</script>

Automated Deployment with GitHub Actions

Every push to main triggers automatic deployment to PythonAnywhere:

# .github/workflows/deploy.yml
name: Deploy to PythonAnywhere

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ssh.pythonanywhere.com
          username: ${{ secrets.PYTHONANYWHERE_USERNAME }}
          password: ${{ secrets.PYTHONANYWHERE_PASSWORD }}
          script: |
            cd ~/teemu_tech
            source ~/.virtualenvs/teemu_tech_env/bin/activate
            git pull origin main
            pip install -r requirements.txt
            python manage.py migrate --settings=config.settings.production
            python manage.py collectstatic --noinput --settings=config.settings.production

      - name: Reload web app
        run: |
          curl -X POST \
            https://www.pythonanywhere.com/api/v0/user/${{ secrets.PYTHONANYWHERE_USERNAME }}/webapps/${{ secrets.PYTHONANYWHERE_USERNAME }}.pythonanywhere.com/reload/ \
            -H "Authorization: Token ${{ secrets.PYTHONANYWHERE_API_TOKEN }}"

Scheduled Tasks for Analytics

PythonAnywhere scheduled tasks handle daily analytics maintenance:

# Aggregate daily stats (run at 00:15 UTC)
cd ~/teemu_tech && source ~/.virtualenvs/teemu_tech_env/bin/activate && \
python manage.py aggregate_daily_stats --settings=config.settings.production

# Cleanup old data after 90 days (run at 00:30 UTC)
cd ~/teemu_tech && source ~/.virtualenvs/teemu_tech_env/bin/activate && \
python manage.py cleanup_analytics --settings=config.settings.production

Key Takeaways

1. You don't always need a frontend framework. For a portfolio site, vanilla JavaScript with fetch() is plenty. The bundle size is zero, and there's no build step.

2. Split settings keep environments clean. Having separate files for local and production prevents accidentally running debug mode in production.

3. API-driven architecture adds flexibility. The same API could power a mobile app or be consumed by other services. Content changes in Django admin appear instantly on the frontend.

4. CSS variables make theming simple. Define your colors once, override them with a data attribute, and the entire site responds.

5. Privacy-friendly analytics is achievable. You can track useful metrics without storing personal data. Hash IPs with daily salts, filter bots, and aggregate data for insights.

6. GitHub Actions + PythonAnywhere = free CI/CD. Push to main, grab a coffee, and your changes are live.

Conclusion

Building teemu.tech taught me that simplicity often wins. Django's admin handles content management, REST Framework serves data efficiently, and vanilla JavaScript renders it without the overhead of a framework. The custom analytics system provides useful insights while respecting user privacy.

If you're building a portfolio or blog, consider this stack. It's powerful enough for production use, simple enough to understand completely, and flexible enough to grow with your needs.

Tutorial by Teemu Virta - teemu.tech

Best Practices for VFX Pipeline Automation with Python

Teemu Virta — Sat, 20 Dec 2025 14:03:22 +0000

Pipeline automation transforms chaotic VFX production into smooth, predictable workflows. When done right, automation eliminates repetitive tasks, prevents costly mistakes, and lets artists focus on creative work instead of file management. The best part? You don't need expensive proprietary tools. Python gives you everything needed to build professional pipeline solutions that scale from small teams to major productions.

This guide covers five battle-tested best practices for VFX pipeline automation. These patterns are studio-agnostic and proven to save hours of manual work daily while dramatically reducing human error. Whether you're a solo artist streamlining personal workflows or building tools for a team, these techniques will make your production pipeline bulletproof.

Why Automate Your Pipeline?

Before diving into techniques, understand what pipeline automation delivers:

Time Savings: Tasks that take 5 minutes manually become instant. Multiply that across dozens of daily operations and hundreds of artists.

Consistency: Every project follows the same structure. Every file uses the same naming. No more "where did I save that?"

Error Prevention: Automated validation catches mistakes before they cascade through production. Wrong file versions, missing assets, and broken paths become rare.

Scalability: Tools that work for one artist work for fifty. Your pipeline grows with your projects without adding overhead.

Knowledge Preservation: Your pipeline code documents how things work. New team members learn your workflow by reading the tools.

Prerequisites

Before diving in, you should have:

Basic Python knowledge (variables, functions, loops, dictionaries)
A text editor or IDE (VS Code, PyCharm, or similar)
Understanding of file systems and directory structures
Python 3.7 or higher installed on your system

No specific VFX software knowledge is required - we'll focus on universal concepts that work anywhere.

Five Core Principles

1. Keep It Simple - Future you (and your colleagues) need to understand this code. Clear beats clever.

2. Make It Modular - Write functions that do one thing well. Reuse everywhere.

3. Validate Everything - Never trust input. Users make mistakes. File paths break. Validate first, process second.

4. Log Everything - When tools fail at 3 AM, logs are your only friend. Log inputs, outputs, decisions, and errors.

5. Handle Errors Gracefully - Anticipate failures. Catch errors. Guide users toward solutions with clear messages.

Best Practice #1: Standardized Directory Structures

The Problem: Artists waste time searching for files. Projects have inconsistent organization. New team members get lost.

The Benefit: One standard structure means everyone knows exactly where everything lives. Tools can rely on predictable paths. Onboarding becomes trivial.

A typical VFX project structure:

PROJECT_ROOT/
├── assets/
│   ├── characters/
│   ├── props/
│   ├── environments/
│   └── fx/
├── shots/
│   ├── seq010/
│   └── seq020/
├── render/
├── reference/
└── scripts/

Here's a Python tool that creates this automatically:

from pathlib import Path
from datetime import datetime

class ProjectStructure:
    """Creates standardized VFX project directories."""

    STRUCTURE = {
        'assets': {
            'characters': [],
            'props': [],
            'environments': [],
            'fx': []
        },
        'shots': {},
        'render': ['preview', 'final'],
        'reference': [],
        'scripts': []
    }

    def __init__(self, project_name, root_path):
        self.project_name = project_name
        self.project_root = Path(root_path) / project_name

    def create_structure(self):
        """Create the entire project directory structure."""
        if self.project_root.exists():
            print(f"Warning: Project '{self.project_name}' already exists!")
            return False

        self._create_recursive(self.project_root, self.STRUCTURE)

        # Add project metadata
        info_file = self.project_root / 'project_info.txt'
        with open(info_file, 'w') as f:
            f.write(f"Project: {self.project_name}\n")
            f.write(f"Created: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")

        print(f"Project created at: {self.project_root}")
        return True

    def _create_recursive(self, base_path, structure):
        """Recursively create directories from nested dictionary."""
        for name, contents in structure.items():
            current_path = base_path / name
            current_path.mkdir(parents=True, exist_ok=True)

            if isinstance(contents, dict):
                self._create_recursive(current_path, contents)
            elif isinstance(contents, list):
                for subdir in contents:
                    (current_path / subdir).mkdir(exist_ok=True)

# Usage
project = ProjectStructure("awesome_commercial", "/projects")
project.create_structure()

Impact: Creating a new project takes 2 seconds instead of 15 minutes. Every project is identical. Tools work immediately without path configuration.

Best Practice #2: File Naming Conventions

The Problem: Files named inconsistently. Can't parse information from filenames. Version chaos.

The Benefit: Automated version detection. Easy sorting and filtering. Tools that understand your files.

Standard VFX naming pattern:

{asset_type}_{asset_name}_{variant}_{version}.{extension}

Examples:
char_hero_model_v001.ma
prop_table_rig_v003.mb
env_street_layout_v012.hip

Here's a naming system that validates and generates filenames:

import re
from pathlib import Path

class VFXFileName:
    """Parse and generate VFX file names following conventions."""

    PATTERN = r'^(?P<type>[a-z]+)_(?P<n>[a-z0-9_]+)_(?P<variant>[a-z]+)_v(?P<version>\d{3,4})$'

    def __init__(self, filepath=None):
        self.asset_type = None
        self.asset_name = None
        self.variant = None
        self.version = None
        self.extension = None

        if filepath:
            self.parse(filepath)

    def parse(self, filepath):
        """Extract naming components from filepath."""
        path = Path(filepath)
        self.extension = path.suffix.lstrip('.')
        filename_no_ext = path.stem

        match = re.match(self.PATTERN, filename_no_ext)
        if not match:
            print(f"Warning: '{filepath}' doesn't match naming convention")
            return False

        self.asset_type = match.group('type')
        self.asset_name = match.group('name')
        self.variant = match.group('variant')
        self.version = int(match.group('version'))
        return True

    def build(self, asset_type, asset_name, variant, version, extension):
        """Build filename from components."""
        # Sanitize inputs
        asset_type = asset_type.lower().replace(' ', '_')
        asset_name = asset_name.lower().replace(' ', '_')
        variant = variant.lower().replace(' ', '_')

        return f"{asset_type}_{asset_name}_{variant}_v{version:03d}.{extension}"

    def increment_version(self):
        """Bump version number."""
        if self.version is None:
            raise ValueError("No version to increment")
        self.version += 1
        return self.build(self.asset_type, self.asset_name, 
                         self.variant, self.version, self.extension)

# Usage
filename = VFXFileName()
new_file = filename.build("char", "hero", "rig", 1, "mb")
print(new_file)  # char_hero_rig_v001.mb

existing = VFXFileName("prop_table_model_v005.ma")
print(f"Version: {existing.version}")  # 5
print(f"Next: {existing.increment_version()}")  # prop_table_model_v006.ma

Impact: Zero ambiguity in file names. Tools automatically find latest versions. Sorting works correctly. Version numbers are always valid.

Best Practice #3: Automated File Versioning

The Problem: Artists manually type version numbers. Files get overwritten. No history when things break.

The Benefit: Never lose work. Always know the latest version. Automatic backups. Clean version history.

Here's a complete versioning system:

import shutil
from pathlib import Path
from datetime import datetime
import re

class FileVersionManager:
    """Manage file versions with automatic backup and increment."""

    def __init__(self, work_directory):
        self.work_dir = Path(work_directory)
        self.backup_dir = self.work_dir / '.backups'
        self.work_dir.mkdir(parents=True, exist_ok=True)
        self.backup_dir.mkdir(parents=True, exist_ok=True)

    def get_latest_version(self, base_name, extension):
        """Find the latest version of a file."""
        pattern = f"{base_name}_v*.{extension}"
        matches = list(self.work_dir.glob(pattern))

        if not matches:
            return None

        versions = []
        for match in matches:
            version_match = re.search(r'_v(\d+)', match.stem)
            if version_match:
                versions.append((int(version_match.group(1)), match))

        if versions:
            versions.sort(reverse=True)
            return versions[0][1]
        return None

    def create_new_version(self, base_name, extension, source_file=None):
        """Create next version, optionally copying from source."""
        latest = self.get_latest_version(base_name, extension)

        new_version = 1
        if latest:
            latest_num = int(re.search(r'_v(\d+)', latest.stem).group(1))
            new_version = latest_num + 1

        new_filename = f"{base_name}_v{new_version:03d}.{extension}"
        new_path = self.work_dir / new_filename

        if source_file and Path(source_file).exists():
            shutil.copy2(source_file, new_path)
        else:
            new_path.touch()

        print(f"Created: {new_filename}")
        return new_path

    def backup_version(self, filepath):
        """Create timestamped backup."""
        source = Path(filepath)
        if not source.exists():
            raise FileNotFoundError(f"File not found: {filepath}")

        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
        backup_name = f"{source.stem}_{timestamp}{source.suffix}"
        backup_path = self.backup_dir / backup_name

        shutil.copy2(source, backup_path)
        print(f"Backed up to: {backup_path}")
        return backup_path

# Usage
vm = FileVersionManager("/work/rigging")
latest = vm.get_latest_version("char_hero_rig", "mb")
new_version = vm.create_new_version("char_hero_rig", "mb")
vm.backup_version(new_version)

Impact: Version creation is instant and automatic. Old versions are safely archived. Recovery from mistakes is trivial. Artists focus on work, not file management.

Best Practice #4: Metadata Management

The Problem: File systems store data but not information about that data. Who worked on this? When was it approved? What's the status?

The Benefit: Track asset status and ownership. Search by properties. Generate reports. Build approval workflows.

Simple JSON-based metadata system:

import json
from pathlib import Path
from datetime import datetime

class AssetMetadata:
    """Manage metadata for VFX assets using JSON."""

    def __init__(self, asset_directory):
        self.asset_dir = Path(asset_directory)
        self.metadata_file = self.asset_dir / 'asset_metadata.json'
        self.data = self._load_metadata()

    def _load_metadata(self):
        """Load existing metadata or create new."""
        if self.metadata_file.exists():
            with open(self.metadata_file, 'r') as f:
                return json.load(f)
        return {'asset_info': {}, 'versions': {}}

    def _save_metadata(self):
        """Save metadata to JSON."""
        with open(self.metadata_file, 'w') as f:
            json.dump(self.data, f, indent=2)

    def set_asset_info(self, name, asset_type, description="", tags=None):
        """Set basic asset information."""
        self.data['asset_info'] = {
            'name': name,
            'type': asset_type,
            'description': description,
            'tags': tags or [],
            'created_date': datetime.now().isoformat()
        }
        self._save_metadata()

    def add_version_info(self, version, artist, notes="", status="in_progress"):
        """Add information about a version."""
        version_key = f"v{version:03d}"
        self.data['versions'][version_key] = {
            'artist': artist,
            'date': datetime.now().isoformat(),
            'notes': notes,
            'status': status
        }
        self._save_metadata()

    def get_latest_approved(self):
        """Find latest approved version."""
        approved = [
            int(k[1:]) for k, v in self.data['versions'].items()
            if v['status'] == 'approved'
        ]
        return max(approved) if approved else None

# Usage
metadata = AssetMetadata("/projects/assets/characters/hero")
metadata.set_asset_info("Hero Character", "character", 
                        tags=["hero", "main_cast"])
metadata.add_version_info(1, "john_doe", "Initial model", "in_progress")
metadata.add_version_info(2, "john_doe", "Final details", "approved")

latest_approved = metadata.get_latest_approved()
print(f"Latest approved: v{latest_approved:03d}")

Impact: Complete asset history at a glance. Status tracking without external tools. Easy reporting and queries. Team coordination becomes simple.

Best Practice #5: Cross-Department Data Exchange

The Problem: Departments work in isolation. Files copied manually. Wrong versions used. No handoff tracking.

The Benefit: Clean data exchange. Version tracking across departments. Clear audit trail. Eliminating "which version did you use?"

Workflow diagram:

┌─────────────┐      ┌──────────────┐      ┌──────────────┐
│  Modeling   │─────▶│   Rigging    │─────▶│  Animation   │
│  (publish)  │      │   (collect)  │      │   (collect)  │
└─────────────┘      └──────────────┘      └──────────────┘

Publish/collect system:

import shutil
from pathlib import Path
from datetime import datetime
import json
import re

class PublishSystem:
    """Manage asset publishing between departments."""

    def __init__(self, project_root):
        self.project_root = Path(project_root)
        self.publish_root = self.project_root / 'published'
        self.publish_root.mkdir(exist_ok=True)

    def publish_asset(self, source_file, asset_name, department, version, notes=""):
        """Publish an asset from a department."""
        source = Path(source_file)
        if not source.exists():
            raise FileNotFoundError(f"Source not found: {source_file}")

        # Create department directory
        dept_dir = self.publish_root / asset_name / department
        dept_dir.mkdir(parents=True, exist_ok=True)

        # Create versioned filename
        pub_filename = f"{asset_name}_{department}_v{version:03d}{source.suffix}"
        pub_path = dept_dir / pub_filename

        # Copy and create metadata
        shutil.copy2(source, pub_path)

        info = {
            'asset': asset_name,
            'department': department,
            'version': version,
            'date': datetime.now().isoformat(),
            'notes': notes
        }

        info_path = pub_path.with_suffix('.json')
        with open(info_path, 'w') as f:
            json.dump(info, f, indent=2)

        print(f"Published: {pub_path}")
        return pub_path

    def collect_asset(self, asset_name, from_department, to_directory):
        """Collect latest published asset."""
        dept_dir = self.publish_root / asset_name / from_department

        if not dept_dir.exists():
            print(f"No published assets from {from_department}")
            return None

        # Find latest version
        pattern = f"{asset_name}_{from_department}_v*"
        matches = [m for m in dept_dir.glob(pattern) if m.suffix != '.json']

        if not matches:
            return None

        # Get highest version
        versions = [(int(re.search(r'_v(\d+)', m.stem).group(1)), m) 
                   for m in matches]
        latest_path = max(versions)[1]

        # Copy to destination
        dest_dir = Path(to_directory)
        dest_dir.mkdir(parents=True, exist_ok=True)
        dest_path = dest_dir / latest_path.name

        shutil.copy2(latest_path, dest_path)
        print(f"Collected: {latest_path.name} to {dest_path}")

        return dest_path

# Usage
pub = PublishSystem("/projects/awesome_commercial")

# Modeling publishes
pub.publish_asset(
    "/work/modeling/hero_v005.ma",
    "hero", "modeling", 5,
    "Final model approved"
)

# Rigging collects
pub.collect_asset("hero", "modeling", "/work/rigging/source")

# Rigging publishes
pub.publish_asset(
    "/work/rigging/hero_rig_v003.mb",
    "hero", "rigging", 3,
    "Rig complete"
)

# Animation collects
pub.collect_asset("hero", "rigging", "/work/animation/rigs")

Impact: Departments never work in each other's folders. Every handoff is tracked. Always know which version was used. Collaboration friction disappears.

Putting It All Together

These five best practices work together to create a robust pipeline:

Standard Structure provides predictable file locations
Naming Conventions make files self-documenting
Version Management prevents data loss and tracks history
Metadata adds intelligence to your file system
Publish/Collect creates clean department workflows

The result? A production environment where:

Artists spend time creating, not managing files
New team members become productive in hours, not weeks
Errors are caught automatically before they cause problems
Every asset has a clear history and ownership
Collaboration happens smoothly without confusion

Common Issues & Solutions

Path Problems Across Operating Systems

Windows uses backslashes, Unix uses forward slashes. Always use pathlib:

from pathlib import Path

# DON'T
bad_path = "C:\\projects\\my_project"

# DO
good_path = Path("C:/projects/my_project")  # Works on all OS

Permission Errors

import stat
from pathlib import Path

def make_writable(filepath):
    """Remove read-only attribute."""
    path = Path(filepath)
    path.chmod(path.stat().st_mode | stat.S_IWRITE)

File Locking on Windows

import time
import shutil

def safe_copy_with_retry(source, dest, max_attempts=3):
    """Copy with retry logic for locked files."""
    for attempt in range(max_attempts):
        try:
            shutil.copy2(source, dest)
            return True
        except PermissionError:
            if attempt < max_attempts - 1:
                print(f"File locked, retrying in 2 seconds...")
                time.sleep(2)
    return False

Real-World Impact: By the Numbers

When properly implemented, pipeline automation delivers measurable results:

Time Savings

Project setup: 15 minutes → 2 seconds
Finding latest file: 30 seconds → instant
Version increment: 1 minute → 2 seconds
Department handoff: 10 minutes → 30 seconds

Error Reduction

Wrong file version used: Common → Rare
Lost work from overwrites: Frequent → Never
Misnamed files: 20% → 0%
Cross-department confusion: Daily → Almost never

Scalability

Same tools work for 1 artist or 50
Pipeline knowledge lives in code, not people
New projects start production-ready
Onboarding time reduced by 60-80%

Next Steps

Start implementing these best practices in your workflow:

Week 1: Implement standardized directory structures
Week 2: Add file naming conventions and validation
Week 3: Set up automated versioning
Week 4: Integrate metadata management
Week 5: Build publish/collect workflows

Resources for Further Learning

Python's pathlib module: Essential for file operations
json module: Data serialization for metadata
logging module: Professional-grade logging
CGWire Kitsu: Open-source production tracker (great code examples)
OpenPype: Modern open-source pipeline (study their architecture)

Practice Projects

Build an asset browser that reads your metadata
Create an automated dailies publishing system
Develop a simple asset status dashboard
Implement automated backup systems with scheduling

Conclusion

Pipeline automation with Python doesn't require complex frameworks or expensive tools. By following these five best practices, you build systems that:

Save hours of manual work daily
Prevent costly production errors
Scale effortlessly as projects grow
Document themselves through code
Empower artists to focus on creativity

The key is starting small. Pick the biggest pain point in your current workflow and automate that first. Once it's working smoothly, move to the next challenge. These small automation wins compound into a professional pipeline that makes everyone's job easier.

Remember: your pipeline code should be as well-crafted as any production asset. Keep it maintainable, document it well, and always consider the artists who will use your tools. With these patterns, you're equipped to build VFX pipeline automation that truly serves your team's needs.

Tutorial by Teemu Virta - teemu.tech

Tags: #python #vfx #pipeline #automation #beginners

Meta Description: Learn essential best practices for automating VFX pipelines with Python. Studio-agnostic guide covering file management, versioning, and cross-department workflows for beginners.

RAG vs Document Injection: Why Your AI Document Chat Needs Smart Retrieval

Teemu Virta — Wed, 17 Dec 2025 16:02:37 +0000

Have you ever wanted to chat with your PDF files using AI? The simplest way is to load all your documents and send them to the LLM with every question. But this approach has a big problem: it's expensive and doesn't scale.

In this tutorial, we'll compare two approaches:

Document Injection: Load everything (simple but expensive)
RAG (Retrieval Augmented Generation): Load only what's needed (smart and efficient)

Try it yourself: I've built an interactive web app where you can test both approaches with your own documents and see the token usage difference in real-time: https://www.teemu.tech/rag/

Upload your documents and compare Document Injection vs. Full RAG mode - watch how token counts change dramatically between the two approaches!

What You'll Learn

How document injection works and why it's expensive
What RAG is and how it saves money
Real token usage comparisons
How to implement both systems
When to use each approach

Prerequisites

You need:

Python 3.8+
Basic understanding of Python and APIs
OpenAI API key (or Google AI key)
Some documents to test with

The Problem

Let's say you have 10 PDF documents with 20 pages each. That's about 100,000 tokens. If you send all this with every question:

Cost per question: ~$3.00 (using GPT-4)
10 questions: $30.00
100 questions: $300.00

This doesn't scale. Your costs explode quickly.

Approach 1: Document Injection

How It Works

Document Injection loads ALL your documents into the system prompt. Every time you ask a question, the LLM processes everything.

Here's the flow:

User asks question
    ↓
Load ALL documents (PDFs, text files)
    ↓
Send everything to LLM
    ↓
LLM processes ALL tokens
    ↓
Get answer

The Code

First, we need a function to load documents:

# load_documents.py
from pathlib import Path
from pypdf import PdfReader


def get_documents(folder='docs'):
    """Load all text, markdown, and PDF files from a folder."""
    path = Path(folder)
    contents = []

    for file in path.rglob('*'):
        if file.suffix in {'.txt', '.md', '.pdf'}:

            if file.suffix == '.pdf':
                # Extract text from PDF
                content = ''
                reader = PdfReader(file)
                for page in reader.pages:
                    content += '\n' + page.extract_text()
            else:
                # Read text files
                content = file.read_text(encoding='utf-8')

            contents.append({str(file): content})

    return contents

Now the chat system:

# documents_injection_system.py
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.messages import SystemMessage, HumanMessage
from load_documents import get_documents


def main():
    load_dotenv()
    llm = ChatOpenAI(model='gpt-4o-mini')

    # Load ALL documents into the system prompt
    system_prompt = f"You are a helpful assistant. Answer questions about these documents: {get_documents()}"

    messages = [SystemMessage(content=system_prompt)]

    while True:
        question = input("Enter a question: ")
        if question == 'exit':
            break

        messages.append(HumanMessage(content=question))
        response = llm.invoke(messages)
        messages.append(response)
        print(response.content)


if __name__ == "__main__":
    main()

The key point: get_documents() loads EVERYTHING, and this gets sent with EVERY question.

Token Usage: Document Injection

Test with 3 PDFs (10 pages each) + 2 text files = ~15,000 tokens total

First question: "What is document1.pdf about?"

Tokens sent: 15,010
Cost: $0.15

Second question: "Summarize document2.pdf"

Tokens sent: ~15,500
Cost: $0.155

After 10 questions: ~$1.60 total

Every question processes ALL 15,000 tokens!

Pros and Cons

Pros:

Simple to implement
LLM has access to everything

Cons:

Expensive - every query processes all documents
Slow with large documents
Doesn't scale beyond small document sets
Hits token limits quickly

Approach 2: RAG System

What is RAG?

RAG (Retrieval Augmented Generation) is smarter. Instead of sending everything, it:

Converts documents into numbers (embeddings)
Stores them in a database
When you ask a question, finds only the relevant documents
Sends only those to the LLM

How It Works

User asks question
    ↓
Convert question to embedding
    ↓
Search database for similar documents
    ↓
Get top 2 most relevant documents
    ↓
Send ONLY those to LLM
    ↓
Get answer

This means instead of processing 100,000 tokens, you might only process 1,000 tokens!

The Code

# full_rag_system.py
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.messages import SystemMessage, HumanMessage
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_community.document_loaders import PyPDFDirectoryLoader, DirectoryLoader, TextLoader

load_dotenv()
os.environ["TOKENIZERS_PARALLELISM"] = "false"

directory = 'docs'

# Initialize LLM
llm = ChatOpenAI(model='gpt-4o-mini')

# Load documents
pdf_loader = PyPDFDirectoryLoader(directory)
pdf_docs = pdf_loader.load()

text_loader = DirectoryLoader(directory, glob='**/*.txt', loader_cls=TextLoader)
text_docs = text_loader.load()

docs = pdf_docs + text_docs

# Create embeddings and vector store
embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
vector_store = InMemoryVectorStore(embeddings)
vector_store.add_documents(docs)

# Chat loop
while True: 
    question = input("Enter a question: ")
    if question == 'exit':
        break

    # KEY: Only retrieve top 2 most relevant documents
    retrieved_docs = vector_store.similarity_search(question, k=2)
    context = "\n".join([doc.page_content for doc in retrieved_docs])

    # System prompt with ONLY relevant context
    system_prompt = f"Answer questions about these documents: {context}"

    messages = [SystemMessage(content=system_prompt)]
    messages.append(HumanMessage(content=question))

    response = llm.invoke(messages)
    print(response.content)

The magic happens at k=2 - we only get the 2 most relevant documents, not all of them!

Token Usage: RAG System

Same test: 3 PDFs + 2 text files = ~15,000 tokens total

First question: "What is document1.pdf about?"

Tokens sent: 1,010 (only 2 relevant chunks!)
Cost: $0.01

Second question: "Summarize document2.pdf"

Tokens sent: ~1,010
Cost: $0.01

After 10 questions: ~$0.11 total

RAG only sends relevant documents, not everything!

Pros and Cons

Pros:

90-95% cost reduction
Works with thousands of documents
Fast responses
Only processes relevant information

Cons:

More complex setup
Needs embeddings model
Initial indexing takes time

Head-to-Head Comparison

Token Usage

Metric	Document Injection	RAG System	Savings
Tokens per query	~15,000	~1,000	93%
Cost per query (GPT-4o-mini)	$0.15	$0.01	93%
100 queries	$15.00	$1.00	93%
1,000 queries	$150.00	$10.00	93%

Scalability

Documents	Document Injection	RAG System
10 files	Works (expensive)	Works (cheap)
100 files	Very expensive	Works great
1,000 files	Exceeds token limits	Works great
10,000 files	Impossible	Works great

Performance

Document Injection:

Initial load: Fast
Query speed: Slow (large context)
Cost: High

RAG:

Initial load: Slower (builds embeddings)
Query speed: Fast (small context)
Cost: Low

Getting Started

Step 1: Setup

# Create project
mkdir document-chat
cd document-chat
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Create folders
mkdir docs
touch .env

Step 2: Install Packages

pip install langchain langchain-openai langchain-huggingface
pip install langchain-community pypdf python-dotenv
pip install sentence-transformers

Step 3: Configure

Create .env file:

OPENAI_API_KEY=your_key_here

Step 4: Add Documents

Put some PDF or text files in the docs/ folder.

Step 5: Run

# Try Document Injection
python documents_injection_system.py

# Try RAG
python full_rag_system.py

Common Issues

Issue 1: Tokenizer Warning

If you see warnings about TOKENIZERS_PARALLELISM:

import os
os.environ["TOKENIZERS_PARALLELISM"] = "false"

Issue 2: Wrong Documents Retrieved

If RAG returns irrelevant documents:

# Get more documents
retrieved_docs = vector_store.similarity_search(question, k=5)

# Or split documents into smaller chunks first
from langchain.text_splitter import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
split_docs = splitter.split_documents(docs)

Issue 3: Out of Memory

For large document sets:

# Process in batches
batch_size = 100
for i in range(0, len(docs), batch_size):
    batch = docs[i:i+batch_size]
    vector_store.add_documents(batch)

When to Use Each

Use Document Injection:

Very small document set (less than 5 pages total)
Quick prototyping
You need ALL context for every answer

Use RAG:

More than 10 pages of documents
Cost matters
Production applications
Any real-world use case

Simple rule: If you're building anything real, use RAG.

Making RAG Better

Once your basic RAG works, you can improve it:

1. Split Documents Better

from langchain.text_splitter import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200
)
split_docs = splitter.split_documents(docs)

2. Save Vector Store

Instead of rebuilding every time:

from langchain_community.vectorstores import Chroma

vector_store = Chroma(
    collection_name="my_docs",
    embedding_function=embeddings,
    persist_directory="./chroma_db"
)

3. Get More Documents

If answers aren't good enough:

# Increase k to get more context
retrieved_docs = vector_store.similarity_search(question, k=5)

Real Cost Example

Scenario: Customer support chatbot with 1,000 product manuals

Document Injection:

Total: ~500,000 tokens
Problem: Exceeds token limits!
Impossible to build

RAG:

Per question: ~2,000 tokens (only relevant docs)
1,000 questions/day: 2M tokens/day
Cost with GPT-4o-mini: ~$20/day = $600/month

RAG makes impossible systems possible and affordable.

Key Takeaways

Document Injection is simple but expensive - fine for tiny documents, breaks quickly
RAG saves 90-95% on costs - by only processing relevant documents
RAG scales - works from 10 to 10,000 documents
RAG is easy to implement - just a few extra lines of code with LangChain
Use RAG for production - unless you have a very specific reason not to

Tutorial by Teemu Virta - teemu.tech

Special thanks to Ardit Sulce
Tags: #python #rag #llm #langchain #ai #openai #tutorial

How to Deploy a Django Website with Automated CI/CD Pipeline

Teemu Virta — Sat, 22 Nov 2025 16:29:22 +0000

A step-by-step guide to deploying a Django website to PythonAnywhere with automatic deployment via GitHub Actions.

📋 Project Overview

Goal: Create a personal website with:

Django backend
Custom domain (optional)
HTTPS security
Automated deployment from VS Code to production

Tech Stack:

Django 5.2.8+
PythonAnywhere hosting
GitHub Actions for CI/CD
Custom domain with SSL (optional)

Result: Push code from VS Code → Site updates automatically in production

Example project: This tutorial uses my_website as the project name. Replace it with your own project name throughout.

🎯 Prerequisites

Before starting, you need:

Python 3.10+ installed
VS Code (or any code editor)
GitHub account
PythonAnywhere account (Hacker tier for custom domains)
Custom domain (optional)

🚀 Step-by-Step Guide

Step 1: Create Django Project Locally

# Create project directory (use your own project name)
mkdir my_website
cd my_website

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install Django
pip install django

# Create Django project (replace 'my_website' with your project name)
django-admin startproject my_website .
django-admin startapp main_app

# Create requirements.txt
pip freeze > requirements.txt

# Test locally
python manage.py runserver

Visit http://127.0.0.1:8000 to verify Django works.

Note: Throughout this tutorial:

my_website = your Django project name
main_app = your Django app name
Replace these with your actual names

Step 2: Setup Git and GitHub

# Initialize Git
git init
git add .
git commit -m "Initial commit"

# Create repository on GitHub
# Then connect local to remote:
git remote add origin https://github.com/YOUR_USERNAME/my_website.git
git push -u origin main

Important: Create a .gitignore file:

*.pyc
__pycache__/
db.sqlite3
venv/
.env

Step 3: Configure Django for Production

Edit my_website/settings.py (replace my_website with your project name):

# Add this at the top
from pathlib import Path
import os  # CRITICAL - don't forget this!

# Configure allowed hosts (replace with your domain)
ALLOWED_HOSTS = [
    'yourdomain.com',           # Your custom domain
    'www.yourdomain.com',       # www version
    'YOUR_USERNAME.pythonanywhere.com'  # PythonAnywhere subdomain
]

# For production, set DEBUG = False (but keep True during setup)
DEBUG = True  # Change to False after everything works

# Add your app to INSTALLED_APPS
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'main_app',  # Your app name here
]

# Static files
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

Step 4: Deploy to PythonAnywhere

4.1 Setup on PythonAnywhere

Create account at pythonanywhere.com
- Free tier works for testing
- Hacker tier ($5/month) needed for custom domains
Open Bash console and clone your repo:

# Replace YOUR_USERNAME and my_website with your values
git clone https://github.com/YOUR_USERNAME/my_website.git
cd my_website

Create virtual environment:

# Replace my_website_env with your preferred name
mkvirtualenv --python=/usr/bin/python3.10 my_website_env
pip install -r requirements.txt

Configure Web App:
- Go to Web tab
- Add new web app
- Choose "Manual configuration"
- Python 3.10
- Set source code: /home/YOUR_USERNAME/my_website
- Set working directory: /home/YOUR_USERNAME/my_website
- Set virtualenv: /home/YOUR_USERNAME/.virtualenvs/my_website_env
Configure WSGI file (click on WSGI config file link in Web tab):

import os
import sys

# Replace YOUR_USERNAME and my_website with your values
path = '/home/YOUR_USERNAME/my_website'
if path not in sys.path:
    sys.path.append(path)

# Replace 'my_website' with your Django project name
os.environ['DJANGO_SETTINGS_MODULE'] = 'my_website.settings'

from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

Reload web app - Click green "Reload" button

Your site should now be live at: YOUR_USERNAME.pythonanywhere.com

Step 5: Setup Custom Domain (Optional)

Note: Requires PythonAnywhere Hacker account ($5/month)

In PythonAnywhere Web tab:
- Add custom domain: www.yourdomain.com (replace with your domain)
- Note the CNAME value: webapp-XXXXXX.pythonanywhere.com
In your domain registrar (Namecheap, GoDaddy, Joker.com, etc):
- Add CNAME record: www → webapp-XXXXXX.pythonanywhere.com
- Optionally add A record for root domain (check PythonAnywhere docs)
Enable HTTPS:
- In PythonAnywhere Web tab → HTTPS section
- Click "Enable HTTPS" or "Renew certificate"

Wait 10-60 minutes for DNS propagation.

If you're not using a custom domain: Skip this step and use YOUR_USERNAME.pythonanywhere.com

Step 6: Setup Automated Deployment

This is where the magic happens - automatic deployment on every Git push!

6.1 Create GitHub Personal Access Token

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Generate new token (classic)
Select scope: ☑️ repo (all checkboxes under repo)
Copy the token (starts with ghp_...)

6.2 Configure Git Authentication on PythonAnywhere

cd ~/my_website
git remote set-url origin https://github.com/YOUR_USERNAME/my_website.git
git config credential.helper store
git pull origin main
# Username: YOUR_GITHUB_USERNAME
# Password: PASTE_YOUR_TOKEN_HERE

The token is now saved and git pull will work automatically.

6.3 Create GitHub Actions Workflow

Create .github/workflows/deploy.yml in your project:

name: Deploy to PythonAnywhere

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ssh.pythonanywhere.com
          username: ${{ secrets.PYTHONANYWHERE_USERNAME }}
          password: ${{ secrets.PYTHONANYWHERE_PASSWORD }}
          script: |
            cd ~/my_website
            git pull origin main
            touch /var/www/YOUR_USERNAME_pythonanywhere_com_wsgi.py

      - name: Reload web app via API
        run: |
          curl -X POST \
            https://www.pythonanywhere.com/api/v0/user/${{ secrets.PYTHONANYWHERE_USERNAME }}/webapps/YOUR_USERNAME.pythonanywhere.com/reload/ \
            -H "Authorization: Token ${{ secrets.PYTHONANYWHERE_API_TOKEN }}"

Important replacements in the workflow:

Line 17: cd ~/my_website → Use your project directory name
Line 19: YOUR_USERNAME_pythonanywhere_com_wsgi.py → Find exact filename in PythonAnywhere /var/www/ directory
Line 24: YOUR_USERNAME.pythonanywhere.com → Use your actual PythonAnywhere URL (or custom domain if configured)

6.4 Add GitHub Secrets

Go to: Repository → Settings → Secrets and variables → Actions

Create three secrets:

PYTHONANYWHERE_USERNAME
- Value: Your PythonAnywhere username
PYTHONANYWHERE_PASSWORD
- Value: Your PythonAnywhere password
PYTHONANYWHERE_API_TOKEN
- Get from: PythonAnywhere → Account → API token → Create new
- Value: The generated token

Step 7: Test Automated Deployment

# Make a small change in your code
# For example, edit index.html or a template file

# Commit and push
git add .
git commit -m "Test automated deployment"
git push origin main

What happens now:

GitHub receives your push
GitHub Actions workflow triggers
Connects to PythonAnywhere via SSH
Runs git pull to get latest code
Reloads web app via API
Your site is updated! (takes ~1-2 minutes)

Check: GitHub → Actions tab to see workflow running

✅ Final Workflow

Your development workflow is now:

1. Edit code in VS Code
2. Save changes  
3. git add . && git commit -m "message" && git push origin main
4. Wait 1-2 minutes
5. Site is live! 🎉

Check your live site at:

PythonAnywhere subdomain: YOUR_USERNAME.pythonanywhere.com
Custom domain (if configured): www.yourdomain.com

🐛 Common Issues & Solutions

Issue 1: "DisallowedHost" error

Solution: Add your domain to ALLOWED_HOSTS in settings.py:

ALLOWED_HOSTS = [
    'yourdomain.com',
    'www.yourdomain.com',
    'YOUR_USERNAME.pythonanywhere.com'
]

Issue 2: "Permission denied (publickey)" when git pull

Solution: Change Git remote to HTTPS and use Personal Access Token:

git remote set-url origin https://github.com/YOUR_USERNAME/your_project.git
git config credential.helper store
git pull  # Enter username and token

Issue 3: GitHub Actions workflow fails

Solution:

Check that all three Secrets are correctly set in GitHub
Verify PythonAnywhere API token is valid
Check workflow logs in GitHub Actions tab
Important: Verify WSGI file path and website URL in deploy.yml match your actual setup

Issue 4: Site doesn't update after push

Solution:

Check GitHub Actions - did workflow succeed?
SSH into PythonAnywhere and manually run git pull
Check error logs in PythonAnywhere Web tab
Verify the touch command uses correct WSGI file path

Issue 5: 502 Bad Gateway error

Solution:

Check WSGI configuration file has correct project name
Verify virtual environment is activated and has dependencies
Check error logs in PythonAnywhere

📊 Project Architecture

┌─────────────┐
│   VS Code   │  (Local Development)
└──────┬──────┘
       │ git push
       ↓
┌─────────────┐
│   GitHub    │  (Version Control)
└──────┬──────┘
       │ triggers
       ↓
┌─────────────────┐
│ GitHub Actions  │  (CI/CD Pipeline)
└──────┬──────────┘
       │ SSH + API
       ↓
┌──────────────────┐
│ PythonAnywhere   │  (Production Server)
└──────┬───────────┘
       │ serves
       ↓
┌──────────────────┐
│   Your Website   │  (Live Site)
└──────────────────┘

🎓 Key Learnings

Django configuration matters - import os and ALLOWED_HOSTS are critical
GitHub Actions is powerful - Automate everything!
Personal Access Tokens - Replace password authentication for Git
WSGI configuration - Connects Django to web server
Systematic debugging - Check each layer: local → Git → GitHub → server → live site

You now have a Django website with automated deployment. Every time you push code, your site updates automatically. No manual deployment needed!

Tutorial by Teemu Virta - teemu.tech