Rock-Spotter

This guide covers deploying the Rock Spotter backend API to various cloud platforms and using Docker.

Table of Contents

1. Prerequisites
2. Environment Variables
3. Docker Deployment
4. Render Deployment
5. Railway Deployment
6. Heroku Deployment
7. DigitalOcean App Platform
8. AWS Elastic Beanstalk
9. Vercel/Netlify (Serverless)
10. Post-Deployment Checklist

Prerequisites

• Node.js v14 or higher
• MongoDB database (MongoDB Atlas recommended for production)
• Git
• Account on your chosen deployment platform

Environment Variables

All deployment platforms require these environment variables:

Variable	Description	Example
NODE_ENV	Environment mode	production
PORT	Server port (usually auto-set)	3000
MONGODB_URI	MongoDB connection string	mongodb+srv://user:pass@cluster.mongodb.net/rock-spotter
JWT_SECRET	Secret key for JWT tokens	your-random-secret-key-here

Getting MongoDB Connection String

Option 1: MongoDB Atlas (Recommended)

1. Go to MongoDB Atlas
2. Create a free cluster
3. Create a database user
4. Whitelist your IP (or use 0.0.0.0/0 for all IPs)
5. Get connection string from “Connect” button
6. Replace <password> with your database password
7. Replace myFirstDatabase with rock-spotter

Option 2: Local MongoDB

mongodb://localhost:27017/rock-spotter

Docker Deployment

Using Docker Compose (Recommended for local/VPS)

The project includes a docker-compose.yml that sets up both the API and MongoDB.

1. Clone the repository:

   git clone https://github.com/jmenichole/Rock-Spotter.git
   cd Rock-Spotter
   

2. Set environment variables: Create a .env file in the root directory:

   JWT_SECRET=your-random-secret-key-here
   

3. Start services:

   docker-compose up -d
   

4. Verify deployment:

   curl http://localhost:3000/api/health
   

5. View logs:

   docker-compose logs -f backend
   

6. Stop services:

   docker-compose down
   

Using Docker Only

1. Build the image:

   cd backend
   docker build -t rock-spotter-api .
   

2. Run the container:

   docker run -d \
     -p 3000:3000 \
     -e MONGODB_URI="your-mongodb-uri" \
     -e JWT_SECRET="your-secret-key" \
     -e NODE_ENV=production \
     --name rock-spotter \
     rock-spotter-api
   

3. Check status:

   docker ps
   docker logs rock-spotter
   

Render Deployment

Render offers free hosting for web services and is great for hobby projects.

Method 1: Using Blueprint (Recommended)

1. Fork/Clone the repository to your GitHub account

2. Create a MongoDB Atlas database (free tier available)

3. Deploy to Render:
   • Go to Render Dashboard
   • Click “New” → “Blueprint”
   • Connect your GitHub repository
   • Render will detect render.yaml and configure services automatically
4. Set environment variables:
   • Go to your web service settings
   • Add MONGODB_URI with your MongoDB Atlas connection string
   • JWT_SECRET will be auto-generated
5. Deploy:
   • Click “Apply” to deploy
   • Wait for deployment to complete
   • Your API will be available at https://rock-spotter-api.onrender.com

Method 2: Manual Setup

1. Create a new Web Service:
   • Go to Render Dashboard
   • Click “New” → “Web Service”
   • Connect your repository
2. Configure the service:
   • Name: rock-spotter-api
   • Environment: Node
   • Region: Choose closest to you
   • Branch: main
   • Build Command: cd backend && npm install
   • Start Command: cd backend && npm start
3. Add environment variables:
   • NODE_ENV = production
   • MONGODB_URI = your-mongodb-atlas-uri
   • JWT_SECRET = your-random-secret-key
4. Create the service and wait for deployment

Free Tier Limitations

• Services spin down after 15 minutes of inactivity
• First request after inactivity may take 30-60 seconds
• 750 hours/month free (enough for 1 service running 24/7)

Railway Deployment

Railway offers $5 free credit per month and excellent developer experience.

1. Install Railway CLI (optional):

   npm install -g railway
   

