Open Source Santa

A fun holiday project that uses AI to generate personalized roast letters from Salty Open Source Santa based on your GitHub open source contributions. Find out if you're on the naughty or nice list! 🎅

Built with ❤️ by the Directus team

Introduction · Features · Tech Stack · Setup Guide ·

Introduction

Open Source Santa is a playful web application that analyzes GitHub profiles and generates AI-powered "naughty or nice" letters from Santa. Whether you want to check your own open source karma or roast a friend, Santa's got opinions about everyone's commits!

Learn how the project was built on the Directus Developer Blog.

Features

• 🎅 Generate AI-powered roast letters from Santa based on GitHub public profile data
• 🎄 Check if you're on the naughty or nice list
• 🎁 Write letters for yourself or roast your friends
• 🌟 Beautiful particle snow effects and holiday theming
• 🔊 Fun sound effects
• 🔒 GitHub OAuth authentication
• 🖼️ Dynamic OG image generation

Tech Stack

Frontend

• Nuxt 3 - Vue.js Framework
• Nuxt UI v3-alpha - UI Component Library
• Tailwind CSS v4-beta - Utility-first CSS
• VueUse - Vue Composition Utilities
• tsParticles - Particle Effects
• Vercel AI SDK - AI SDK

Backend

• Directus - Backend + CMS (Admin)
• Anthropic Claude - AI Text Generation
• PostgreSQL - Database

Setup Guide

0. Prerequisites

• Node.js - v18.17.0 or higher
• pnpm - v9.0.0 or higher
• Docker - v25.0.0 or higher

Clone the repository and navigate to the root directory.

git clone https://github.com/directus-labs/os-santa.git
cd os-santa

1. Backend Setup (Directus)

We recommend you checkout the Directus documentation for more information on how to setup and run Directus.

Option A: Directus Cloud (Recommended for Quick Start)

1. Create an account at Directus Cloud

2. Create a new trial project - choose the build from scratch option

3. Once created, note your project URL and login credentials.

4. Run the directus-template-cli tool to apply the template to your project. Replace the values with your specific project URL and login credentials.

   cd directus

   npx directus-template-cli@latest apply --directusUrl="your_directus_url" --userEmail="your_email" --userPassword="your_password" --templateLocation="./template" --templateType="local"

5. Login to Directus and generate a static access token for the "Santa's Helper" user. Save the token for the environment variables.

   DIRECTUS_SERVER_TOKEN=your_directus_token

Option B: Self-Hosted Setup

1. Ensure you have docker installed and running on your machine. Install Docker

2. Start the Directus instance using Docker:

   cd directus

   docker-compose up -d

3. Run the directus-template-cli tool to apply the template to your project. Replace the values with your specific project details.

   npx directus-template-cli@latest apply --directusUrl="http://localhost:8055" --userEmail="[email protected]" --userPassword="d1r3ctus" --templateLocation="./template" --templateType="local"

4. Login to Directus and generate a static access token for the "Santa's Helper" user. Save the token for the environment variables.

   DIRECTUS_SERVER_TOKEN=your_directus_token

2. GitHub OAuth Setup

1. Go to GitHub Developer Settings

2. Click "New OAuth App"

3. Fill in the application details:

   • Application name: "Open Source Santa" (or your preferred name)
   • Homepage URL: http://localhost:3000 (development) or your production URL
   • Authorization callback URL: http://localhost:3000/auth/github

4. Save the Client ID and Client Secret for environment variables

   GITHUB_CLIENT_ID=your_github_client_id
   GITHUB_CLIENT_SECRET=your_github_client_secret

Generating a GitHub Token for GraphQL API

1. Go to GitHub Personal Access Tokens

2. Click "Generate new token"

3. Fill in the token details:

   • Note: "Open Source Santa GraphQL Access" (or your preferred note)
   • Expiration: Choose an appropriate expiration time
   • Repository access: Public Repositories (read-only)

4. Add the token to your environment variables:

   GITHUB_TOKEN=your_github_token

3. Anthropic API Setup

1. Create an account at Anthropic

2. Generate an API key from your dashboard

3. Save the API key for environment variables

   ANTHROPIC_API_KEY=your_anthropic_api_key

4. Frontend (Nuxt) Setup

1. Install dependencies:

   cd nuxt

   pnpm i

2. Copy the example environment file:

   cp .env.example .env

3. Fill in your environment variables:

   # Directus Configuration
   DIRECTUS_URL=your_directus_url
   DIRECTUS_SERVER_TOKEN=your_directus_token
   
   # AI Generation
   ANTHROPIC_API_KEY=your_anthropic_api_key
   
   # Site Configuration
   NUXT_PUBLIC_SITE_URL=http://localhost:3000
   NUXT_SESSION_PASSWORD="password-with-at-least-32-characters"
   SALT="some-random-salt-string"
   
   # Authentication
   GITHUB_TOKEN=your_github_token_for_graphql_api
   GITHUB_CLIENT_ID=your_github_client_id
   GITHUB_CLIENT_SECRET=your_github_client_secret
   
   # Analytics (Optional)
   POSTHOG_API_KEY=your_posthog_api_key
   POSTHOG_API_HOST=your_posthog_host

   Note: PostHog analytics is optional and will be disabled in development mode. If you don't need product analytics, you can skip these environment variables.

4. Generate Directus types:

   NOTE: Your Directus instance must be running for type generation to work.

   pnpm generate:types

5. Start the development server:

   pnpm dev

6. Visit http://localhost:3000 in your browser

Common Issues and Troubleshooting

CORS Issues

If you're running into CORS issues with Directus, ensure your Directus instance has CORS properly configured. For development, you can add the following to your Directus environment:

Learn more about CORS in Directus.

CORS_ENABLED=true
CORS_ORIGIN=http://localhost:3000

Authentication Issues

• Ensure your GitHub OAuth callback URL exactly matches your application setup
• Verify your Directus token has admin access
• Check that all environment variables are properly set

🛟 Community Help

For community help or support with Directus itself, please see the Directus Discord server.

• Directus Discord – Join over 10k+ developers and community members to ask questions and live discussion around Directus.

❤️ Contributing

Here's how you can contribute:

• Open an issue if you believe you've encountered a bug.
• Please open an issue before submitting any PRs for new features or improvements.

🙏 Thanks To

• Our other awesome core team members at Directus who helped test and provide feedback.
• joshwcomeau for the idea and logic behind the spice-meter / like button.
• codenoid/github-roast for additional inspiration of the GitHub roast idea.

License

This project is open source and available under the MIT License. See the LICENSE file for more details.