<PROJECT_NAME>

A modern Ruby on Rails application with comprehensive authentication, user management, and social features

---

📖 About

This is a feature-rich Ruby on Rails application built with modern web technologies. It provides a complete foundation for user-centric applications with multiple authentication methods, profile management, and administrative capabilities.

Key Features

• ✅ Multi-factor Authentication: Password, OAuth 2.0, Passkeys (WebAuthn), TOTP
• ✅ User Profiles: Rich text bios, avatars, social media links
• ✅ Admin Dashboard: User management, activity tracking, global settings
• ✅ Analytics: Visit tracking with geo-location
• ✅ Modern UI: DaisyUI + Tailwind CSS with dark/light mode
• ✅ Component-based Architecture: Phlex view components
• ✅ Real-time Features: Hotwire (Turbo + Stimulus)
• ✅ Deployment Ready: Docker + Kamal support

---

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Dependency	Version	Installation Guide
Ruby	4.0.1+	ruby-lang.org
Bun	1.0.0+	bun.sh
SQLite	3.8.0+	sqlite.org
Node.js	18+ (optional)	nodejs.org
Docker	20.10+ (optional)	docker.com

Note: This project uses Bun for JavaScript/CSS bundling instead of Node.js/npm/yarn.

Installation

1. Clone the repository

git clone <repository-url>
cd <project-directory>

2. Install Ruby dependencies

bundle install

3. Install JavaScript/CSS dependencies

bun install

4. Set up the database

bin/rails db:prepare

This command runs:

• db:create - Creates the database
• db:schema:load - Loads the schema
• db:seed - (Optional) Loads seed data

5. Configure environment variables

Copy the example configuration and adjust as needed:

cp config/settings.yml config/settings.local.yml

Edit config/settings.local.yml with your configuration (see Configuration section).

6. Generate master key

If you don't have a config/master.key file:

EDITOR="nano" bin/rails credentials:edit

7. Build assets

bin/rails assets:precompile

Or for development with auto-reload:

bun run build --watch
bun run build:css --watch

8. Start the development server

bin/dev

This starts:

• Rails server on http://localhost:3000
• Solid Queue worker
• CSS watcher
• JavaScript watcher

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

---

📦 Development with Docker

Using Docker Compose (Development)

The project includes a docker-compose.yml file for development with Mailpit (SMTP server).

# Start Mailpit for email testing
docker-compose up -d

Mailpit will be available at:

• Web UI: http://localhost:8025
• SMTP: localhost:1025

Using Docker for Production

Build and run the production image:

# Build the image
docker build -t <project-name> .

# Run the container
docker run -d \
  -p 80:80 \
  -e RAILS_MASTER_KEY=$(cat config/master.key) \
  --name <project-name> \
  <project-name>

---

🔧 Configuration

Application Settings

The application uses the config gem for settings management.

Main Configuration File: config/settings.yml

app:
  name: <PROJECT_NAME>           # Application name (displayed in UI)
  logo_version: 1               # Logo variant to use
  url: http://localhost:3000    # Base URL for the application

social:
  # Optional: Add your project's social media links
  # These will appear in the footer
  # Example:
  # forgejo:
  #   name: Forgejo
  #   icon: fa-forgejo
  #   url: https://git.example.com/your/project

auth:
  passkey: true                 # Enable WebAuthn/Passkey authentication
  registration_enabled: true  # Allow new user registrations
  
  proxy:
    enabled: true              # Enable proxy authentication
    auto_create_users: true    # Automatically create users from proxy headers
    header_username: X-Authentik-Username  # Header containing username
    header_email: X-Authentik-Email        # Header containing email
    header_groups: X-Authentik-Groups      # Header containing user groups
    groups_separator: "|"      # Separator for multiple groups
  
  # OAuth Providers
  # Add provider configurations as needed
  # providers:
  #   github:
  #     client_id: YOUR_CLIENT_ID
  #     client_secret: YOUR_CLIENT_SECRET
  #     name: GitHub
  #     icon: fa-github
  #     btn_color: "#24292e"
  #     text_color: "#ffffff"
  #   google:
  #     client_id: YOUR_CLIENT_ID
  #     client_secret: YOUR_CLIENT_SECRET
  #     name: Google
  #     icon: fa-google
  #     btn_color: "#4285F4"
  #     text_color: "#ffffff"