2. Deploy via Dashboard:
   • Go to Railway
   • Click “New Project”
   • Choose “Deploy from GitHub repo”
   • Select your repository
   • Railway will detect railway.json configuration
3. Add MongoDB:
   • Click “New” → “Database” → “Add MongoDB”
   • Railway will automatically set MONGODB_URI
4. Set environment variables:
   • Go to Variables tab
   • Add JWT_SECRET
   • NODE_ENV and PORT are auto-set
5. Deploy:
   • Railway deploys automatically on push
   • Get your URL from Settings → Domains

CLI Deployment

# Login
railway login

# Initialize project
cd Rock-Spotter
railway init

# Add MongoDB
railway add

# Set variables
railway variables set JWT_SECRET=your-secret-key

# Deploy
railway up

Heroku Deployment

Heroku is a classic PaaS with free tier (limited).

1. Install Heroku CLI:

   npm install -g heroku
   

2. Login to Heroku:

   heroku login
   

3. Create Heroku app:

   cd Rock-Spotter
   heroku create rock-spotter-api
   

4. Add MongoDB addon: ```bash

   Option 1: MongoDB Atlas addon (recommended)

   heroku addons:create mongolab:sandbox

Option 2: Set MongoDB URI manually

heroku config:set MONGODB_URI=”your-mongodb-atlas-uri”

5. **Set environment variables:**
```bash
heroku config:set JWT_SECRET="your-random-secret-key"
heroku config:set NODE_ENV=production

1. Deploy:

   git push heroku main
   

2. Open the app:

   heroku open
   heroku logs --tail
   

Heroku Configuration

The project includes a Procfile for Heroku:

web: cd backend && npm start

DigitalOcean App Platform

DigitalOcean offers $200 free credit for 60 days.

1. Create account at DigitalOcean

2. Create App:
   • Go to Apps section
   • Click “Create App”
   • Choose GitHub and select repository
   • Select branch: main
3. Configure app:
   • Name: rock-spotter-api
   • Source Directory: backend
   • Build Command: npm install
   • Run Command: npm start
   • HTTP Port: 3000
4. Add MongoDB:
   • Create a MongoDB cluster in DigitalOcean
   • Or use MongoDB Atlas
   • Add connection string to environment variables
5. Set environment variables:

   NODE_ENV=production
   MONGODB_URI=your-mongodb-uri
   JWT_SECRET=your-secret-key
   

6. Create resources and deploy

AWS Elastic Beanstalk

AWS offers 12 months free tier for new accounts.

1. Install EB CLI:

   pip install awsebcli
   

2. Initialize EB:

   cd Rock-Spotter
   eb init -p node.js rock-spotter-api --region us-west-2
   

3. Create environment:

   eb create rock-spotter-env
   

4. Set environment variables:

   eb setenv NODE_ENV=production \
     MONGODB_URI="your-mongodb-uri" \
     JWT_SECRET="your-secret-key"
   

5. Deploy:

   eb deploy
   

6. Open app:

   eb open
   eb logs
   

AWS Configuration

Create .ebextensions/nodecommand.config:

option_settings:
  aws:elasticbeanstalk:container:nodejs:
    NodeCommand: "cd backend && npm start"

Vercel/Netlify (Serverless)

Note: These platforms are optimized for frontend apps and serverless functions. The Rock Spotter backend uses Express with persistent MongoDB connections, which works better on traditional hosting platforms (Render, Railway, Heroku).

If you want to deploy on Vercel/Netlify, you’ll need to refactor the backend into serverless functions.

Post-Deployment Checklist

After deploying to any platform:

1. Test the API

# Health check
curl https://your-app-url.com/api/health

# Should return:
# {"status":"ok","message":"Rock Spotter API is running!"}

2. Create test user

curl -X POST https://your-app-url.com/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'

3. Test authentication

curl -X POST https://your-app-url.com/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

4. Verify database connection

Check your platform logs to ensure MongoDB connection is successful:

MongoDB connected successfully
Rock Spotter API server running on port 3000

5. Set up monitoring (optional)

