Skip to main content
One command sets up MongoDB, Redis, and the app with hot-reloading: 
git clone https://github.com/spoo-me/spoo.git
cd spoo
cp .env.example .env
docker compose up -d
Visit http://localhost:8000. The app auto-reloads on file changes via the volume mount. 
docker compose logs -f app   # View logs
docker compose down           # Stop everything
The .env.example file comes pre-configured for local development — MongoDB and Redis connect to the Docker containers automatically. Auth features (OAuth, email) are disabled by default and work fine without configuration.

​
Running Tests and Linting

You’ll need uv for running tests and linting outside the container: 
pip install uv
uv sync
uv run pre-commit install     # Auto-lint on every commit
uv run pytest                  # Run test suite

​
Configuring Optional Features

The default .env.example gets you a working instance for URL shortening, redirects, and analytics. For additional features, configure these in your .env:
FeatureEnv VarsSetup Guide
JWT Auth (RSA)JWT_PRIVATE_KEY, JWT_PUBLIC_KEYAuthentication Setup
JWT Auth (HMAC)JWT_SECRETGenerate with python -c "import os; print(os.urandom(32).hex())"
Google OAuthGOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRETAuthentication Setup
GitHub OAuthGITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRETAuthentication Setup
Discord OAuthDISCORD_OAUTH_CLIENT_ID, DISCORD_OAUTH_CLIENT_SECRETAuthentication Setup
Email (Zeptomail)ZEPTO_API_TOKEN, ZEPTO_FROM_EMAILSee .env.example comments
SentrySENTRY_DSNLeave empty to disable
Discord WebhooksCONTACT_WEBHOOK, URL_REPORT_WEBHOOKCreating Webhooks
hCaptchaHCAPTCHA_SECREThcaptcha.com
All optional features degrade gracefully — the app runs fine with empty values. Configure only what you need.

​
Manual Setup (Without Docker)

If you prefer not to use Docker, you’ll need to install MongoDB and Redis yourself.

​
Prerequisites

​
Installation

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

# Install dependencies
pip install uv
uv sync
uv run pre-commit install

# Configure environment
cp .env.example .env
Edit .env to point to your local MongoDB and Redis: 
MONGODB_URI=mongodb://localhost:27017/
REDIS_URI=redis://localhost:6379

​
Running the Server

uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload
Visit http://localhost:8000. Check http://localhost:8000/health to verify MongoDB and Redis are connected.

​
Verifying Your Setup

After starting the app (via Docker or manually):
  1. Health check: curl http://localhost:8000/health — should return {"status": "healthy"}
  2. Shorten a URL: Visit the homepage and create a test short link
  3. Test redirect: Click the short link to verify it redirects
  4. Run tests: uv run pytest — all tests should pass

​
Troubleshooting

# Find what's using port 8000
lsof -i :8000    # macOS/Linux
netstat -ano | findstr :8000  # Windows

# Or change the port in docker-compose.yml
ports:
  - "8001:8000"
Check that all containers are running:
docker compose ps
If the db container is unhealthy, check its logs:
docker compose logs db
Make sure you’re using uv run to execute commands — it activates the virtual environment automatically:
uv run uvicorn main:app --reload   # correct
uvicorn main:app --reload           # may fail if venv not activated
This means MongoDB is connected but Redis isn’t. The app still works — Redis is optional for caching. Check your REDIS_URI in .env or verify Redis is running.