🚀 Foolstack - Full Stack Django + Vue3 Template

A production-ready, batteries-included full stack web application template featuring Django REST API, Vue 3 SPA, Docker containerization, and automatic SSL with Caddy.

🎯 Why Foolstack?

Foolstack eliminates the tedious setup of a modern full-stack application by providing:

• Zero-config development environment - One command to start developing
• Production-ready from day one - SSL, CORS, security headers all configured
• Modern tech stack - Django 5.1, Vue 3, Vite, Docker, Caddy
• Developer experience focused - Hot reload, VSCode integration, comprehensive Makefile
• Best practices built-in - JWT auth, environment-based config, proper project structure

🏗️ Tech Stack

Component	Technology	Purpose
Backend	Django 5.1 + DRF	REST API with JWT authentication
Frontend	Vue 3 + Vite	Modern SPA with hot module replacement
Database	SQLite (dev) / PostgreSQL (prod)	Simple development, scalable production
Web Server	Caddy	Automatic HTTPS, reverse proxy
Container	Docker + Docker Compose	Consistent environments
Package Management	Poetry (Python) + Bun (JS)	Modern dependency management

🚀 Quick Start

Using as a Template

1. Use this template on GitHub:

   • Click "Use this template" button
   • Create a new repository
   • Clone your new repo

2. Or use GitHub CLI:

   gh repo create myapp --template yourusername/foolstack --clone
   cd myapp

3. Start developing:

   make setup  # Automated setup - creates .env, builds, migrates
   make superuser  # Create admin user

4. Access your app:

   • Frontend: http://localhost
   • API: http://api.localhost
   • Admin: http://api.localhost/admin

📚 Documentation

• Template Usage Guide - How to customize this template for your project
• Developer Guide - Comprehensive development documentation
• AI Assistant Guide - Instructions for AI pair programming

🛠️ Available Commands

# Development
make setup           # One-command initial setup
make up              # Start all services
make down            # Stop all services
make logs            # View logs from all services
make status          # Show container status

# Django
make app <name>      # Create a new Django app
make migrations      # Create database migrations
make migrate         # Apply database migrations
make superuser       # Create admin user
make test            # Run tests
make shell-django    # Django container shell
make shell-vue       # Vue container shell

# Building
make build           # Smart rebuild with caching
make build-clean     # Full rebuild (no cache)

# IDE Setup
make vscode-setup    # Configure VSCode Python environment
make poetry-install  # Install Python deps locally
make bun-install     # Generate Bun lockfile

# Maintenance
make restart         # Restart all services
make clean           # Remove containers and volumes

🏗️ Project Structure

.
├── server/                # Django backend
│   ├── core/              # Project settings
│   ├── authentication/    # JWT auth app (included)
│   ├── pyproject.toml     # Python dependencies
│   └── manage.py
├── client/                # Vue 3 frontend
│   ├── src/
│   │   ├── components/    # Reusable components
│   │   ├── pages/         # Page components
│   │   ├── stores/        # Pinia stores
│   │   └── apiClient/     # API client
│   └── package.json       # JS dependencies
├── caddy/                 # Web server config
├── docker-compose.yml     # Container orchestration
├── Makefile               # Developer commands
└── .env.example           # Environment template

🔧 Configuration

Environment Variables

The entire stack is configured via .env:

ENVIRONMENT=development|production
BASE_DOMAIN=localhost
DJANGO_SECRET_KEY=<auto-generated>
DJANGO_PORT=8000
VUE_PORT=5173
DATABASE_NAME=db.sqlite3
CADDY_EMAIL=admin@example.com
LOG_LEVEL=INFO

Domain Configuration

• Frontend: {BASE_DOMAIN}
• API: api.{BASE_DOMAIN}
• Automatic SSL in production via Caddy

🚢 Production Deployment

1. Update .env:

   ENVIRONMENT=production
   BASE_DOMAIN=yourdomain.com

2. Build and deploy:

   make prod-build
   make prod-up

3. Caddy automatically provisions SSL certificates

🎨 Included Features

Backend

• ✅ Custom User model with email authentication
• ✅ JWT authentication system
• ✅ CORS configuration (environment-aware)
• ✅ Health check endpoint
• ✅ Structured project layout
• ✅ Poetry dependency management

Frontend

• ✅ Vue 3 with Composition API
• ✅ Vue Router configured
• ✅ Pinia state management
• ✅ Vite for fast development
• ✅ API client setup (connects to backend)
• ✅ Authentication store
• ✅ Responsive starter layout

DevOps

• ✅ Docker multi-stage builds
• ✅ Development with hot reload
• ✅ Production optimizations
• ✅ Automatic HTTPS with Caddy
• ✅ Environment-based configuration
• ✅ VSCode integration

🤝 Contributing

This is a template repository designed to be forked and customized. If you have improvements to the template itself:

1. Fork the repository
2. Create a feature branch
3. Make your improvements
4. Submit a pull request

---

Ready to build something awesome? Get started now!