Skip to main content

​
Prerequisites

Before installing Short-URL, ensure you have the following installed on your system:

​
Required Software

Python 3.11+

Short-URL requires Python 3.11 or higher. Check your version with python --version

MongoDB

MongoDB 4.0 or higher (local installation or MongoDB Atlas)

pip

Python package manager (usually included with Python)

Git

For cloning the repository

​
Check Your Python Version

python --version
# or
python3 --version
You should see output like Python 3.11.0 or higher.
Python 3.10 and below are not supported due to dependency requirements.

​
Installation Methods

1

Clone the Repository

git clone https://github.com/tanmandal/Short-URL.git
cd Short-URL
2

Install Dependencies

Install all required packages from requirements.txt:
pip install -r requirements.txt
This will install:
  • fastapi (0.119.0) - Web framework
  • motor (3.7.1) - Async MongoDB driver
  • pymongo (4.15.3) - MongoDB Python driver
  • pydantic (2.12.2) - Data validation
  • python-jose (3.5.0) - JWT token handling
  • passlib (1.7.4) - Password hashing
  • uvicorn (0.37.0) - ASGI server
  • python-dotenv (1.1.1) - Environment variable management
  • And other dependencies
3

Verify Installation

Check that FastAPI is installed correctly:
python -c "import fastapi; print(fastapi.__version__)"
Expected output: 0.119.0

​
MongoDB Setup

​
Install MongoDB Locally

sudo apt-get install mongodb
sudo systemctl start mongodb
sudo systemctl enable mongodb

​
Verify MongoDB is Running

mongosh --eval "db.adminCommand('ping')"
Expected output should include { ok: 1 }

​
Environment Configuration

1

Create .env File

Create a .env file in the project root directory:
touch .env
2

Add Required Variables

Add the following environment variables to your .env file:
# MongoDB Configuration
# For local MongoDB:
MONGO_URI=mongodb://localhost:27017
# For MongoDB Atlas:
# MONGO_URI=mongodb+srv://username:[email protected]/?retryWrites=true&w=majority

# JWT Secret Key (REQUIRED - Change this!)
# Generate a secure random string for production
SECRET_KEY=your-super-secret-key-change-this-in-production

# Token Expiration (in minutes)
# How long JWT tokens remain valid
TOKEN_EXPIRE=5

# Short URL Base
# The base URL for your short links
# For local development:
SURL_BASE=http://127.0.0.1:8000
# For production:
# SURL_BASE=https://yourdomain.com

# CORS Configuration (Optional)
# Comma-separated list of allowed origins
# Use * to allow all origins (not recommended for production)
ALLOWED_ORIGINS=*
# For production, specify exact origins:
# ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

# URL Blacklist (Optional)
# Comma-separated list of URL patterns to block
# Prevents creation of short URLs containing these strings
URL_BLACKLIST=
# Example:
# URL_BLACKLIST=spam.com,malicious.site,phishing.net
3

Generate Secure Secret Key

For production, generate a cryptographically secure secret key:
python -c "import secrets; print(secrets.token_urlsafe(32))"
Copy the output and use it as your SECRET_KEY value.
Never commit your .env file to version control! Add it to .gitignore.

​
Environment Variables Reference

VariableRequiredDefaultDescription
MONGO_URIYes-MongoDB connection string
SECRET_KEYYes-JWT token signing key (must be secure)
TOKEN_EXPIRENo5Token expiration time in minutes
SURL_BASEYes-Base URL for generated short links
ALLOWED_ORIGINSNo*CORS allowed origins (comma-separated)
URL_BLACKLISTNo""Blacklisted URL patterns (comma-separated)

​
Start the Server

1

Basic Start

Start the server with default settings:
uvicorn main:app --reload
The server will start on http://127.0.0.1:8000
2

Custom Host and Port

uvicorn main:app --host 0.0.0.0 --port 8080 --reload
3

Production Mode

For production, remove --reload and add workers:
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

​
Verify Installation

1

Check Root Endpoint

curl http://127.0.0.1:8000/
Expected Response:
{
  "message": "Welcome to URL Shortener"
}
2

Check Database Connection

curl http://127.0.0.1:8000/health
Expected Response:
{
  "message": "Database is active"
}
If this fails, check your MongoDB connection string and ensure MongoDB is running.
3

Access API Documentation

Open your browser and visit:You should see interactive API documentation.

​
Troubleshooting

Problem: FastAPI or other dependencies not installed.Solution:
pip install -r requirements.txt
If using a virtual environment, make sure it’s activated first.
Problem: Cannot connect to MongoDB.Solutions:
  1. Local MongoDB: Ensure MongoDB is running 
    sudo systemctl status mongodb  # Linux
brew services list  # macOS
  2. MongoDB Atlas:
    • Check your connection string is correct
    • Verify network access settings allow your IP
    • Confirm database user credentials are correct
  3. Check MONGO_URI format: 
    # Local:
MONGO_URI=mongodb://localhost:27017

# Atlas:
MONGO_URI=mongodb+srv://user:[email protected]/
Problem: JWT token creation or validation failing.Solution: Ensure SECRET_KEY is set in your .env file:
SECRET_KEY=your-secret-key-here
Generate a new one if needed:
python -c "import secrets; print(secrets.token_urlsafe(32))"
Problem: Port 8000 is already occupied.Solution: Use a different port:
uvicorn main:app --port 8080 --reload
Or find and kill the process using port 8000:
# Linux/macOS
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F
Problem: Cross-origin requests blocked.Solution: Update ALLOWED_ORIGINS in .env:
# Allow all (development only)
ALLOWED_ORIGINS=*

# Specific origins (production)
ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
Problem: Cannot create URL with certain codes.Solution:
  • URL codes must be 3-20 characters
  • Only alphanumeric, hyphens, and underscores allowed
  • Cannot use reserved keywords: docs, redoc, create, login, delete, pause, resume, details, refresh_token, change_password, reset_hits, change_url, validate_token, health
Valid examples: mylink, link-123, my_url_2024

​
Next Steps

Quickstart Guide

Follow the quickstart to create your first short URL

API Reference

Explore all available endpoints and features

Authentication

Learn about JWT authentication and token management

Deployment

Deploy Short-URL to production
Join the community! Star the repository on GitHub and contribute to the project.

Build docs developers (and LLMs) love

Get started for freeTalk to us