Skip to content
forked from laffchem/yomama

About

RESTful Web App and API for "Yo Mama" Jokes!

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Yo Mama Jokes

Yo Mama Jokes API

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

Yo Mama Jokes Screenshot


  • 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 data directory you can edit).
  • Reads from a simple jokes.csv / jokes.tsv file.

If you use The Lounge, check out the companion plugin:

TheLounge Plugin: thelounge-plugin-yomama


Public Instance

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 Requests responses.
  • For heavy or automated use, please self-host (see the Docker section below).

Features

  • 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, and http://127.0.0.1).
  • Jokes stored in jokes.csv (or jokes.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.

API Overview

  • 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 within category, 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"
    }

Running via Docker

Example docker-compose.yml

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-stopped

Usage:

mkdir -p data
docker compose up -d

On 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.

Example docker run command

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-api

Then visit: http://localhost:6262/


Running from Source

Requirements:

  • Python 3.8+
  • Git
  • A terminal and basic familiarity with virtual environments.

1. Clone the repository

git clone https://github.com/azstrait/yomama-api.git
cd yomama-api

2. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate     # on Linux/macOS

# on Windows (PowerShell):
# python -m venv .venv
# .venv\Scripts\Activate.ps1

3. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Ensure jokes data exists

By 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.

5. Run the app (development)

Use the dev runner (run.py) which enables FastAPI/Uvicorn reload:

python run.py

By 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.

6. Run tests

pytest

Environment Variables

These can be used both:

  • From source (via shell env vars before running run.py).
  • In Docker (via environment: in compose or -e in docker 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_DIR is used by both the app and the Docker entrypoint. In Docker, the entrypoint will:
    • Create ${DATA_DIR} inside the container if missing.
    • Seed jokes.csv from app/default_jokes.csv if no *.csv or *.tsv exists.
  • DOWNLOADABLE_JOKES:
    • If true, the homepage shows a “See full list here.” link and the /data/jokes endpoint returns the CSV/TSV inline.
    • If false, /data/jokes returns 404 and the link is omitted.

Releases and Docker Images

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:

  1. Run lint (Black), tests (pytest), and the jokes linter (plus optional npm linters).

  2. Build single-arch images for:

    • linux/amd64 (on ubuntu-latest)
    • linux/arm64 (on ubuntu-24.04-arm)
  3. Push the single-arch images to GHCR with the following tags:

    • ghcr.io/azstrait/yomama-api:v1-amd64
    • ghcr.io/azstrait/yomama-api:v1.2-amd64
    • ghcr.io/azstrait/yomama-api:v1.2.3-amd64
    • ghcr.io/azstrait/yomama-api:v1-arm64
    • ghcr.io/azstrait/yomama-api:v1.2-arm64
    • ghcr.io/azstrait/yomama-api:v1.2.3-arm64
  4. Create multi-arch manifests (combining amd64 and arm64) for:

    • ghcr.io/azstrait/yomama-api:v1
    • ghcr.io/azstrait/yomama-api:v1.2
    • ghcr.io/azstrait/yomama-api:v1.2.3
    • ghcr.io/azstrait/yomama-api:latest
    • ghcr.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-amd64 or v1.2.3-arm64).

You can browse all published images here:


Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on how to contribute, code style, and joke formatting rules.


Credits and References

This project is heavily inspired by and based on earlier work by:

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.


About

RESTful Web App and API for "Yo Mama" Jokes!

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages