Crystal Community

A community platform for Crystal developers to connect and discover each other. Built with the Crystal programming language and inspired by rubycommunity.org.

✨ Features

• 🔐 GitHub OAuth Authentication - Sign in with your GitHub account
• 🗺️ Interactive Community Map - Visualize developers around the world
• 👥 Developer Directory - Browse and discover Crystal developers
• 📝 GitHub Profile Integration - Automatically sync name, bio, location, and avatar from GitHub
• 🎨 Modern UI - Clean and responsive design

🚧 Planned Features

• 👤 Developer Profiles - Detailed profile pages for each developer
• 📊 Activity Tracking - Track projects, posts, comments, and stars
• 🏆 Scoring System - Gamified community engagement
• 💼 Open to Work - Mark your availability for opportunities

🛠️ Tech Stack

• Crystal - Fast, statically typed language
• Kemal - Fast, effective web framework
• PostgreSQL - Robust relational database
• Micrate - Database migrations
• Kemal Session - Session management

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Crystal (>= 1.19.1)
• PostgreSQL (>= 12.0)
• Git

🚀 Installation

1. Clone the repository

   git clone https://github.com/your-username/crystal-community.git
   cd crystal-community
   

2. Install dependencies

   shards install
   

3. Set up the database

   # Create PostgreSQL database
   createdb crystal_community_development
   
   # Run migrations
   crystal run src/micrate.cr up
   

4. Configure environment variables

   Create a .env.development file in the project root:

   DATABASE_URL="postgres://localhost/crystal_community_development"
   GITHUB_CLIENT_ID="your_github_client_id"
   GITHUB_CLIENT_SECRET="your_github_client_secret"
   SESSION_SECRET="your-secret-key-change-this-in-production"
   CRYSTAL_COMMUNITY_ENV="development"
   

   Getting GitHub OAuth Credentials:

   • Go to GitHub Settings > Developer settings > OAuth Apps
   • Click "New OAuth App"
   • Set Application name: Crystal Community (Development)
   • Set Homepage URL: http://localhost:3000
   • Set Authorization callback URL: http://localhost:3000/users/auth/github/callback
   • Copy the Client ID and generate a Client Secret

5. Build the application

   crystal build src/app.cr -o crystal-community
   

🎮 Usage

Running the Application

Option 1: Direct execution

crystal run src/app.cr

Option 2: Using the compiled binary

./crystal-community

The application will be available at http://localhost:3000

Development with Auto-Reload

This project uses sentry.cr for automatic rebuild/restart during development.

Installation:

curl -fsSLo- https://raw.githubusercontent.com/samueleaton/sentry/master/install.cr | crystal eval

Run with auto-reload:

./sentry --install
./sentry

The .sentry.yml file is configured to build src/app.cr and run the ./crystal-community binary, watching src/**/*.cr and src/**/*.ecr files.

Fake User Generator (Development)

Create fake users in the development environment to test the map and developer directory:

CRYSTAL_COMMUNITY_ENV=development crystal run src/seeders/fake_user_generator.cr

This command creates 100 fake users by default. Users are inserted with random names, bios, locations, avatar URLs, and other profile data.

Note: Ensure database migrations have been run and .env.development is configured before running this command.

📁 Project Structure

crystal-community/
├── db/
│   └── migrations/          # Database migrations
├── public/
│   └── assets/              # Static assets (CSS, JS, images)
├── spec/                    # Test files
├── src/
│   ├── app.cr               # Application entry point
│   ├── config/              # Configuration files
│   ├── controllers/         # Request handlers
│   ├── models/              # Data models
│   ├── routes/              # Route definitions
│   ├── seeders/             # Database seeders
│   └── views/               # ECR templates
├── .env.development         # Development environment variables
├── shard.yml                # Crystal dependencies
└── README.md

🧪 Testing

Running Tests

Before running tests, make sure you have a test database set up:

# Create test database
createdb crystal_community_test

# Run migrations on test database
CRYSTAL_COMMUNITY_ENV=test crystal run src/micrate.cr -- up

Create a .env.test file in the project root with the following configuration:

DATABASE_URL="postgres://localhost/crystal_community_test"
GITHUB_CLIENT_ID="dummy_github_client_id"
GITHUB_CLIENT_SECRET="dummy_github_client_secret"
SESSION_SECRET="test-secret-key"
CRYSTAL_COMMUNITY_PORT=3001
GA_TRACKING_ID=""

Run the test suite:

KEMAL_ENV=test CRYSTAL_COMMUNITY_ENV=test crystal spec

The tests use spec-kemal for E2E testing of Kemal routes and controllers.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Development Guidelines

• Follow Crystal's style guide
• Write tests for new features
• Update documentation as needed
• Ensure migrations are reversible when possible

📝 Database Migrations

Create a new migration:

crystal run src/micrate.cr create migration_name

Run migrations:

crystal run src/micrate.cr up

Rollback migrations:

crystal run src/micrate.cr down

🔒 Security

• Always use strong SESSION_SECRET values in production
• Never commit .env files with real credentials
• Keep dependencies up to date
• Review OAuth scopes and permissions

📄 License

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