> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoo.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Deployment

> The easiest way to deploy Spoo.me locally with MongoDB and Redis bundled

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!

<Info>
  **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.
</Info>

## Prerequisites

All you need:

* **Docker** and **Docker Compose** installed on your system
* That's it! MongoDB and Redis are automatically included

### Installing Docker

<Tabs>
  <Tab title="macOS">
    Download and install Docker Desktop from [docker.com](https://docker.com/get-started), or use Homebrew:

    ```bash theme={null}
    brew install --cask docker
    ```

    Start Docker Desktop and verify:

    ```bash theme={null}
    docker --version
    docker-compose --version
    ```
  </Tab>

  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows">
    Download and install Docker Desktop from [docker.com](https://docker.com/get-started)

    Verify in PowerShell:

    ```powershell theme={null}
    docker --version
    docker-compose --version
    ```
  </Tab>

  <Tab title="Other Linux">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

## Quick Start - Get Running in 4 Steps

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/spoo-me/spoo.git
    cd spoo
    ```
  </Step>

  <Step title="Create .env File">
    ```bash theme={null}
    cp .env.example .env
    ```

    That's it! The default `.env.example` works out of the box. MongoDB and Redis are automatically configured by Docker.

    <Accordion title="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](/self-hosting/setting-up-authentication) to enable Google, GitHub, or Discord login
      * **Discord Webhooks**: Follow the [webhook creation guide](/self-hosting/creating-discord-webhooks) for contact form and report notifications

      You can skip these and add them later—basic URL shortening works without them!
    </Accordion>
  </Step>

  <Step title="Start Docker Compose">
    ```bash theme={null}
    docker-compose up -d
    ```

    This single command starts everything:

    * MongoDB database
    * Redis cache
    * Spoo.me application

    <Info>
      First run takes 3-5 minutes to download images and build. Subsequent starts take only seconds!
    </Info>
  </Step>

  <Step title="Access Your Instance">
    Open your browser and visit:

    **[http://localhost:8000](http://localhost:8000)**

    <Check>
      Try shortening a URL to verify everything works!
    </Check>
  </Step>
</Steps>

## 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:

<Steps>
  <Step title="Use Cloud Database (Recommended)">
    For production, use a managed database instead of local containers:

    **In your `.env` file:**

    ```bash theme={null}
    # Replace the MongoDB URI with your cloud database
    MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/spoo-me

    # Optional: Use managed Redis (e.g., Redis Cloud, Upstash)
    REDIS_URI=redis://username:password@host:port
    ```

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

  <Step title="Update Docker Compose for Production">
    Modify `docker-compose.yml` to remove local database containers:

    ```yaml theme={null}
    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!
    ```
  </Step>

  <Step title="Add Reverse Proxy (Optional)">
    For custom domains and SSL, add Nginx:

    ```yaml theme={null}
    # 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`:**

    ```nginx theme={null}
    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;
            }
        }
    }
    ```

    <Accordion title="Adding SSL/HTTPS with Let's Encrypt">
      Use Certbot to get free SSL certificates:

      ```bash theme={null}
      # 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.
    </Accordion>
  </Step>
</Steps>

## Common Commands

<CardGroup cols={2}>
  <Card title="Start Services" icon="play">
    ```bash theme={null}
    docker-compose up -d
    ```

    Starts all containers in the background
  </Card>

  <Card title="Stop Services" icon="stop">
    ```bash theme={null}
    docker-compose down
    ```

    Stops and removes containers (data persists in volumes)
  </Card>

  <Card title="View Logs" icon="scroll">
    ```bash theme={null}
    docker-compose logs -f
    ```

    Follow logs in real-time for all services
  </Card>

  <Card title="Restart" icon="rotate">
    ```bash theme={null}
    docker-compose restart
    ```

    Restart all containers
  </Card>
</CardGroup>

### More Useful Commands

```bash theme={null}
# 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

```bash theme={null}
# Access MongoDB shell
docker-compose exec mongo mongosh

# Access application shell
docker-compose exec app bash

# View container resource usage
docker stats
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port Already in Use">
    **Error**: `Cannot start service app: Ports are not available: port is already allocated`

    **Solution**: Another service is using port 8000. Either stop that service or change the port:

    ```yaml theme={null}
    # In docker-compose.yml, change the host port:
    ports:
      - "8001:8000"  # Now access via localhost:8001
    ```
  </Accordion>

  <Accordion title="Containers Keep Restarting">
    **Cause**: Usually a configuration error in `.env`

    **Solution**: Check logs for the specific container:

    ```bash theme={null}
    docker-compose logs app
    docker-compose logs mongo
    ```

    Common issues:

    * Invalid MongoDB URI format
    * Missing required environment variables
    * Docker resource limits too low
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Docker Daemon Not Running">
    **Error**: `Cannot connect to the Docker daemon`

    **Solution**:

    ```bash theme={null}
    # Linux
    sudo systemctl start docker

    # macOS/Windows
    # Start Docker Desktop application
    ```
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Enable Authentication" icon="key" href="/self-hosting/setting-up-authentication">
    Add OAuth login for v1 API features
  </Card>

  <Card title="Local Development" icon="code" href="/self-hosting/local-development">
    Set up for code customization and development
  </Card>

  <Card title="Cloud Deployment" icon="cloud" href="/self-hosting/cloud-deployment">
    Deploy to production with managed databases
  </Card>

  <Card title="Create Webhooks" icon="webhook" href="/self-hosting/creating-discord-webhooks">
    Get notifications for contact forms and reports
  </Card>
</CardGroup>