MySMSAPio/STARTUP_GUIDE.md

MySMSAPio - Startup Guide

⚠️ Important: Configuration Changes Made

The application configuration has been updated to support both API endpoints and the admin web interface. You MUST restart your Rails server for these changes to take effect.

Quick Start

1. Stop Any Running Servers

If you have a Rails server running, stop it first (Ctrl+C).

2. Start the Server

Option A: With Tailwind CSS watch (Recommended)

bin/dev

This starts both Rails server and Tailwind CSS watcher.

Option B: Rails server only

bin/rails server

3. Access the Admin Interface

Open your browser to:

http://localhost:3000/admin/login

4. Login

Email: admin@example.com
Password: password123

⚠️ Remember to change this password in production!

What Changed

Configuration Updates

1. Disabled API-Only Mode

   • File: config/application.rb
   • Changed: Commented out config.api_only = true
   • Reason: Allows admin interface to use sessions and flash messages

2. Added Session Store

   • File: config/initializers/session_store.rb
   • Added: Cookie-based session configuration
   • Reason: Required for admin authentication

3. CSRF Protection

   • All admin controllers have CSRF protection enabled
   • Forms automatically include CSRF tokens
   • API endpoints (ActionController::API) are unaffected

Why These Changes Were Needed

The Problem:

• The app was configured as api_only = true
• This disables sessions, flash messages, and cookies
• Admin interface needs these features for authentication

The Solution:

• Keep API controllers using ActionController::API (fast, stateless)
• Admin controllers use ActionController::Base (full Rails features)
• Both work together in the same app

Architecture

MySMSAPio Application
│
├── API Endpoints (Fast & Stateless)
│   ├── /api/v1/sms/*
│   ├── /api/v1/otp/*
│   └── /api/v1/gateway/*
│   └── Controllers inherit from ActionController::API
│   └── Use: Token authentication, no sessions
│
└── Admin Interface (Full Rails Features)
    ├── /admin/login
    ├── /admin/dashboard
    ├── /admin/api_keys
    ├── /admin/logs
    └── /admin/gateways
    └── Controllers inherit from ActionController::Base
    └── Use: Session authentication, flash messages, cookies

Troubleshooting

Error: "undefined method 'flash'"

Solution: Restart the Rails server. Configuration changes require a server restart.

# Stop the server (Ctrl+C), then:
bin/dev
# or
bin/rails server

Error: "Admin is not a module"

Solution: This was already fixed by renaming the model to AdminUser. If you see this:

bin/rails db:migrate
bin/rails db:seed

Login Page Shows 404

Check routes:

bin/rails routes | grep admin

Should show routes like /admin/login, /admin/dashboard, etc.

Session Not Persisting

Check middleware:

bin/rails middleware | grep Session

Should show: use ActionDispatch::Session::CookieStore

API Endpoints Not Working

The API endpoints should work exactly as before. Test with:

curl -H "Authorization: Bearer your_api_key" \
  http://localhost:3000/api/v1/sms/received

Development Workflow

Daily Development

# Start everything
bin/dev

# This runs:
# - Rails server (port 3000)
# - Tailwind CSS watcher (auto-rebuild on changes)

Running Tests

bin/rails test

Database Operations

# Reset database
bin/rails db:reset

# Run migrations
bin/rails db:migrate

# Seed data
bin/rails db:seed

Code Quality

# Run RuboCop
bin/rubocop

# Run Brakeman security scanner
bin/brakeman

Production Deployment

Environment Variables

Make sure these are set:

DATABASE_URL=postgresql://...
REDIS_URL=redis://...
SECRET_KEY_BASE=your_secret_key
RAILS_ENV=production

Precompile Assets

bin/rails assets:precompile
bin/rails tailwindcss:build

Change Default Password

bin/rails console

# In console:
admin = AdminUser.find_by(email: 'admin@example.com')
admin.update!(password: 'your_secure_password')

Enable HTTPS

Update config/environments/production.rb:

config.force_ssl = true

Features Working

✅ Admin Dashboard

• Real-time statistics
• Recent messages
• Gateway status

✅ API Keys Management

• Create with permissions
• View all keys
• Revoke keys

✅ SMS Logs

• Filter by direction, status, date
• View error messages
• Pagination

✅ Gateway Management

• View all gateways
• Activate/deactivate
• Monitor health

✅ Authentication

• Session-based login
• Flash messages
• CSRF protection

✅ Professional UI

• Tailwind CSS theme
• Responsive design
• Animated indicators

Need Help?

Documentation

• README.md - Project overview
• ADMIN_INTERFACE.md - Complete admin documentation
• ADMIN_QUICKSTART.md - Quick reference
• NAMESPACE_FIX.md - Model naming fix
• SESSION_MIDDLEWARE_FIX.md - Middleware configuration

Logs

# Development log
tail -f log/development.log

# Test log
tail -f log/test.log

Rails Console

bin/rails console

# Check AdminUser
AdminUser.count
AdminUser.first.email

# Check API Keys
ApiKey.count

# Check Gateways
Gateway.count

Summary

1. ✅ Configuration updated to support admin interface
2. ✅ Sessions and flash messages enabled
3. ✅ API endpoints remain fast and stateless
4. ✅ Both admin and API work together
5. ⚠️ Must restart server after configuration changes

Start the server with bin/dev and access the admin at http://localhost:3000/admin/login!

Happy coding! 🚀