Environment-Specific Configuration

• Development: config/settings/development.yml
• Production: Set via environment variables with SETTINGS_ prefix

SMTP Configuration (Development)

# config/settings/development.yml
smtp:
  address: localhost
  port: 1025
  username: none
  password: none
  authentication: false

For production, use environment variables:

SETTINGS_SMTP_ADDRESS=smtp.example.com
SETTINGS_SMTP_PORT=587
SETTINGS_SMTP_USERNAME=user@example.com
SETTINGS_SMTP_PASSWORD=password
SETTINGS_SMTP_AUTHENTICATION=true

Environment Variables

Variable	Description	Required
RAILS_MASTER_KEY	Master key for encrypted credentials	✅
DATABASE_URL	Database connection URL	❌ (uses SQLite by default)
SETTINGS_APP_NAME	Application name	❌ (default: "Application")
SETTINGS_APP_URL	Application URL	❌ (default: "http://localhost:3000")
SETTINGS_SMTP_*	SMTP settings	❌ (for email functionality)

---

🏗️ Architecture

Directory Structure

.
├── app/
│   ├── assets/              # Stylesheets, JavaScript, images
│   │   ├── builds/          # Compiled assets
│   │   ├── stylesheets/     # PCSS files (Tailwind)
│   │   └── javascript/      # JavaScript files
│   ├── components/          # Phlex view components
│   │   ├── concerns/        # Shared component logic
│   │   ├── form/            # Form components
│   │   ├── layout/          # Layout components (navbar, footer)
│   │   └── users/           # User-specific components
│   ├── controllers/         # Rails controllers
│   │   ├── concerns/        # Controller concerns
│   │   └── admin/           # Admin controllers
│   ├── helpers/             # View helpers
│   ├── jobs/                # Active Job classes
│   ├── mailers/             # Mailers
│   ├── models/              # Models
│   │   ├── concerns/        # Model concerns
│   │   └── user/            # User-related models
│   ├── policies/            # Pundit policies
│   └── views/               # Phlex views
│       └── layouts/         # Layout views
├── config/
│   ├── environments/        # Environment configurations
│   ├── initializers/        # Rails initializers
│   ├── locales/             # I18n translations
│   ├── routes.rb            # Routes definition
│   └── settings.yml         # Application settings
├── db/
│   ├── migrate/             # Database migrations
│   └── seeds.rb              # Seed data
├── docker-compose.yml       # Docker Compose for development
├── Dockerfile               # Production Docker image
├── .kamal/                  # Kamal deployment configuration
└── Gemfile                  # Ruby dependencies

Technology Stack

Layer	Technology	Purpose
Backend	Ruby on Rails 8.1.2	Web framework
Frontend	Phlex + Hotwire	View rendering
Styling	DaisyUI + Tailwind CSS	UI framework
Database	SQLite 3	Data storage
Assets	Propshaft + esbuild	Asset pipeline
JavaScript	Bun	Package manager & runtime
Jobs	Solid Queue	Background jobs
Cache	Solid Cache	Caching
Realtime	Solid Cable	Action Cable
Auth	Custom + OmniAuth + WebAuthn	Authentication
Analytics	Ahoy Matey	Visit tracking
Rich Text	Action Text + Lexxy	WYSIWYG editing

---

✨ Features

🔐 Authentication & Security

Authentication Methods

Method	Description	Status
Email/Password	Traditional login with secure password hashing	✅
OAuth 2.0	Login via third-party providers (GitHub, Google, etc.)	✅
Passkeys	Passwordless authentication via WebAuthn	✅
TOTP (2FA)	Time-based one-time passwords	✅
Proxy Auth	Header-based authentication for SSO	✅

Security Features

