Local Development Setup

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

Windows
macOS
Ubuntu/Debian
CentOS/RHEL

# 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

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.

Installing Dependencies

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

Windows
macOS/Linux

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

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

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.

Access Your Application

Open your web browser and navigate to:

Local access: http://localhost:8000
Network access: http://your-ip-address:8000

You should see the Spoo.me homepage. Test the URL shortening functionality to ensure everything is working correctly.

Test Core Features

Verify all functionality is working:Public Features (No Auth Required):

URL Shortening: Create a test short URL via v1 API (anonymous)
Analytics: Click the short URL and check public analytics
Contact Form: Submit the contact form to test webhooks
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

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

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.

Test Your Changes

Always test your modifications thoroughly:

Test in the browser
Check console output for errors
Verify database operations
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

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:

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

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

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

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

Import Errors

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

Database Connection Issues

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

Port Already in Use

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

Template or Static File Issues

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:

Fork the Original Repository

Create your own fork on GitHub to contribute changes back.

Create Feature Branches

Work on separate branches for each feature or fix.

Submit Pull Requests

Share your improvements with the community through pull requests.

Check the project’s contribution guidelines and code standards before submitting changes.

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

Local Development Setup

Benefits of Local Development

Prerequisites

Setting Up the Development Environment

Starting the Development Server

Development Workflow

Code Structure Overview

Making Code Changes

Production Deployment

Troubleshooting

Contributing Back to the Project

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

​Benefits of Local Development

​Prerequisites

​Setting Up the Development Environment

​Starting the Development Server

​Development Workflow

​Code Structure Overview

​Making Code Changes

​Production Deployment

​Troubleshooting

​Contributing Back to the Project

Benefits of Local Development

Prerequisites

Setting Up the Development Environment

Starting the Development Server

Development Workflow

Code Structure Overview

Making Code Changes

Production Deployment

Troubleshooting

Contributing Back to the Project