# Aukpad

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

[Issue tracker](https://git.uphillsecurity.com/cf7/aukpad/issues) | `Libera Chat #aukpad` 

- Status: Beta - expect minor changes.
- Instance/Demo: [aukpad.com](https://aukpad.com/)
- Inspired by:
    - [Rustpad](https://github.com/ekzhang/rustpad)

The goal is to keep it simple! For feature-rich solutions please check out [hedgedoc](https://github.com/hedgedoc/hedgedoc) or [codeMD](https://github.com/hackmdio/codimd).

---

## Features

**Use cases:**
- shared notepad across multiple machines
- 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
- 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](https://git.uphillsecurity.com/cf7/aukpad/issues?q=&type=all&sort=&state=open&labels=12&milestone=0&project=0&assignee=0&poster=0&archived=false)

**Not planned:**
- accounts / RBAC

---

## Usage

**Creating pad with curl**

```bash
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**

```bash
# 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 |

---

## Security

For security concerns or reports, please contact via `hello a t uphillsecurity d o t com` [gpg](https://uphillsecurity.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