🖥️ Ad Server – FastAPI-Based Lightweight Ad Delivery System

A minimal, embeddable ad server built with FastAPI, SQLModel, and Jinja2. Ideal for use in personal blogs, micro-publisher sites, or experimental monetization projects.

---

✨ Features

✅ Embeddable ad zones (via <script src="/embed.js?zone=...">) ✅ Weighted ad rotation with click-through logging ✅ Impressions and click tracking per ad ✅ Admin panel with zone/ad management ✅ Analytics dashboard with CTR ✅ JSON stats endpoint ✅ SQLite-based (but pluggable with other DBs) ✅ Dockerized for easy deployment

---

🚀 Quickstart

1. Clone and Install

git clone https://github.com/npneykov/ad-server
cd ad-server
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

2. Create .env

ADMIN_KEY=supersecretkey
DATABASE_URL=sqlite:///./adserver.db

3. Run it

uvicorn main:app --reload

4. Access

URL	Description
/admin	Admin panel (requires header)
/render?zone=1	Render ads for iframe delivery
/embed.js?zone=1	Embeddable JS script tag
/api/stats.json	Raw stats JSON (CTR, imps, etc.)

🧪 Testing

pytest -q -v

🐳 Docker

docker build -t ad-server .
docker run --env-file=.env -p 8000:8000 ad-server

To persist the database:

docker run --env-file=.env -p 8000:8000 -v $(pwd)/adserver.db:/app/adserver.db ad-server

💡 Example Embed Snippet

Paste this on a partner/publisher site:

<script src="http://yourdomain.com/embed.js?zone=1"></script>

📜 License

This project is proprietary software owned by Nikola Neykov.

You may not use, copy, distribute, or modify any part of this software without explicit written permission.

For commercial inquiries or licensing, please contact: [email protected]

🙋‍♂️ Author

Nikola Neykov github.com/npneykov