A self-hostable RESTful web app + API for “Yo Mama” jokes, powered by FastAPI and backed by a simple CSV/TSV file.
Public Instance: https://yomama.dev
- Live website UI: lets you pick a category (or any category) and fetch jokes with a single click.
- JSON API:
/api/random,/api/random/{category}, and/api/categories. - Swagger/OpenAPI docs:
/docs. - Self-hostable via Docker (with a bind-mounted
datadirectory you can edit). - Reads from a simple
jokes.csv/jokes.tsvfile.
If you use The Lounge, check out the companion plugin:
TheLounge Plugin:
thelounge-plugin-yomama
A public instance is available at:
- Web UI:
https://yomama.dev - API base URL:
https://yomama.dev
Notes:
- The public instance is rate-limited (e.g. to about 1 request/second). If you exceed this, you may see HTTP
429 Too Many Requestsresponses. - For heavy or automated use, please self-host (see the Docker section below).
- FastAPI backend with auto-generated Swagger UI at
/docs. - Simple HTML/JS frontend at
/:- Category dropdown (or “Any category”).
- “Get Random Joke” button.
- “Copy Joke” button (only works on secure connections,
http://localhost, andhttp://127.0.0.1).
- Jokes stored in
jokes.csv(orjokes.tsv). - API responses:
GET /api/random→ random joke (any category).GET /api/random/{category}→ random joke in that category.GET /api/categories→ list of categories + count.GET /health→ health and basic stats.
- Optional link from UI to the full jokes file (CSV/TSV) if enabled.
-
GET /api/random
Returns a JSON object:{ "status": "success", "id": 42, "joke": "Yo mama is so old, her first car was a chariot.", "category": "old" } -
GET /api/random/{category}
Returns a random joke withincategory, or 404 if not found:{ "status": "failure", "message": "Category not found or has no jokes" } -
GET /api/categories
Returns all categories and a count:{ "status": "success", "categories": ["old", "fat", "ugly"], "category_count": 3 } -
GET /health
Basic health info:{ "status": "ok", "app_name": "Yo Mama Jokes API", "version": "1.0.0", "jokes_loaded": true, "joke_count": 123, "category_count": 7, "environment": "production" }
name: yomama
services:
yomama-api:
image: ghcr.io/azstrait/yomama-api:latest
container_name: yomama-api
ports:
- "6262:6262"
environment:
# the directory (inside the container) where it looks for jokes.csv
- DATA_DIR=/data
# the port the UI runs on
- PORT=6262
# Can be one of: debug, info, warning, error, critical
- LOG_LEVEL=info # case-insensitive (info/INFO/Info)
# whether to include a link to jokes.csv on the homepage
- DOWNLOADABLE_JOKES=true # case-insensitive (true/1/yes/...)
- RELOAD=true # watches jokes.csv file for changes
# and reloads the API automatically
volumes:
- ./data:/data # jokes.csv will be created here if absent
restart: unless-stoppedUsage:
mkdir -p data
docker compose up -dOn first startup, if ./data contains no .csv or .tsv, the container will seed ./data/jokes.csv from the bundled default list. You can then edit ./data/jokes.csv on the host.
By default (RELOAD=true), the container watches the jokes file (jokes.csv/jokes.tsv) for changes and will reload the app when it changes, so new jokes can be picked up live. If you'd like to disable this behavior, set RELOAD=false.
mkdir -p data
docker run -d \
--name yomama-api \
-p 6262:6262 \
-e DOWNLOADABLE_JOKES=true \
-e RELOAD=true \
-v "$(pwd)/data:/data" \
ghcr.io/azstrait/yomama-apiThen visit: http://localhost:6262/
Requirements:
- Python 3.8+
- Git
- A terminal and basic familiarity with virtual environments.
git clone https://github.com/azstrait/yomama-api.git
cd yomama-apipython3 -m venv .venv
source .venv/bin/activate # on Linux/macOS
# on Windows (PowerShell):
# python -m venv .venv
# .venv\Scripts\Activate.ps1pip install --upgrade pip
pip install -r requirements.txtBy default, the app expects a data/ directory and a jokes.csv or jokes.tsv inside it.
CSV format:
id,joke,category
1,"Yo mama so old, her first car was a chariot.","old"
2,"Yo mama so fat, when she sits around the house, she sits AROUND the house.","fat"Note
Be sure to encase jokes with double quotes so any commas contained in them don't break the CSV formatting.
Use the dev runner (run.py) which enables FastAPI/Uvicorn reload:
python run.pyBy default:
- Listens on
http://0.0.0.0:6262. (PORT=6262) - Reloads on code changes.
- Logs at
LOG_LEVEL(default:INFO). - Environment variables can be set by running them before
python run.py:LOG_LEVEL=warning python run.py
Visit:
http://localhost:6262/– Web UI.http://localhost:6262/docs– Swagger UI/API docs.
pytestThese can be used both:
- From source (via shell env vars before running
run.py). - In Docker (via
environment:in compose or-eindocker run).
| Variable | Default | Description | Possible values |
|---|---|---|---|
DATA_DIR |
/data |
Directory containing jokes.csv or jokes.tsv. In Docker, the container side of a bind mount. |
Any valid directory path. |
JOKES_CSV_FILENAME |
jokes.csv |
Name of the CSV jokes file within DATA_DIR. |
Any filename; must match actual file. |
JOKES_TSV_FILENAME |
jokes.tsv |
Name of the TSV jokes file within DATA_DIR. |
Any filename; must match actual file. |
DOWNLOADABLE_JOKES |
false |
Whether the UI and /data/jokes endpoint expose the jokes file. |
true, 1, yes, y → enabled; anything else → disabled. Case-insensitive. |
PORT |
6262 |
TCP port the app listens on. | Any valid port (e.g. 8000, 8080). |
LOG_LEVEL |
INFO |
Logging level for the app and Uvicorn. | debug, info, warning, error, critical (case-insensitive). |
RELOAD |
true (in container-run) / controlled by run.py in dev |
In container mode, controls whether Uvicorn reloads on changes to jokes file. In dev run.py, reload is always on. |
true, 1, yes, y → reload enabled; anything else → disabled. |
ENVIRONMENT |
production (currently unused but available in health) |
Optional environment label used in /health if you choose to wire it. |
e.g. development, staging, production. |
Notes:
DATA_DIRis used by both the app and the Docker entrypoint. In Docker, the entrypoint will:- Create
${DATA_DIR}inside the container if missing. - Seed
jokes.csvfromapp/default_jokes.csvif no*.csvor*.tsvexists.
- Create
DOWNLOADABLE_JOKES:- If
true, the homepage shows a “See full list here.” link and the/data/jokesendpoint returns the CSV/TSV inline. - If
false,/data/jokesreturns 404 and the link is omitted.
- If
The repository uses semantic-style version tags to drive Docker builds via GitHub Actions.
On a new version tag (e.g. v1.2.3), the “Publish” workflow will:
-
Run lint (Black), tests (pytest), and the jokes linter (plus optional npm linters).
-
Build single-arch images for:
linux/amd64(onubuntu-latest)linux/arm64(onubuntu-24.04-arm)
-
Push the single-arch images to GHCR with the following tags:
ghcr.io/azstrait/yomama-api:v1-amd64ghcr.io/azstrait/yomama-api:v1.2-amd64ghcr.io/azstrait/yomama-api:v1.2.3-amd64ghcr.io/azstrait/yomama-api:v1-arm64ghcr.io/azstrait/yomama-api:v1.2-arm64ghcr.io/azstrait/yomama-api:v1.2.3-arm64
-
Create multi-arch manifests (combining
amd64andarm64) for:ghcr.io/azstrait/yomama-api:v1ghcr.io/azstrait/yomama-api:v1.2ghcr.io/azstrait/yomama-api:v1.2.3ghcr.io/azstrait/yomama-api:latestghcr.io/azstrait/yomama-api:build-<short-commit>
This makes it easy to:
- Pin to a major series:
v1 - Pin to a minor series:
v1.2 - Pin to an exact patch:
v1.2.3 - Always follow the latest:
latest - Or explicitly choose architecture-specific tags (e.g.
v1.2.3-amd64orv1.2.3-arm64).
You can browse all published images here:
Contributions are welcome! Please see CONTRIBUTING.md for details on how to contribute, code style, and joke formatting rules.
This project is heavily inspired by and based on earlier work by:
- GitHub user: @laffchem
- Original repo: https://github.com/laffchem/yomama
- Original website: https://www.yomama-jokes.com/
This implementation reworks the architecture around FastAPI, updates the web UI, adds Docker support and CI/CD, while preserving the spirit of the original project.

