Skip to main content
Local development provides the maximum flexibility and control over your Spoo.me deployment. This method is ideal for developers who want to customize the codebase, add new features, or thoroughly understand how the application works.
Advanced Users Only: This method requires experience with Python development, uv package manager, and server management. It’s recommended for developers comfortable with command-line tools and debugging.

​
Benefits of Local Development

✅ Full Control: Complete access to modify code, add features, and customize functionality ✅ Development Environment: Perfect for testing changes before deployment ✅ Custom Integrations: Add analytics, SEO optimizations, or third-party integrations ✅ Performance Tuning: Optimize database queries and server configuration ✅ Learning Opportunity: Understand the complete application architecture

​
Prerequisites

Before starting, ensure you have:
  • Python 3.10 or higher installed on your system
  • Git for version control
  • Basic knowledge of Python development and virtual environments
  • Basic knowledge of uv package manager
  • Completed MongoDB setup
  • Completed authentication setup (for v1 API)
  • Completed webhook creation
# Check Python version
python --version

# Check Git installation
git --version

# Install Python if needed
# Download from https://python.org/downloads

​
Setting Up the Development Environment

1

Clone the Repository

Start by cloning the Spoo.me repository to your local machine:
# Clone the repository
git clone https://github.com/spoo-me/url-shortener.git

# Navigate to the project directory
cd url-shortener

# List files to verify successful clone
ls -la
This downloads the complete source code, including all necessary configuration files and dependencies.
2

Installing Dependencies

We use uv to automatically setup the development environment and install the dependencies:
# Install uv
pip install uv

# Sync and install dependencies
uv sync
Your command prompt should now show (venv) at the beginning, indicating the virtual environment is active.
3

Configure Environment Variables

Create and configure your environment file:
# Create environment file
touch .env  # On Windows: type nul > .env

# Edit the file with your preferred editor
nano .env  # or code .env, vim .env, etc.
Add your configuration variables:
# MongoDB Configuration
MONGODB_URI=mongodb+srv://username:[email protected]/spoo-me?retryWrites=true&w=majority
MONGODB_URI_DEV=mongodb://localhost:27017/
MONGO_DB_NAME=url-shortener

# Discord Webhooks
CONTACT_WEBHOOK=https://discord.com/api/webhooks/your-contact-webhook-id/your-webhook-token
URL_REPORT_WEBHOOK=https://discord.com/api/webhooks/your-report-webhook-id/your-webhook-token

# Redis Configuration (Optional)
REDIS_URI=redis://localhost:6379
REDIS_URI_DEV=redis://localhost:6379
REDIS_TTL_SECONDS=3600

# Flask Configuration
FLASK_SECRET_KEY=your-random-secret-key-here
HOST_URI=127.0.0.1:8000
SHORTEN_API_RATE_LIMIT_PER_HOUR=100

# JWT Configuration (Required for v1 API)
JWT_ISSUER=spoo.me
JWT_AUDIENCE=spoo.me
ACCESS_TOKEN_TTL_SECONDS=3600
REFRESH_TOKEN_TTL_SECONDS=2592000
COOKIE_SECURE=false
JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour-Private-Key-Here\n-----END PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nYour-Public-Key-Here\n-----END PUBLIC KEY-----"

# Google OAuth (Optional)
GOOGLE_OAUTH_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:8000/oauth/google/callback

# GitHub OAuth (Optional)
GITHUB_OAUTH_CLIENT_ID=your-github-client-id
GITHUB_OAUTH_CLIENT_SECRET=your-github-client-secret
GITHUB_OAUTH_REDIRECT_URI=http://127.0.0.1:8000/oauth/github/callback

# Discord OAuth (Optional)
DISCORD_OAUTH_CLIENT_ID=your-discord-client-id
DISCORD_OAUTH_CLIENT_SECRET=your-discord-client-secret
DISCORD_OAUTH_REDIRECT_URI=http://127.0.0.1:8000/oauth/discord/callback

# HCaptcha (Optional)
HCAPTCHA_SECRET=your-hcaptcha-secret

# Development Settings
DEBUG=True
PORT=8000
HOST=0.0.0.0
Never commit your .env file to version control. Add it to .gitignore to prevent accidental commits.
Copy from .env.example and fill in your values:
cp .env.example .env

​
Starting the Development Server

1

Start the Application

Launch the Spoo.me development server:
# Start the server
uv run main.py
You should see output similar to:
* Running on http://0.0.0.0:8000
* Debug mode: on
* Restarting with stat
* Debugger is active!
The server runs in debug mode by default, which means it will automatically restart when you make code changes.
2

Access Your Application

Open your web browser and navigate to:
You should see the Spoo.me homepage. Test the URL shortening functionality to ensure everything is working correctly.
3

Test Core Features

Verify all functionality is working:Public Features (No Auth Required):
  1. URL Shortening: Create a test short URL via v1 API (anonymous)
  2. Analytics: Click the short URL and check public analytics
  3. Contact Form: Submit the contact form to test webhooks
  4. URL Reporting: Test the URL reporting feature