• Enable logging in your platform dashboard
• Set up uptime monitoring (e.g., UptimeRobot)
• Configure error tracking (e.g., Sentry)

6. Update CORS (if needed)

If you have a frontend, update CORS settings in backend/src/server.js:

app.use(cors({
  origin: ['https://your-frontend-url.com'],
  credentials: true
}));

7. Secure your JWT secret

• Generate a strong random secret
• Never commit secrets to Git
• Use platform secret management

Generate a secure secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

8. Set up database backups

• Enable automated backups in MongoDB Atlas
• Schedule regular backup exports
• Test restore procedures

9. Configure custom domain (optional)

Most platforms allow adding custom domains:

• Add your domain in platform settings
• Update DNS records (CNAME or A record)
• Enable HTTPS/SSL (usually automatic)

10. Update documentation

Update your README with:

• Production API URL
• API documentation link
• Example requests with production URL

Common Issues

Issue: “Cannot connect to MongoDB”

Solutions:

• Check MongoDB Atlas IP whitelist includes 0.0.0.0/0
• Verify connection string format
• Check database user credentials
• Ensure database name is included in URI

Issue: “Port already in use”

Solution: Most platforms auto-set PORT. In server.js:

const PORT = process.env.PORT || 3000;

Issue: “JWT authentication fails”

Solution: Ensure JWT_SECRET is set and matches on all instances

Issue: “App crashes after deployment”

Solutions:

• Check platform logs for errors
• Verify all dependencies are in package.json
• Ensure NODE_ENV is set to “production”
• Check start command is correct

Issue: “Slow cold starts”

Solutions:

• Use paid tier to keep service running
• Implement health check endpoint pinging
• Use CDN for static assets
• Optimize dependencies

Updating Your Deployment

Automatic Deployment (CI/CD)

Most platforms support automatic deployment from Git:

1. Push to main branch:

   git add .
   git commit -m "Update API"
   git push origin main
   

2. Platform auto-deploys (usually takes 1-3 minutes)

Manual Deployment

# Render: Auto-deploys on git push
# Railway: railway up
# Heroku: git push heroku main
# DigitalOcean: Auto-deploys on git push

Scaling Your Application

Horizontal Scaling

• Render: Upgrade plan for multiple instances
• Railway: Adjust replicas in settings
• Heroku: heroku ps:scale web=2

Vertical Scaling

• Upgrade to larger instance size in platform settings
• Monitor CPU and memory usage
• Consider caching (Redis) for performance

Database Scaling

• MongoDB Atlas: Upgrade cluster tier
• Enable connection pooling
• Add read replicas for high traffic

Cost Estimates

Platform	Free Tier	Paid Tier Starts At
Render	750 hrs/month	$7/month
Railway	$5 credit/month	$0.000231/GB-hour
Heroku	1000 hrs/month	$7/month
DigitalOcean	$200 credit (60 days)	$5/month
AWS EB	12 months free	Varies
MongoDB Atlas	512MB free	$9/month

Security Best Practices

1. Never commit secrets to Git
2. Use strong JWT secrets (32+ random characters)
3. Enable rate limiting for API endpoints
4. Use HTTPS (usually automatic on platforms)
5. Keep dependencies updated (npm audit)
6. Set secure headers (use helmet middleware)
7. Validate all inputs (use express-validator)
8. Implement API authentication for all protected routes
9. Monitor logs for suspicious activity
10. Regular backups of database

Support

For deployment issues:

• Check platform documentation
• Review platform status page
• Check GitHub Issues
• Contact platform support

Next Steps

After successful deployment:

1. ✅ Test all API endpoints
2. ✅ Set up monitoring and alerts
3. ✅ Configure custom domain (optional)
4. ✅ Implement CI/CD pipeline
5. ✅ Set up staging environment
6. ✅ Create mobile app connecting to API
7. ✅ Implement photo upload to cloud storage
8. ✅ Add caching layer (Redis)
9. ✅ Set up API documentation (Swagger)
10. ✅ Implement analytics

---

Congratulations on deploying Rock Spotter! 🪨🚀

Your API is now live and ready to serve rock enthusiasts worldwide!

This site is open source. Improve this page.