Skip to main content
One command sets up MongoDB, Redis, and the app with hot-reloading:
Visit http://localhost:8000. The app auto-reloads on file changes via the volume mount.
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:

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

Edit .env to point to your local MongoDB and Redis:

​
Running the Server

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

Check that all containers are running:
If the db container is unhealthy, check its logs:
Make sure you’re using uv run to execute commands — it activates the virtual environment automatically:
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.