• ✅ Password Complexity: Minimum 10 characters with complexity requirements
• ✅ Account Locking: Manual locking via admin interface
• ✅ Email Verification: Required for new registrations
• ✅ Password Reset: Secure token-based reset flow
• ✅ Session Management: Multiple sessions with geo-tracking
• ✅ CSRF Protection: Built-in Rails protection
• ✅ Secure Cookies: HttpOnly, SameSite, Signed

👤 User Management

User Model

# Key attributes
- email (unique, validated)
- username (unique, 3-30 chars)
- password_digest (bcrypt)
- role (:user, :admin)
- visibility (:public, :private)
- verified_at
- locked_at
- totp_secret (for 2FA)
- unconfirmed_email (for email changes)

# Associations
- has_one :profile
- has_many :sessions
- has_many :identities (OAuth accounts)
- has_many :passkeys
- has_one_attached :avatar
- has_many :visits (Ahoy)
- has_many :events (Ahoy)

Profile Features

• Name: Display name (optional)
• Bio: Rich text with Action Text
• URL: Personal website link
• Country: ISO 3166 country selection
• Avatar: Upload, Gravatar, or from OAuth provider
• Social Accounts: Instagram, TikTok, Reddit, Bluesky, Mastodon, Matrix

⚙️ Administration

Admin Features

Feature	Description
User Management	View, edit, lock/unlock users
Activity Log	View user activities and system events
Global Settings	Configure app name, logo, legal pages
Social Links	Manage social media links in footer
Jobs Dashboard	Monitor background jobs (Mission Control)

Admin Routes

/admin                    # Admin dashboard
/admin/users              # User management
/admin/users/:id          # User details
/admin/users/:id/edit     # Edit user
/admin/activities         # Activity log

📊 Analytics & Tracking

• Ahoy Matey: Comprehensive visit and event tracking
• Geo-IP: Automatic location detection for sessions
• User Agent: Browser and device information
• Custom Events: Track user actions throughout the app

🎨 User Interface

UI Features

• ✅ Responsive Design: Mobile-first approach
• ✅ Dark/Light Mode: Theme switching with localStorage persistence
• ✅ Accessibility: ARIA labels and keyboard navigation
• ✅ Internationalization: German (default) and English support
• ✅ Modern Components: Reusable Phlex components
• ✅ Icons: Font Awesome (Brands & Solid)

Layout Components

• Navbar: Logo, theme toggle, user menu
• Footer: Social links, legal pages, copyright
• Sidebar: Navigation for logged-in users
• Flash Messages: Styled notifications

📧 Email Notifications

• ✅ Welcome Email: Sent after registration
• ✅ Email Verification: Verification link
• ✅ Password Reset: Reset link
• ✅ Account Deletion: Notification
• ✅ MJML Templates: Responsive email design

---

🔌 APIs & Integrations

OAuth 2.0 Providers

Supported providers (configure in settings.yml):

Provider	Gem	Strategy
Apple	omniauth-apple	omniauth-apple
Discord	omniauth-discord	omniauth-discord
Facebook	omniauth-facebook	omniauth-facebook
GitHub	omniauth-github	omniauth-github
Google	omniauth-google-oauth2	omniauth-google-oauth2
Microsoft	omniauth-microsoft_graph	omniauth-microsoft_graph
OIDC	omniauth_oidc	oidc

WebAuthn / Passkeys

• ✅ Platform Authenticators: Support for biometric authentication (Face ID, Touch ID, Windows Hello)
• ✅ Cross-Device: Support for external authenticators (YubiKey, etc.)
• ✅ Backup & Sync: Browser-based passkey management

Geo-IP Lookup

• Geocoder: IP-based location detection
• MaxMindDB: Support for MaxMind GeoIP databases

---

🚢 Deployment

Deployment Options

Option 1: Kamal (Recommended)

Kamal is the recommended deployment tool.

1. Configure .kamal/config/deploy.yml
2. Set up your server
3. Deploy:

# Set up the server
kamal setup

# Deploy the application
kamal deploy

Option 2: Docker Manually

# Build the image
docker build -t <project-name> .

