Docker Deployment

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

macOS
Ubuntu/Debian
Windows
Other Linux

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

# Install Docker
sudo apt update
sudo apt install -y docker.io docker-compose

# Add your user to docker group
sudo usermod -aG docker $USER

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Verify installation
docker --version
docker-compose --version

Download and install Docker Desktop from docker.comVerify in PowerShell:

docker --version
docker-compose --version

# Install Docker
sudo yum install -y docker docker-compose  # CentOS/RHEL
# OR
sudo pacman -S docker docker-compose       # Arch

# Add user to docker group and start service
sudo usermod -aG docker $USER
sudo systemctl start docker
sudo systemctl enable docker

Quick Start - Get Running in 4 Steps

Clone the Repository

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

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.

Optional: Enable OAuth & Webhooks

If you want v1 API features (user authentication, URL management, API keys), you can optionally configure:

OAuth Providers: Follow the authentication setup guide to enable Google, GitHub, or Discord login
Discord Webhooks: Follow the webhook creation guide for contact form and report notifications

You can skip these and add them later—basic URL shortening works without them!

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!

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:

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_URI=redis://username:password@host:port

Using MongoDB Atlas (free tier available) gives you automatic backups, better performance, and no maintenance hassle.

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_URI=${REDIS_URI}      # Optional: cloud Redis
      - CONTACT_WEBHOOK=${CONTACT_WEBHOOK}
      - URL_REPORT_WEBHOOK=${URL_REPORT_WEBHOOK}
      - SECRET_KEY=${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!

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;
        }
    }
}

Adding SSL/HTTPS with Let's Encrypt

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

Port Already in Use

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

Containers Keep Restarting

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

Can't Connect to MongoDB/Redis

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

Docker Daemon Not Running

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

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

Prerequisites

Installing Docker

Quick Start - Get Running in 4 Steps

What Just Happened?

Production Deployment

Common Commands

Start Services

Stop Services

View Logs

Restart

More Useful Commands

Accessing Containers

Troubleshooting

Why Docker is the Best Option

Next Steps

Enable Authentication

Local Development

Cloud Deployment

Create Webhooks

​Prerequisites

​Installing Docker

​Quick Start - Get Running in 4 Steps

​What Just Happened?

​Production Deployment

​Common Commands

Start Services

Stop Services

View Logs

Restart

​More Useful Commands

​Accessing Containers

​Troubleshooting

​Why Docker is the Best Option

​Next Steps

Enable Authentication

Local Development

Cloud Deployment

Create Webhooks

Prerequisites

Installing Docker

Quick Start - Get Running in 4 Steps

What Just Happened?

Production Deployment

Common Commands

More Useful Commands

Accessing Containers

Troubleshooting

Why Docker is the Best Option

Next Steps