Authenticated Features (Requires Login): 5. User Login: Test OAuth login at http://localhost:8000/login 6. Dashboard Access: Verify dashboard loads at http://localhost:8000/dashboard 7. API Key Creation: Create a test API key in dashboard settings 8. URL Management: Test listing, updating, and deleting URLs via v1 API 9. Advanced Analytics: Test filtered analytics queries
Check your Discord channels to verify webhook notifications are being received.

​
Development Workflow

​
Code Structure Overview

Understanding the project structure will help you navigate and modify the code: 
── url-shortener/
    ├── main.py
    ├── blueprints/
    │   ├── api.py
    │   ├── contact.py
    │   ├── docs.py
    │   ├── limiter.py
    │   ├── redirector.py
    │   ├── seo.py
    │   ├── stats.py
    │   └── url_shortener.py
    ├── cache/
    │   ├── __init__.py
    │   ├── base_cache.py
    │   ├── cache_updates.py
    │   ├── cache_url.py
    │   ├── dual_cache.py
    │   └── redis_client.py
    ├── misc/
    │   ├── GeoLite2-Country.mmdb
    ├── static/
    │   ├── css/
    │   ├── images/
    │   └── js/
    ├── templates/
    │   ├── api.html
    │   ├── index.html
    │   ├── stats.html
    ├── utils/
    │   ├── __init__.py
    │   ├── analytics_utils.py
    │   ├── contact_utils.py
    │   ├── export_utils.py
    │   ├── general.py
    │   ├── mongo_utils.py
    │   ├── pipeline_utils.py
    │   └── url_utils.py
    └── .github/
        ├── dependabot.yml
        └── workflows/
            ├── api_test.yaml
            ├── github-ci.yaml
            └── minify.yaml

​
Making Code Changes

1

Create a Development Branch

Always work on a separate branch for new features:
# Create and switch to a new branch
git checkout -b feature/my-new-feature

# Or for bug fixes
git checkout -b fix/bug-description
2

Make Your Changes

Edit the relevant files using your preferred code editor:
# Open project in VS Code
code .

# Or use any other editor
vim main.py
nano templates/index.html
The development server automatically reloads when you save changes, so you can see updates immediately.
3

Test Your Changes

Always test your modifications thoroughly:
  1. Test in the browser
  2. Check console output for errors
  3. Verify database operations
  4. Test edge cases and error handling
# Run any custom tests you've created
python -m pytest tests/

# Or run manual tests
python test_custom_feature.py
4

Commit Your Changes

Use descriptive commit messages:
# Stage your changes
git add .

# Commit with descriptive message
git commit -m "Add custom analytics dashboard feature"

# Push to your branch
git push origin feature/my-new-feature

​
Production Deployment

When you’re ready to deploy your customized version:
1

Production Environment Setup

Create a production environment file:
# .env.production
DEBUG=False
PORT=8000
HOST=0.0.0.0
MONGODB_URI=your-production-mongodb-uri
CONTACT_WEBHOOK=your-production-webhook
URL_REPORT_WEBHOOK=your-production-report-webhook
2

Install Production Dependencies

# Install additional production packages
pip install gunicorn  # WSGI server
pip install nginx     # Reverse proxy (if needed)

# Update requirements
pip freeze > requirements.txt
3

Create Production Startup Script

Create start_production.sh:
#!/bin/bash
source venv/bin/activate
export $(cat .env.production | xargs)
gunicorn -w 4 -b 0.0.0.0:8000 main:app
Make it executable:
chmod +x start_production.sh
4

Set Up Process Management

Use a process manager like systemd or supervisord:
# /etc/systemd/system/spoo-me.service
[Unit]
Description=Spoo.me URL Shortener
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/url-shortener
ExecStart=/path/to/url-shortener/start_production.sh
Restart=always

[Install]
WantedBy=multi-user.target
Enable and start the service:
sudo systemctl enable spoo-me
sudo systemctl start spoo-me

​
Troubleshooting

Symptoms: ModuleNotFoundError or import-related errorsSolutions:
  • Ensure your virtual environment is activated
  • Verify all dependencies are installed: pip install -r requirements.txt
  • Check Python path and working directory
  • Install missing packages manually: pip install package-name
Symptoms: Cannot connect to MongoDB or database errorsSolutions:
  • Verify your MONGODB_URI in the .env file
  • Test connection with the database test script
  • Check MongoDB Atlas IP whitelist settings
  • Ensure your MongoDB cluster is running
Symptoms: Address already in use error when starting serverSolutions:
# Find process using port 8000
netstat -tulpn | grep :8000  # Linux/macOS
netstat -ano | findstr :8000  # Windows

# Kill the process
kill -9 <PID>  # Linux/macOS
taskkill /PID <PID> /F  # Windows

# Or change port in .env file
PORT=8001
Symptoms: 404 errors for CSS/JS files or template rendering errorsSolutions:
  • Verify file paths in templates match actual file locations
  • Check Flask static and template folder configuration
  • Ensure static files are in the correct directory structure
  • Clear browser cache and hard refresh

​
Contributing Back to the Project

If you’ve made improvements that could benefit others:
1

Fork the Original Repository

Create your own fork on GitHub to contribute changes back.
2

Create Feature Branches

Work on separate branches for each feature or fix.
3

Submit Pull Requests

Share your improvements with the community through pull requests.
Check the project’s contribution guidelines and code standards before submitting changes.