# Run the container
docker run -d \
  -p 80:80 \
  -e RAILS_MASTER_KEY=$(cat config/master.key) \
  -e SETTINGS_APP_URL=https://your-domain.com \
  -e DATABASE_URL=sqlite3:/path/to/database.sqlite3 \
  --name <project-name> \
  <project-name>

Option 3: Traditional Server

# Install dependencies
bundle install --deployment --without development test
bun install --production

# Precompile assets
RAILS_ENV=production bin/rails assets:precompile

# Start the server (with Thruster for performance)
./bin/thrust ./bin/rails server -e production

Production Configuration

1. Database: SQLite (default) or configure DATABASE_URL for PostgreSQL/MySQL
2. Assets: Precompiled in production
3. Jobs: Solid Queue runs automatically
4. Cache: Solid Cache configured
5. Logging: Structured logging enabled

Required Production Environment Variables

# Required
RAILS_MASTER_KEY=your_master_key
SETTINGS_APP_URL=https://your-domain.com
SETTINGS_APP_NAME=Your App Name

# SMTP (for email)
SETTINGS_SMTP_ADDRESS=smtp.example.com
SETTINGS_SMTP_PORT=587
SETTINGS_SMTP_USERNAME=user@example.com
SETTINGS_SMTP_PASSWORD=password
SETTINGS_SMTP_AUTHENTICATION=true

# Optional
DATABASE_URL=sqlite3:/path/to/production.sqlite3
RAILS_MAX_THREADS=5

---

🛠️ Development

Running Tests

# Run all tests
bin/rails test

# Run specific test
bin/rails test test/models/user_test.rb

# Run with specific seed
bin/rails test SEED=12345

Code Quality

# Run RuboCop
bin/rubocop

# Run Brakeman (security scanner)
bundle exec brakeman

# Run Bundler Audit
bundle audit

Generators

# Generate a new model
bin/rails generate model Post title:string body:text

# Generate a new controller
bin/rails generate controller Posts index show new create

# Generate a new component
bin/rails generate component Card title content

# Generate a new policy
bin/rails generate pundit:policy Post

Database Operations

# Run migrations
bin/rails db:migrate

# Rollback last migration
bin/rails db:rollback

# Create a new migration
bin/rails generate migration AddColumnToTable column:type

# Reset the database
bin/rails db:reset

# Seed the database
bin/rails db:seed

Background Jobs

# Start the worker
bin/rails solid_queue:start

# Stop the worker
bin/rails solid_queue:stop

# Restart the worker
bin/rails solid_queue:restart

# View jobs dashboard
# Visit /admin/jobs in your browser (admin only)

Email Previews

View and test email templates in development at: http://localhost:3000/rails/mailers

This shows previews for all mailers in the application:

• OnboardingMailer (welcome, email verification, etc.)
• PasswordsMailer (password reset)

---

🎯 Project Structure Details

Models

Model	Description
User	Main user model with authentication
User::Profile	User profile information
User::Identity	OAuth provider identities
User::Passkey	WebAuthn passkeys
Session	User sessions with geo-tracking
GlobalConfig	Global application settings
SocialAccounts	Social media account links
Ahoy::Visit	Visit tracking
Ahoy::Event	Event tracking

Controllers

Controller	Description
ApplicationController	Base controller
PagesController	Static pages (home, imprint, privacy, etc.)
SessionsController	Login/logout
RegistrationsController	User registration
PasswordsController	Password reset
OAuthSessionsController	OAuth authentication
EmailVerificationsController	Email verification
AdminController	Admin dashboard
Admin::UsersController	User management
Admin::ActivitiesController	Activity log
Settings::ProfileController	Profile settings
Settings::SecurityController	Security settings

Policies (Pundit)

Policy	Description
ApplicationPolicy	Base policy
PagePolicy	Page access policies
ProfilePolicy	Profile editing permissions
SecurityPolicy	Security settings permissions
SessionPolicy	Session management permissions
RegistrationPolicy	Registration permissions
SystemPolicy	System/admin permissions
UserPolicy	User management permissions

Components (Phlex)

