🎯 Elixir Starter Kit

A production-ready Elixir starter template with Phoenix Framework, ready for deployment. Perfect for building scalable web applications and APIs.

🚀 Quick Start

Prerequisites

• Elixir 1.15+ (Install via asdf or official installer)
• PostgreSQL 14+
• Node.js 18+ (for assets)
• Git

Setup in 5 minutes

# 1. Clone the repository
git clone https://github.com/Solomonkassa/elixir-starter-kit.git
cd elixir-starter-kit

# 2. Setup environment
cp .env.example .env
# Edit .env with your database credentials

# 3. Setup dependencies
mix setup

# 4. Start the application
mix phx.server

Visit http://localhost:4000 to see your application running.

✨ Features

🏗️ Architecture

• Phoenix 1.7 with LiveView
• Clean Domain-Driven Design (DDD) structure
• Context-based business logic organization
• API-first design with REST & GraphQL support

🔐 Security

• Built-in authentication (User, Admin)
• OAuth2 support (Google, GitHub)
• Role-based authorization (RBAC)
• SSL/TLS ready
• CSRF, XSS, CORS protection

📦 Development Tools

• Live reload with Phoenix
• Interactive IEx shell with helpers
• Code formatting (mix format)
• Static analysis (Credo, Dialyzer)
• Git hooks for quality checks

🗄️ Database

• PostgreSQL with Ecto
• Database seeding
• Migrations with rollback support
• Query optimization (Ecto.Query)
• Soft deletes with deleted_at

🧪 Testing

• Unit tests (ExUnit)
• Integration tests
• Property-based testing (StreamData)
• Test coverage (ExCoveralls)
• CI/CD ready

📁 Project Structure

elixir-starter-kit/
├── lib/
│   ├── starter/                  # Application core
│   │   ├── accounts/             # User/Account management
│   │   ├── blog/                 # Blog module example
│   │   ├── core/                 # Shared utilities
│   │   └── web/                  # Web interface (controllers, views)
│   │       ├── controllers/      # REST controllers
│   │       ├── live/             # LiveView components
│   │       └── views/            # View modules
│   └── starter_web.ex           # Web endpoint
├── test/                         # Test suite
├── assets/                       # Frontend assets (JS, CSS)
├── priv/repo/                    # Database migrations
└── config/                       # Configuration

🛠️ Development Commands

# Start development server
mix phx.server

# Run tests
mix test
mix test.watch  # Watch mode

# Code quality
mix format      # Format code
mix credo       # Static analysis
mix dialyzer    # Type checking

# Database
mix ecto.setup  # Create, migrate, seed
mix ecto.migrate
mix ecto.rollback
mix ecto.reset  # Reset database

# Dependencies
mix deps.get    # Get dependencies
mix deps.update # Update dependencies

# Production
mix release     # Create release
MIX_ENV=prod mix phx.server  # Production mode

🌐 API Endpoints

REST API (JSON)

GET    /api/v1/posts          # List posts
POST   /api/v1/posts          # Create post
GET    /api/v1/posts/:id      # Get post
PUT    /api/v1/posts/:id      # Update post
DELETE /api/v1/posts/:id      # Delete post

Authentication

POST   /api/v1/auth/register  # Register user
POST   /api/v1/auth/login     # Login
POST   /api/v1/auth/logout    # Logout
GET    /api/v1/auth/me        # Current user

GraphQL (Optional)

POST   /api/graphql           # GraphQL endpoint
GET    /api/graphiql          # GraphQL playground

📊 Database Schema

-- Users table
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255),
  role VARCHAR(50) DEFAULT 'user',
  inserted_at TIMESTAMP,
  updated_at TIMESTAMP
);

-- Posts table (example)
CREATE TABLE posts (
  id UUID PRIMARY KEY,
  title VARCHAR(500) NOT NULL,
  content TEXT,
  user_id UUID REFERENCES users(id),
  published_at TIMESTAMP,
  inserted_at TIMESTAMP,
  updated_at TIMESTAMP
);

🚢 Deployment

Option 1: Docker (Recommended)

# Build and run with Docker Compose
docker-compose up --build

# Or with Docker
docker build -t elixir-starter .
docker run -p 4000:4000 elixir-starter

Option 2: Fly.io (Free Tier)

# Install Fly CLI
fly auth login

# Deploy
fly launch
fly deploy

Option 3: Heroku

# Create Heroku app
heroku create your-app-name

# Add buildpacks
heroku buildpacks:add https://github.com/HashNuke/heroku-buildpack-elixir
heroku buildpacks:add https://github.com/gjaldon/heroku-buildpack-phoenix-static

# Deploy
git push heroku main

Option 4: Gigalixir

# Install Gigalixir CLI
pip install gigalixir --user

# Create app
gigalixir create

# Set config
gigalixir config:set POOL_SIZE=2

# Deploy
git push gigalixir main

📈 Monitoring & Observability

Built-in Metrics

• Prometheus metrics endpoint (/metrics)
• Health checks (/health)
• Request logging
• Error tracking

Optional Integrations

• Sentry for error reporting
• AppSignal for performance monitoring
• Logflare for log management
• Datadog for APM

🔧 Configuration

Environment Variables

# Required
DATABASE_URL=postgresql://user:pass@localhost:5432/db_name
SECRET_KEY_BASE=your-secret-key-base

# Optional
PORT=4000
HOSTNAME=localhost
POOL_SIZE=10
SENTRY_DSN=your-sentry-dsn

Production Configuration

Edit config/runtime.exs for production settings:

config :starter, StarterWeb.Endpoint,
  url: [host: System.get_env("HOSTNAME"), port: 443],
  http: [port: {:system, "PORT"}],
  secret_key_base: System.get_env("SECRET_KEY_BASE")

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow the Elixir Style Guide
• Write tests for new features
• Update documentation
• Use conventional commits

📚 Learning Resources

• Phoenix Framework Guide
• Elixir School
• Elixir Forum
• Awesome Elixir

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Phoenix Framework team
• Elixir community
• All contributors and users

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@example.com

---

Happy coding with Elixir! 🎉

🎯 Quick Commands Cheat Sheet

# Setup
mix setup

# Development
mix phx.server
mix test

# Code Quality
mix format
mix credo

# Database
mix ecto.migrate
mix ecto.reset

# Production
mix release
mix phx.server --env prod