Skip to main content
Docker deployment is the easiest and fastest way to run Spoo.me locally. Everything you need—MongoDB, Redis, and the application—runs together with a single command. No complex setup required!
What’s Included: Docker Compose automatically sets up MongoDB, Redis, and the Spoo.me application in isolated containers. You don’t need to install or configure databases separately.

​
Prerequisites

All you need:
  • Docker and Docker Compose installed on your system
  • That’s it! MongoDB and Redis are automatically included

​
Installing Docker

Download and install Docker Desktop from docker.com, or use Homebrew:
brew install --cask docker
Start Docker Desktop and verify:
docker --version
docker-compose --version

​
Quick Start - Get Running in 4 Steps

1

Clone the Repository

git clone https://github.com/spoo-me/url-shortener.git
cd url-shortener
2

Create .env File

cp .env.example .env
That’s it! The default .env.example works out of the box. MongoDB and Redis are automatically configured by Docker.
If you want v1 API features (user authentication, URL management, API keys), you can optionally configure:You can skip these and add them later—basic URL shortening works without them!
3

Start Docker Compose

docker-compose up -d
This single command starts everything:
  • MongoDB database
  • Redis cache
  • Spoo.me application
First run takes 3-5 minutes to download images and build. Subsequent starts take only seconds!
4

Access Your Instance

Open your browser and visit:http://localhost:8000
Try shortening a URL to verify everything works!

​
What Just Happened?

Docker Compose automatically:
  • ✅ Created a MongoDB database container
  • ✅ Created a Redis cache container
  • ✅ Built the Spoo.me application container
  • ✅ Connected everything together
  • ✅ Persisted your data in Docker volumes
No manual database setup, no configuration files, no complex installation steps!

​
Production Deployment

Want to deploy to a production server with a domain? Just a few small changes:
1

Use Cloud Database (Recommended)

For production, use a managed database instead of local containers:In your .env file:
# Replace the MongoDB URI with your cloud database
MONGODB_URI=mongodb+srv://username:[email protected]/spoo-me

# Optional: Use managed Redis (e.g., Redis Cloud, Upstash)
REDIS_URL=redis://username:password@host:port
Using MongoDB Atlas (free tier available) gives you automatic backups, better performance, and no maintenance hassle.
2

Update Docker Compose for Production

Modify docker-compose.yml to remove local database containers:
version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - MONGODB_URI=${MONGODB_URI}  # Uses cloud MongoDB
      - REDIS_URL=${REDIS_URL}      # Optional: cloud Redis
      - CONTACT_WEBHOOK=${CONTACT_WEBHOOK}
      - URL_REPORT_WEBHOOK=${URL_REPORT_WEBHOOK}
      - FLASK_SECRET_KEY=${FLASK_SECRET_KEY}
      # Add your OAuth variables if configured
      - JWT_PRIVATE_KEY=${JWT_PRIVATE_KEY}
      - JWT_PUBLIC_KEY=${JWT_PUBLIC_KEY}
      - GOOGLE_OAUTH_CLIENT_ID=${GOOGLE_OAUTH_CLIENT_ID}
      - GOOGLE_OAUTH_CLIENT_SECRET=${GOOGLE_OAUTH_CLIENT_SECRET}
      # ... other OAuth providers
    restart: unless-stopped

# No mongo or redis containers needed when using cloud services!
3

Add Reverse Proxy (Optional)

For custom domains and SSL, add Nginx:
# Add to docker-compose.yml
services:
  # ... your app service ...
  
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - /etc/letsencrypt:/etc/letsencrypt:ro  # SSL certs
    depends_on:
      - app
    restart: unless-stopped
Basic nginx.conf:
events { worker_connections 1024; }

http {
    upstream app {
        server app:8000;
    }

    server {
        listen 80;
        server_name your-domain.com;
        
        location / {
            proxy_pass http://app;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}
Use Certbot to get free SSL certificates:
# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Get SSL certificate
sudo certbot --nginx -d your-domain.com

# Certificates auto-renew, stored in /etc/letsencrypt
Update your nginx config to handle HTTPS and redirect HTTP to HTTPS.

​
Common Commands

Start Services

docker-compose up -d
Starts all containers in the background

Stop Services

docker-compose down
Stops and removes containers (data persists in volumes)

View Logs

docker-compose logs -f
Follow logs in real-time for all services

Restart

docker-compose restart
Restart all containers

​
More Useful Commands

# View running containers
docker-compose ps

# View logs for specific service
docker-compose logs app     # Application logs
docker-compose logs mongo   # MongoDB logs
docker-compose logs redis   # Redis logs

# Update to latest code
git pull
docker-compose up -d --build

# Clean up unused Docker resources
docker system prune -a

​
Accessing Containers

# Access MongoDB shell
docker-compose exec mongo mongosh

# Access application shell
docker-compose exec app bash

# View container resource usage
docker stats

​
Troubleshooting

Error: Cannot start service app: Ports are not available: port is already allocatedSolution: Another service is using port 8000. Either stop that service or change the port:
# In docker-compose.yml, change the host port:
ports:
  - "8001:8000"  # Now access via localhost:8001
Cause: Usually a configuration error in .envSolution: Check logs for the specific container:
docker-compose logs app
docker-compose logs mongo
Common issues:
  • Invalid MongoDB URI format
  • Missing required environment variables
  • Docker resource limits too low
For local Docker setup: This shouldn’t happen! The containers are auto-configured.For production with cloud databases:
  • Verify your MONGODB_URI in .env is correct
  • Check firewall rules allow connections
  • Ensure IP whitelist includes your server IP
Error: Cannot connect to the Docker daemonSolution:
# Linux
sudo systemctl start docker

# macOS/Windows
# Start Docker Desktop application

​
Why Docker is the Best Option

✅ Zero Configuration: MongoDB and Redis work instantly, no setup needed ✅ Everything Bundled: One command installs the complete stack ✅ Consistent Environment: Works the same on any OS (macOS, Linux, Windows) ✅ Easy Updates: git pull && docker-compose up -d --build ✅ Data Persistence: Your URLs and data survive container restarts ✅ Clean Uninstall: Remove everything with docker-compose down -v

​
Next Steps

Enable Authentication

Add OAuth login for v1 API features

Local Development

Set up for code customization and development

Cloud Deployment

Deploy to production with managed databases

Create Webhooks

Get notifications for contact forms and reports