Foolstack

A production-ready full-stack web application template with Django, Vue 3, Redis, Celery, and automatic HTTPS.

Tech Stack

Layer	Technology
Backend	Django 5.1 + Django REST Framework
Frontend	Vue 3 + Vite + Tailwind CSS
Worker	Celery (background tasks)
Cache/Broker	Redis
Proxy	Caddy (automatic HTTPS)
Database	SQLite (configurable)
Containers	Docker + Docker Compose

Quick Start

# Clone and setup
git clone https://github.com/spaceCabbage/foolstack.git {you project name here}
cd myproject
make setup

# Start services
make up
make migrate
make superuser

Access your app:

• Frontend: https://localhost

• API: https://localhost/api

• Admin: https://localhost/admin

• Health: https://localhost/api/health/

Note: Development uses self-signed certificates. Accept the browser warning.

Architecture

Single domain with path-based routing:

https://localhost/
├── /           → Vue SPA (frontend)
├── /api/*      → Django REST API
├── /admin/*    → Django Admin
└── /static/*   → Static files

All traffic flows through Caddy reverse proxy which handles SSL termination.

Project Structure

foolstack/
├── server/                 # Django backend
│   ├── core/               # Project settings, URLs, health checks
│   ├── users/              # Custom user model + auth
│   ├── requirements.txt    # Python dependencies
│   └── Dockerfile
├── client/                 # Vue 3 frontend
│   ├── src/
│   │   ├── components/     # Vue components
│   │   ├── apiClient/      # Axios API client
│   │   └── App.vue
│   ├── package.json        # JS dependencies (Bun)
│   └── Dockerfile
├── data/                   # Persistent data (gitignored)
│   ├── logs/
│   ├── staticfiles/
│   ├── mediafiles/
│   └── db.sqlite3
├── docker-compose.yml      # Production config
├── docker-compose.dev.yml  # Development overrides
├── Caddyfile               # Reverse proxy config
├── Makefile                # Developer commands
├── .env.example            # Environment template
└── CLAUDE.md               # AI assistant instructions

Available Commands

# Setup & Lifecycle
make setup          # First-time setup (creates .env, builds, installs deps)
make up             # Start all services
make down           # Stop all services
make restart        # Restart all services
make status         # Show system health
make urls           # Show access URLs

# Development
make logs           # Follow all logs
make logs s         # Follow server logs only (s=server, c=client, w=worker)
make shell          # Django shell
make deps           # Sync local venv + bun for IDE

# Database
make migrations     # Create Django migrations
make migrate        # Apply migrations
make superuser      # Create admin user

# Building
make build          # Build Docker images
make build-clean    # Build without cache

# Testing
make test           # Run all tests
make test-coverage  # Run tests with coverage

# Project Management
make init <name>    # Rename project from template
make purge          # DANGER: Wipe everything and start fresh

Configuration

All configuration via .env:

# Required
PROJECT_NAME=foolstack
DOMAIN=localhost
ENVIRONMENT=development
SECRET_KEY=<auto-generated>

# Optional (with defaults)
LOG_LEVEL=INFO
DATABASE_NAME=db.sqlite3
CADDY_EMAIL=admin@example.com

# Ports (all have defaults)
# CADDY_HTTP_PORT=80
# CADDY_HTTPS_PORT=443
# SERVER_PORT=8000
# CLIENT_PORT=5173
# REDIS_PORT=6379

Features

Backend

• Custom User model (email-based auth)
• JWT authentication (SimpleJWT)
• Health check endpoints (/api/ping/, /api/health/)
• Celery worker for background tasks
• Redis caching
• Structured logging with Loguru

Frontend

• Vue 3 with Composition API
• Vite for fast HMR
• Tailwind CSS
• Axios API client configured for /api
• Vue Router ready

DevOps

• Docker multi-stage builds
• Hot reload in development
• Automatic HTTPS (self-signed dev, Let's Encrypt prod)
• Non-root containers (security)
• Configurable ports

Production Deployment

# Update .env
ENVIRONMENT=production
DOMAIN=yourdomain.com
CADDY_EMAIL=admin@yourdomain.com

# Deploy
make up

Caddy automatically provisions SSL certificates from Let's Encrypt.

Documentation

• API Reference - REST endpoints
• Authentication - JWT auth system
• Template Usage - Customizing the template
• AI Instructions - For AI pair programming

Using as a Template

# Option 1: GitHub template
# Click "Use this template" on GitHub

# Option 2: Clone and rename
git clone https://github.com/spaceCabbage/foolstack.git {your-project-name}
cd {your-project-name}
make init {your-project-name}   # Renames all references
make setup

License

MIT