Component	Description
Components::Base	Base component class
Components::Form	Form builder
Components::Layout::Navbar	Navigation bar
Components::Layout::Footer	Footer with links
Components::Layout::Sidebar	Sidebar navigation
Components::Layout::Theme	Theme toggle
Components::Layout::Flash	Flash messages
Components::Icon	Icon rendering
Components::Dropdown	Dropdown menus
Components::Pagination	Pagination
Components::Table	Data tables
Components::Tabs	Tab navigation
Components::SearchForm	Search forms
Components::Users::Avatar	User avatar
Components::Users::Session	Session display
Components::Users::Passkey	Passkey display

---

📚 Routes

Public Routes

Route	Controller	Description
/	Pages#home	Home page
/sign_up	Registrations#new	Registration form
/sign_in	Sessions#create	Login
/sign_out	Sessions#destroy	Logout
/auth/:provider	OAuthSessions#create	OAuth callback
/auth/:provider/callback	OAuthSessions#create	OAuth callback
/auth/failure	OAuthSessions#failure	OAuth failure

User Routes

Route	Controller	Description
/users	Users#index	List users
/users/:username	Users#show	User profile

Settings Routes

Route	Controller	Description
/settings/profile/edit	Settings::Profile#edit	Edit profile
/settings/profile	Settings::Profile#update	Update profile
/settings/security/edit	Settings::Security#edit	Security settings
/settings/security	Settings::Security#update	Update security
/settings/delete	Settings::Security#delete	Delete account

Admin Routes

Route	Controller	Description
/admin	Admin#show	Admin dashboard
/admin/edit	Admin#edit	Edit global settings
/admin	Admin#update	Update global settings
/admin/users	Admin::Users#index	List users
/admin/users/:id	Admin::Users#show	User details
/admin/users/:id/edit	Admin::Users#edit	Edit user
/admin/users/:id	Admin::Users#update	Update user
/admin/users/:id/lock	Admin::Users#lock	Lock user
/admin/users/:id/unlock	Admin::Users#unlock	Unlock user
/admin/activities	Admin::Activities#index	Activity log
/admin/jobs	MissionControl::Jobs	Jobs dashboard

Legal Pages

Route	Controller	Description
/imprint	Pages#imprint	Imprint page
/privacy_policy	Pages#privacy_policy	Privacy policy
/terms_of_service	Pages#terms_of_service	Terms of service

API-style Routes

Route	Controller	Method	Description
/email/verify/:token	EmailVerifications#show	GET	Verify email
/email/reset_verification	EmailVerifications#create	POST	Resend verification
/passwords	Passwords#create	POST	Request reset
/passwords/:token	Passwords#new	GET	Reset form
/passwords/:token	Passwords#create	PATCH	Update password
/sessions/passkeys	Sessions::Passkeys#create	POST	Authenticate with passkey
/sessions/passkeys/options	Sessions::Passkeys#options	POST	Get passkey options
/sessions/otp	Sessions::Otp#create	POST	Verify OTP
/sessions/otp	Sessions::Otp#destroy	DELETE	Clear OTP
/settings/security/passkeys	Settings::Security::Passkeys#create	POST	Add passkey
/settings/security/passkeys/:id	Settings::Security::Passkeys#destroy	DELETE	Remove passkey
/settings/security/passkeys/options	Settings::Security::Passkeys#options	POST	Get options
/settings/security/otp	Settings::Security::Otps#create	POST	Enable OTP
/settings/security/otp	Settings::Security::Otps#destroy	DELETE	Disable OTP

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes
4. Run tests (bin/rails test)
5. Run code quality checks (bin/rubocop)
6. Commit your changes (git commit -m 'Add your feature')
7. Push to the branch (git push origin feature/your-feature)
8. Open a Pull Request

---

📜 License

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

---

🙏 Acknowledgments

• Ruby on Rails - The web framework
• Phlex - View components for Rails
• Hotwire - Modern web development
• DaisyUI - Tailwind CSS components
• Bun - Fast JavaScript runtime
• Solid Queue - Background jobs
• Ahoy - Analytics
• WebAuthn - Passkey support

---

📞 Support

For questions or issues, please open a GitHub issue or contact the maintainers.