The Meme Protocol

Small self-hosted meme gallery matching the stitch_the_meme_protocol desktop mockup direction.

Run locally

npm start

The server listens on http://localhost:8080 by default.

Configuration

• PORT: HTTP port, default 8080
• HOST: bind address, default 0.0.0.0
• DATA_DIR: disk storage root, default ./data
• SITE_URL: public canonical site URL used for SEO metadata, sitemaps, feeds, llms.txt, OpenAPI servers, and API skill instructions. Production should use https://bitsforfree.com.
• SEED_DEMO_MEMES: set to false to disable generated demo memes on first boot
• ADMIN_TOKEN: secret review URL token. If omitted, one is generated at boot and printed in server logs.
• OPENAI_API_KEY: enables AI upload moderation. Without it, uploads are queued for admin review.
• OPENAI_MODERATION_MODEL: moderation vision model, default gpt-4o-mini
• TRUST_PROXY: set to true when running behind a trusted reverse proxy so upload limits use X-Forwarded-For

Uploads accept PNG and JPEG images. The server rejects files over 5 MB, any image edge over 6000px, and images over 20 million pixels. Accepted uploads are decoded, metadata-stripped, resized so the longest edge is at most 1600px, and stored as WebP. Upload caps are 5 per hour per IP, 10 per day per IP, and 100 globally per day. AI-approved uploads publish immediately; ambiguous uploads are queued for the secret admin review page; likely illegal uploads are rejected immediately.

Files are stored under sharded date/hash paths:

data/
  index/memes.jsonl
  memes/YYYY/MM/DD/aa/bb/<sha256>.<ext>
  meta/YYYY/MM/DD/aa/bb/<sha256>.json

Discovery Metadata

The app serves crawler and answer-engine metadata without adding visible page copy:

• /openapi.json
• /meme-api.skill.md
• /robots.txt
• /sitemap.xml with the home page and approved meme URLs
• /feed.json
• /llms.txt
• /site.webmanifest
• Open Graph, Twitter card, canonical, and JSON-LD metadata on /

Set SITE_URL in production so canonical and API discovery URLs use the public domain instead of an internal proxy hostname. The server loads .env at startup when present, while real environment variables still take precedence.

Public API

• GET /api/memes?page=1&pageSize=12: lists approved memes only. pageSize is capped at 48.
• GET /api/memes/<sha256>: returns public metadata for one approved meme.
• GET /media/<sha256>: returns the normalized WebP image for one approved meme.
• POST /api/memes: submits one PNG/JPEG upload as multipart/form-data with a file field named meme.

API uploads use the exact same path as the browser form: persistent IP upload quotas, file size checks, image dimension and pixel checks, metadata-stripping WebP normalization, AI moderation, and admin-review queueing. A published upload returns 201; a queued upload returns 202; moderation rejection returns 422.

Public API reads are rate-limited per IP and return 429 with Retry-After when exceeded. List and metadata responses include RateLimit-* headers and a rateLimit object.

Docker

docker build -t meme-protocol .
docker run --rm -p 8080:8080 -v meme-protocol-data:/data meme-protocol

For production, copy .env.example to .env, set real secrets, then run:

docker compose up -d --build

The included compose file binds the app to 127.0.0.1:18080 on the host so a reverse proxy can publish it without exposing the Node container directly.

Production Build Note

On the production host used for this project, npm registry downloads from inside Docker timed out unless registry.npmjs.org was pinned to a known-good IPv4 address during build. The proven build command is:

sudo docker build \
  --network=host \
  --add-host registry.npmjs.org:104.16.1.34 \
  -t meme-protocol:latest .

Then start with the already-built image:

sudo docker compose up -d --no-build

If the registry IP ever stops working, resolve and test another IPv4 address for registry.npmjs.org, then replace 104.16.1.34 in the build command.

When using a host-mounted data directory, the container writes as UID/GID 10001:10001:

sudo mkdir -p ./data
sudo chown -R 10001:10001 ./data
sudo chmod -R u+rwX,g+rwX,o-rwx ./data