Before proceeding, ensure you have completed the prerequisite steps:
Platform Comparison
Choose the platform that best fits your needs:| Platform | Free Tier | Custom Domain | Pros | Best For |
|---|---|---|---|---|
| Vercel | Generous | ✅ Free | Excellent performance, great DX | Most users |
| Railway | $5 credit | ✅ Free | Simple setup, good performance | Developers |
| Render | 750 hours/month | ✅ Free | Reliable, good free tier | Stable hosting |
| Koyeb | Limited | ❌ Paid only | Good performance | Testing only |
Recommended: Start with Vercel for the best combination of features and ease of use.
Method 1: Vercel Deployment (Recommended)
Vercel offers the most generous free plan and excellent performance for Spoo.me deployments.1
Prepare Your GitHub Account
- Create a GitHub account if you don’t have one
- Sign up for Vercel and connect your GitHub account
Vercel will need access to your GitHub account to create and deploy repositories.
2
Deploy with One Click
Click the deploy button to start the deployment process:
This will:
- Fork the Spoo.me repository to your GitHub account
- Set up a new Vercel project
- Prompt you for environment variables
3
Configure Environment Variables
In the deployment configuration, enter your environment variables:
Your MongoDB connection string from the MongoDB setup guide
Discord webhook URL for contact form notifications
Discord webhook URL for URL report notifications
Redis connection string for caching. Optional, but recommended for production.
Double-check your environment variables before deploying. Incorrect values will cause deployment failures.
4
Complete Deployment
- Click “Deploy” and wait for the build process to complete
- Once finished, you’ll receive a deployment URL like
https://your-project.vercel.app - Test your deployment by visiting the URL
Your Spoo.me instance should now be live and fully functional!
5
Add Custom Domain (Optional)
To use your own domain:
- Go to your Vercel project dashboard
- Navigate to Settings → Domains
- Add your custom domain
- Configure DNS records as instructed by Vercel
Vercel provides free SSL certificates for custom domains automatically.
Method 2: Railway Deployment
Railway offers $5 in free credits upon account verification, which typically lasts 5-7 months.1
Set Up Railway Account
- Create a Railway account
- Verify your account with your email
- Connect your GitHub account for additional verification
Account verification is required to receive the $5 free credit.
2
Deploy from Template
Click the Railway deployment button:
If prompted, configure Railway to access your GitHub account.
If prompted, configure Railway to access your GitHub account.3
Configure Environment Variables
Railway will prompt you to fill in the required environment variables. The environment variables are the same as the ones you set up in vercel deployment.Enter the values you prepared in the prerequisite steps.
4
Deploy and Access
- Click “Deploy” to start the deployment
- Wait for the build process to complete
- Copy the deployment URL from the Deployments tab
- Your URL will look like:
https://your-project.up.railway.app
You may encounter a 502 error initially. This typically resolves within a few minutes as the service starts up.
Method 3: Render Deployment
Render provides 750 hours of free hosting per month, which is sufficient for most Spoo.me deployments.1
Create Render Account
Sign up for a free Render account.
2
Deploy from Blueprint
Use the Render deployment button:
3
Configure Blueprint
- Enter a Blueprint Name (e.g., “Spoo.me URL Shortener”)
- Fill in the environment variables section. The environment variables are the same as the ones you set up in vercel deployment.
- Click “Deploy Blueprint” to start deployment
4
Access Your Deployment
- Wait for the deployment to complete
- Your app will be available at:
https://your-project.onrender.com - Test the deployment by creating a short URL
Render automatically provides SSL certificates and handles scaling for you.
Method 4: Koyeb Deployment
Koyeb offers one free deployment, though custom domains require a paid plan.1
Create Koyeb Account
Sign up for a Koyeb account.
2
Deploy from GitHub
- Click the Koyeb deployment button:
- Configure your deployment settings as needed
3
Set Environment Variables
In the deployment configuration:
- Scroll to Environment Variables
- Add your the required variables. The environment variables are the same as the ones you set up in vercel deployment.
- Click “Deploy”
4
Access Your App
Your deployment will be available at:
https://your-project.koyeb.appKoyeb’s free plan doesn’t support custom domains. Consider upgrading or using another platform if you need a custom domain.
Post-Deployment Configuration
After successful deployment on any platform:1
Test Core Functionality
- URL Shortening: Create a test short URL
- Analytics: Check that click tracking works
- Contact Form: Submit a test contact form
- URL Reporting: Test the URL reporting feature
Verify that webhook notifications appear in your Discord channels.
2
Monitor Performance
Most platforms provide built-in monitoring:
- Vercel: Analytics tab in project dashboard
- Railway: Metrics tab in service dashboard
- Render: Metrics section in service dashboard
- Koyeb: Monitoring tab in service dashboard
Set up alerts for downtime or high error rates to stay informed about your service health.
3
Set Up Custom Domain (If Needed)
If you want to use your own domain:
- Purchase a domain from a registrar
- Proxy with cloudflare or any other DNS manager for faster DNS propagation
- Configure DNS records as instructed
- Wait for DNS propagation (usually a few minutes if you use cloudflare)
Limitations of Cloud Deployment
While cloud deployment is convenient, there are some limitations to consider:Limited Customization: You cannot modify the application code or add custom features like analytics integrations or custom SEO elements.
- No code modifications: The deployed version is exactly as provided in the repository, except when using vercel because they create a private fork on your gitHub account before deploying.
- Platform dependencies: Your deployment depends on the chosen platform’s reliability and pricing
- Resource limits: Free tiers have usage limits that may affect high-traffic deployments
If you need more control or customization, consider Docker deployment or local development instead.
Troubleshooting Common Issues
Build/Deployment Failures
Build/Deployment Failures
Symptoms: Deployment fails during build processSolutions:
- Verify all environment variables are correctly set
- Check that your MongoDB connection string is valid
- Ensure webhook URLs are properly formatted
- Review build logs for specific error messages
Database Connection Errors
Database Connection Errors
Symptoms: App loads but can’t create/retrieve URLsSolutions:
- Test your MongoDB connection string manually
- Verify your MongoDB Atlas IP whitelist includes 0.0.0.0/0
- Check that your database user has proper permissions
- Ensure your cluster is running and accessible
Webhook Not Working
Webhook Not Working
Symptoms: Forms submit but no Discord notificationsSolutions:
- Test webhook URLs manually using curl
- Verify Discord channels still exist
- Check that webhook permissions haven’t been revoked
- Ensure webhook URLs are correctly configured in environment variables
Custom Domain Issues
Custom Domain Issues
Symptoms: Custom domain doesn’t work or shows SSL errorsSolutions:
- Verify DNS records are correctly configured
- Wait for DNS propagation (up to 48 hours)
- Check that your domain registrar supports the required record types
- Ensure SSL certificates have been issued (usually automatic)
Cost Considerations
All recommended platforms offer generous free tiers:- Vercel: Free for personal projects, very high limits
- Railway: $5 credit covers ~5-7 months of usage
- Render: 750 free hours per month (enough for continuous hosting)
- Koyeb: Limited free tier, paid plans start at $5/month
For most personal or small business use cases, the free tiers are more than sufficient. You can always upgrade later if needed.