Secret Santa App

Organize your family's Secret Santa gift exchange with ease!

Secret Santa is a self-hosted web application that helps manage gift exchanges with features like wishlist management, assignment generation with constraints, email notifications, and assignment history tracking.

---

📦 Quick Start

Using Docker (Recommended)

docker run -d \
  -p 3000:3000 \
  -v secret-santa-data:/app/data \
  -e NEXTAUTH_SECRET=$(openssl rand -base64 32) \
  -e ADMIN_PASSWORD=changeme123 \
  ghcr.io/JR33D/secret-santa:latest

Visit http://localhost:3000 and login with:

• Username: admin
• Password: changeme123 (change immediately!)

See full installation guide →

---

✨ Features

• 🎁 Wishlist Management - Create and manage gift wishlists
• 👥 Pool Organization - Separate groups (family, friends, coworkers)
• 🎲 Smart Assignment - Automated matching with constraint support
• 🚫 Restrictions - Prevent couples/siblings from drawing each other
• 📧 Email Notifications - Automated assignment notifications
• 📊 History Tracking - Visual history of past assignments
• 🔐 User Management - Secure authentication with role-based access
• 🐳 Easy Deployment - Docker support with multi-architecture builds

---

📖 Documentation

Getting Started

• Installation Guide - Setup instructions
• User Guide - How to use the application
• Docker Deployment - Production deployment
• Troubleshooting - Common issues and solutions

For Contributors

• Contributing Guide - How to contribute
• Development Setup - Local development environment
• Release Process - How releases work
• API Documentation - API reference

Project Information

• Code of Conduct - Community standards
• Security Policy - Security and vulnerability reporting
• Changelog - Version history

---

🚀 Installation

Prerequisites

• Docker and Docker Compose (recommended)
• OR Node.js 18+ and npm

Option 1: Docker Compose (Production)

1. Download configuration files

   curl -O https://raw.githubusercontent.com/JR33D/secret-santa/main/docker-compose.prod.yml
   mv docker-compose.prod.yml docker-compose.yml
   curl -O https://raw.githubusercontent.com/JR33D/secret-santa/main/.env.example
   mv .env.example .env

2. Configure environment

   # Generate secure secret
   echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)" >> .env
   echo "ADMIN_PASSWORD=your_secure_password" >> .env

3. Start the application

   docker-compose up -d

Option 2: Development Setup

1. Clone the repository

   git clone https://github.com/JR33D/secret-santa.git
   cd secret-santa

2. Install dependencies

   npm ci

3. Configure environment

   cp .env.example .env
   # Edit .env with your configuration

4. Start development server

   npm run dev

---

🤝 Contributing

We love contributions! Whether it's bug fixes, new features, or documentation improvements, all contributions are welcome.

Quick Start for Contributors

1. Fork the repository
2. Clone your fork
3. Create a feature branch: git checkout -b feat/amazing-feature
4. Commit using conventional commits: git commit -m 'feat: add amazing feature'
5. Push to your branch: git push origin feat/amazing-feature
6. Open a Pull Request

See our Contributing Guide for detailed instructions.

Good First Issues: Check out issues tagged with "good first issue" to get started!

---

🐛 Bug Reports & Feature Requests

• 🐛 Report a bug
• ✨ Request a feature

---

🔒 Security

Found a security vulnerability? Please review our Security Policy and report it responsibly. We take security seriously and will respond promptly.

---

📊 Project Stats

---

🛠️ Tech Stack

• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS
• Backend: Next.js API Routes, Node.js
• Database: SQLite
• Authentication: NextAuth.js
• Email: Nodemailer
• Testing: Jest, React Testing Library
• Deployment: Docker, Docker Compose

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Built with Next.js - The React Framework
• UI styled with Tailwind CSS - Utility-first CSS
• Authentication via NextAuth.js - Authentication for Next.js
• Automated releases with Release Please - Automated releases

---

💖 Support the Project

If you find this project helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 📖 Improving documentation
• 🤝 Contributing code
• 📢 Sharing with others who might find it useful

---

Made with ❤️ for easier gift exchanges

Documentation · Report Bug · Request Feature