completed SMS gateway project
This commit is contained in:
Min Zeya Phyo
281
STARTUP_GUIDE.md
Normal file
281
STARTUP_GUIDE.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# 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)**
|
||||
```bash
|
||||
bin/dev
|
||||
```
|
||||
This starts both Rails server and Tailwind CSS watcher.
|
||||
|
||||
**Option B: Rails server only**
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
bin/rails db:migrate
|
||||
bin/rails db:seed
|
||||
```
|
||||
|
||||
### Login Page Shows 404
|
||||
**Check routes:**
|
||||
```bash
|
||||
bin/rails routes | grep admin
|
||||
```
|
||||
|
||||
Should show routes like `/admin/login`, `/admin/dashboard`, etc.
|
||||
|
||||
### Session Not Persisting
|
||||
**Check middleware:**
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer your_api_key" \
|
||||
http://localhost:3000/api/v1/sms/received
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Daily Development
|
||||
```bash
|
||||
# Start everything
|
||||
bin/dev
|
||||
|
||||
# This runs:
|
||||
# - Rails server (port 3000)
|
||||
# - Tailwind CSS watcher (auto-rebuild on changes)
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
bin/rails test
|
||||
```
|
||||
|
||||
### Database Operations
|
||||
```bash
|
||||
# Reset database
|
||||
bin/rails db:reset
|
||||
|
||||
# Run migrations
|
||||
bin/rails db:migrate
|
||||
|
||||
# Seed data
|
||||
bin/rails db:seed
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
```bash
|
||||
# Run RuboCop
|
||||
bin/rubocop
|
||||
|
||||
# Run Brakeman security scanner
|
||||
bin/brakeman
|
||||
```
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Environment Variables
|
||||
Make sure these are set:
|
||||
```bash
|
||||
DATABASE_URL=postgresql://...
|
||||
REDIS_URL=redis://...
|
||||
SECRET_KEY_BASE=your_secret_key
|
||||
RAILS_ENV=production
|
||||
```
|
||||
|
||||
### Precompile Assets
|
||||
```bash
|
||||
bin/rails assets:precompile
|
||||
bin/rails tailwindcss:build
|
||||
```
|
||||
|
||||
### Change Default Password
|
||||
```bash
|
||||
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`:
|
||||
```ruby
|
||||
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
|
||||
```bash
|
||||
# Development log
|
||||
tail -f log/development.log
|
||||
|
||||
# Test log
|
||||
tail -f log/test.log
|
||||
```
|
||||
|
||||
### Rails Console
|
||||
```bash
|
||||
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! 🚀
|
||||
Reference in New Issue
Block a user