aukpad/README.md

Aukpad

Simple temporary live collaboration notepad with websockets and FastAPI — pads expire automatically after a configurable retention period.

Issue tracker | Libera Chat #aukpad

• Status: Beta - expect minor changes.
• Instance/Demo: aukpad.com
• Inspired by:
  • Rustpad

The goal is to keep it simple! For feature-rich solutions please check out hedgedoc or codeMD.

---

Features

Use cases:

• shared notepad across multiple machines and users
• collaboration on the same notepage with multiple people (notes, config, etc)
• piping configs: curl -o app.conf https://aukpad.com/{pad_id}/raw → edit in aukpad → repeat

Editor:

• real-time WebSocket collaboration with cursor preservation across remote edits
• per-pad password protection (PBKDF2-SHA256), with a built-in password generator in the UI
• line numbers; Tab inserts 4 spaces
• dark / light mode (auto-detects system preference, manual toggle)
• copy-to-clipboard and "new pad" buttons, live peer count in the header

Endpoints:

• custom pad path {pad_id} (1–64 chars, [a-zA-Z0-9_-]); auto-generated IDs are 8-char [a-z0-9]
• POST / — create a pad from request body (curl-friendly, see Usage)
• GET /{pad_id}/raw — raw text (auth via ?pw=… for protected pads)
• GET /system/info — instance configuration page
• GET /health — JSON health check (200 ok / 503 degraded)
• GET /system/metrics — Prometheus metrics, disabled by default (see Monitoring)
• WebSocket /ws/{pad_id} — live collaboration

Deployment:

• optional Valkey/Redis cache for cross-restart persistence
• configurable text-size, connection, room, and retention limits
• per-IP rate limiting (pad creation + failed password attempts), reverse-proxy aware
• distroless, non-root, read-only-rootfs container image

Ideas: Check out the open feature requests

Not planned:

• accounts / RBAC

---

Usage

Creating pad with curl

curl -X POST -d "Cheers" https://aukpad.com/                  # string
curl -X POST https://aukpad.com --data-binary @- < file.txt   # file
ip -br a | curl -X POST https://aukpad.com --data-binary @-   # command output

---

Installation

Please use a reverse proxy and TLS in production!

Docker

Simple / Testing

docker run -p 127.0.0.1:8000:8000 git.uphillsecurity.com/cf7/aukpad:latest

Open 127.0.0.1:8000

Adv. example with Podman

# Create Pod
podman pod create --name aukpad-pod -p 127.0.0.1:8000:8000

# Start Valkey Container (or replace with redis)
podman run -d --name aukpad-cache \
    --replace \
    --pod aukpad-pod \
    --restart=unless-stopped \
    docker.io/valkey/valkey:7 \
    --requirepass xeZNopyIeMMncqDFPHtJQwMwIathgMWo \
    --maxmemory 2gb \
    --maxmemory-policy allkeys-lru \
    --save "" \
    --appendonly no \
    --bind 0.0.0.0 \
    --protected-mode yes

# Start aukpad Container
podman run -d --name aukpad-app \
    --replace \
    --pod aukpad-pod \
    --read-only \
    --tmpfs /tmp \
    --security-opt no-new-privileges:true \
    --cap-drop ALL \
    -e USE_VALKEY=true \
    -e VALKEY_URL=redis://:xeZNopyIeMMncqDFPHtJQwMwIathgMWo@localhost:6379 \
    -e MAX_TEXT_SIZE=5 \
    -e MAX_CONNECTIONS_PER_IP=20 \
    -e RETENTION_HOURS=72 \
    -e TRUST_PROXY=true \
    git.uphillsecurity.com/cf7/aukpad:latest

Tested only with Podman - Docker-Compose file might follows.

Enable support for web sockets in your reverse proxy of choice! - Nginx config example will be added at some point.

Environment Variables

The following environment variables can be configured:

Variable	Default	Description
USE_VALKEY	false	Enable Valkey/Redis caching. Set to true to enable
VALKEY_URL	redis://localhost:6379/0	Redis/Valkey connection URL
MAX_TEXT_SIZE	5	Maximum text size in MB (5MB default)
MAX_CONNECTIONS_PER_IP	10	Maximum concurrent connections per IP address
RETENTION_HOURS	48	How long to retain pads in hours after last access
MAX_ROOMS	10000	Maximum number of pads kept in memory; new pads are refused (WS close 1008) when full until cleanup reclaims space
TRUST_PROXY	false	If true, read the client IP from X-Forwarded-For (first entry) or X-Real-IP for per-IP rate/connection limits. Only enable when aukpad sits behind a reverse proxy that strips/sets these headers — otherwise they can be spoofed
DESCRIPTION	powered by aukpad.com	Instance description shown on info page
ENABLE_METRICS	false	Serve Prometheus metrics on /system/metrics. While false the path returns 404
METRICS_KEY	(empty)	If set, scrapes must send Authorization: Bearer <key>. Empty means no auth — only sane if the path is blocked at the reverse proxy

---

Monitoring

• /health simple healthcheck
• /system/metrics optional Prometheus endpoint

Metric	Description
aukpad_rooms	Pads currently held in memory
aukpad_rooms_active	Pads with at least one connected peer
aukpad_rooms_protected	Pads with a password set
aukpad_peers_connected	Live WebSocket peers across all pads
aukpad_peers_authenticated	Peers past authentication; a gap vs. the above means clients are stuck at the password prompt
aukpad_stored_bytes	Total UTF-8 bytes of all pad text
aukpad_pad_bytes_mean / aukpad_pad_bytes_max	Mean and largest pad size in bytes
aukpad_pad_versions	Sum of all pad version counters — a proxy for edit volume. Drops when pads are evicted, so use deriv(), not rate()
aukpad_room_idle_seconds_max	Age of the least recently used pad; shows whether cleanup is keeping up
aukpad_client_ips / aukpad_ip_connections_max	Distinct IPs connected, and the busiest single IP
aukpad_pads_created_last_hour	Rolling pad creations via POST /, all IPs
aukpad_auth_failures_recent	Failed pad passwords inside the 60s window — brute-force signal
aukpad_cache_enabled / aukpad_cache_up	Valkey configured, and answering PING right now
aukpad_cache_keys	Keys in the Valkey database (all of them, if the DB is shared)
aukpad_max_rooms, aukpad_max_text_bytes, aukpad_max_connections_per_ip, aukpad_retention_seconds	Configured limits, so alert rules can use ratios instead of hardcoded numbers
aukpad_start_time_seconds	Unix start time; uptime is time() - aukpad_start_time_seconds
aukpad_build_info	Always 1, carries DESCRIPTION as a label

---

Security

For security concerns or reports, please contact via hello a t uphillsecurity d o t com gpg.

---

License

Apache License

Version 2.0, January 2004

http://www.apache.org/licenses/

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Patent use
• ✅ Private use
• ✅ Limitations
• ❌Trademark use
• ❌Liability
• ❌Warranty