276 lines
10 KiB
Markdown
276 lines
10 KiB
Markdown
# RustPad
|
|
|
|
RustPad is a collaborative Markdown editor with standalone notes and workspaces.
|
|
|
|
## Development setup
|
|
|
|
```bash
|
|
./dev.sh
|
|
```
|
|
|
|
The script creates `data/db` and `data/files`, builds the project, and starts it with Cargo. If Cargo is unavailable, it runs `docker compose up --build` instead.
|
|
|
|
## Workspace features
|
|
|
|
- Real-time collaborative editing over WebSocket.
|
|
- Nicknames stored in `localStorage`.
|
|
- Change authors shown in history.
|
|
- Line numbering enabled by default, with a persistent toggle.
|
|
- Owner color displayed next to each line.
|
|
- Image and file uploads to `data/files/pads/<id>_<token>/` or `data/files/notes/<id>_<token>/`.
|
|
- Automatic Markdown link insertion after upload.
|
|
- Markdown and Mermaid diagram rendering.
|
|
- History with snippets, previews, and version restore.
|
|
- Alert blocks: `success`, `info`, `warning`, and `danger`.
|
|
- Table of contents generated with `[TOC]`.
|
|
- Optional line numbers in fenced code blocks.
|
|
|
|
## Fenced code blocks and language aliases
|
|
|
|
RustPad recognizes common language names and aliases, including:
|
|
|
|
- JavaScript: `js`, `javascript`, `jsx`
|
|
- TypeScript: `ts`, `typescript`, `tsx`
|
|
- Python: `py`, `python`
|
|
- PHP: `php`
|
|
- Rust: `rs`, `rust`
|
|
- Shell: `sh`, `shell`, `bash`, `zsh`
|
|
- C and C++: `c`, `h`, `cpp`, `c++`, `cxx`, `hpp`
|
|
- C#: `cs`, `c#`, `csharp`
|
|
- Java, Kotlin, Go, Swift, Dart, Scala
|
|
- HTML, XML, SVG, CSS, SCSS, Sass, Less
|
|
- JSON, YAML, TOML, INI, SQL, GraphQL
|
|
- Markdown, Dockerfile, Makefile, PowerShell
|
|
- Lua, Perl, R, MATLAB, Nginx, Apache, Diff, and plain text
|
|
|
|
Standard code block:
|
|
|
|
````markdown
|
|
```python
|
|
print("Hello")
|
|
```
|
|
````
|
|
|
|
Code block with line numbers starting from line 1:
|
|
|
|
````markdown
|
|
```python=
|
|
print("Hello")
|
|
```
|
|
````
|
|
|
|
Code block with line numbers starting from a custom value:
|
|
|
|
````markdown
|
|
```python=101
|
|
print("Hello")
|
|
```
|
|
````
|
|
|
|
The `=number` suffix is a RustPad extension and may not be supported by other Markdown renderers.
|
|
|
|
## Data
|
|
|
|
- SQLite database: `data/db/rustpad.db`
|
|
- Attachments: `data/files/pads/<id>_<token>/` and `data/files/notes/<id>_<token>/`
|
|
- Public attachment URL: `/f/<token>/<filename>`
|
|
|
|
In Docker, both directories are located under `/data`.
|
|
|
|
## Publishing a note as a page
|
|
|
|
Use the **Page** button in the editor. RustPad creates a permanent public `/s/<token>` URL, copies it to the clipboard, and opens it in a new tab. The page displays the current note and renders Markdown, images, links, and Mermaid diagrams.
|
|
|
|
Publishing a protected note requires its password, but the generated public page itself is accessible without that password.
|
|
|
|
## Upload limit
|
|
|
|
Configure the maximum size of a single uploaded file with `UPLOAD_MAX_SIZE_MB` in `.env`, for example:
|
|
|
|
```env
|
|
UPLOAD_MAX_SIZE_MB=50
|
|
```
|
|
|
|
The default limit is 20 MB. Restart the project with `./dev.sh` after changing it.
|
|
|
|
## Database selection
|
|
|
|
RustPad selects the database engine through `DATABASE_URL`:
|
|
|
|
- SQLite: `sqlite:///data/db/rustpad.db?mode=rwc&journal_mode=WAL&busy_timeout=5000`
|
|
- PostgreSQL: `postgres://rustpad:rustpad@postgres:5432/rustpad`
|
|
- MySQL: `mysql://rustpad:rustpad@mysql:3306/rustpad`
|
|
|
|
SQLite remains the default for development and small installations. WAL mode allows reads during writes, but SQLite still performs only one write at a time. `busy_timeout=5000` waits briefly instead of immediately returning a `database is locked` error. PostgreSQL or MySQL is recommended for many concurrent editors or multiple application instances.
|
|
|
|
Optional databases in Docker Compose:
|
|
|
|
```bash
|
|
# PostgreSQL
|
|
docker compose --profile postgres up -d postgres
|
|
DATABASE_URL=postgres://rustpad:rustpad@postgres:5432/rustpad docker compose up -d rustpad
|
|
|
|
# MySQL
|
|
docker compose --profile mysql up -d mysql
|
|
DATABASE_URL=mysql://rustpad:rustpad@mysql:3306/rustpad docker compose up -d rustpad
|
|
```
|
|
|
|
Migrations are stored in `migrations/sqlite`, `migrations/postgres`, and `migrations/mysql`. Runtime SQL statements are centralized in `src/queries.rs`, while `src/database.rs` selects the driver and configures the connection.
|
|
|
|
## Optional user accounts and password reset
|
|
|
|
Nicknames can be used anonymously while they remain unregistered. Registering a nickname reserves it and requires a valid login session before it can be used in editor WebSocket connections.
|
|
|
|
Configure `PUBLIC_URL`, `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURITY`, `SMTP_USERNAME`, `SMTP_PASSWORD`, and `SMTP_FROM` to enable password-reset emails. `SMTP_FROM` accepts both `RustPad <no-reply@example.com>` and a value wrapped in one matching pair of single or double quotes, as may be passed literally by container env-file implementations. `SMTP_SECURITY` accepts `none` (plain SMTP, typically an internal relay on port 25), `starttls`, or `tls` (implicit TLS, commonly port 465). When omitted, it defaults to `tls` for port 465 and `starttls` for other ports. Reset links expire after 30 minutes and can be used only once.
|
|
|
|
## Diagnostics and logging
|
|
|
|
Server logs use `tracing`. Configure verbosity with `RUST_LOG`, for example:
|
|
|
|
```env
|
|
RUST_LOG=rustpad=debug,tower_http=info
|
|
```
|
|
|
|
Important lifecycle, database, authentication, password-reset, and WebSocket events are logged. Passwords, session tokens, reset tokens, SMTP credentials, and authorization headers are never logged.
|
|
|
|
Browser diagnostics are configured separately with `FRONTEND_LOG_LEVEL`. Supported values are `off`, `error`, `warn`, `info`, and `debug`; the default is `warn`. URL parameters cannot enable diagnostics. Use `debug` only in trusted development environments. Production should normally use `warn` or `error`.
|
|
|
|
## Registration and SMTP
|
|
|
|
Set `REGISTRATION_ENABLED=true` to enable registration. After an account is created, the application sends an SMTP message containing the nickname and `PUBLIC_URL`.
|
|
|
|
Set `ACCOUNT_CONFIRMATION_REQUIRED=true` to require users to click a confirmation link before signing in. This option is disabled by default and requires SMTP configuration.
|
|
|
|
## Attachment storage
|
|
|
|
RustPad supports two interchangeable attachment backends selected in `.env`:
|
|
|
|
- `STORAGE_DRIVER=local` stores files under `FILES_DIR` and is the default.
|
|
- `STORAGE_DRIVER=s3` uses an S3-compatible service such as AWS S3, Garage, Ceph RGW, OpenStack, or MinIO.
|
|
|
|
Public application URLs remain `/f/{token}/{filename}` for both backends. RustPad validates access and streams objects through the API, so the bucket does not need to be public and existing database records do not require migration.
|
|
|
|
For the optional Docker Garage service, configure the S3 variables shown in `.env.example`, use strong unique credentials, and run:
|
|
|
|
```sh
|
|
docker compose --profile s3 up -d --build
|
|
```
|
|
|
|
Garage runs as a separate Compose service. Existing PostgreSQL and MySQL profiles remain unchanged. The included single-node setup is intended for local or self-hosted development without redundancy. Production Garage deployments should use a properly designed multi-node configuration.
|
|
|
|
## Authentication: local, LDAP, LDAPS, or Active Directory
|
|
|
|
Choose exactly one authentication backend:
|
|
|
|
```env
|
|
AUTHORIZATION_TYPE=local
|
|
```
|
|
|
|
Supported values:
|
|
|
|
- `local` - built-in registration and password login
|
|
- `ldap` - OpenLDAP-compatible directory
|
|
- `ad` - Microsoft Active Directory defaults
|
|
|
|
For `ldap` and `ad`, RustPad searches the directory with the service account, validates the password by binding as the user, and automatically provisions a local account. Existing sessions, ownership, sharing, and other account functions continue to use the existing `users` table. Local registration and guest nickname access are disabled.
|
|
|
|
The nickname is generated as `LDAP_ORGANIZATION/displayName`, for example `example/Mateusz Testowy`. Directory accounts are stored using a stable `entryUUID` (LDAP) or `objectGUID` (AD), while e-mail, nickname, and DN are synchronized after every successful login.
|
|
|
|
### OpenLDAP
|
|
|
|
```env
|
|
AUTHORIZATION_TYPE=ldap
|
|
LDAP_URL=ldap://10.87.2.6:389
|
|
LDAP_STARTTLS=false
|
|
LDAP_BIND_DN=cn=admin,dc=example,dc=org
|
|
LDAP_BIND_PASSWORD=admin
|
|
LDAP_BASE_DN=ou=people,dc=example,dc=org
|
|
LDAP_ORGANIZATION=example
|
|
```
|
|
|
|
In `ldap` mode the defaults are:
|
|
|
|
```env
|
|
LDAP_USER_FILTER=(uid={username})
|
|
LDAP_USERNAME_ATTRIBUTE=uid
|
|
LDAP_EMAIL_ATTRIBUTE=mail
|
|
LDAP_DISPLAY_NAME_ATTRIBUTE=displayName
|
|
```
|
|
|
|
### Active Directory
|
|
|
|
```env
|
|
AUTHORIZATION_TYPE=ad
|
|
LDAP_URL=ldaps://ad.example.org:636
|
|
LDAP_STARTTLS=false
|
|
LDAP_BASE_DN=DC=example,DC=org
|
|
LDAP_BIND_DN=CN=rustpad-bind,OU=Service Accounts,DC=example,DC=org
|
|
LDAP_BIND_PASSWORD=secret
|
|
LDAP_ORGANIZATION=example
|
|
```
|
|
|
|
In `ad` mode the defaults are:
|
|
|
|
```env
|
|
LDAP_USER_FILTER=(|(sAMAccountName={username})(userPrincipalName={username}))
|
|
LDAP_USERNAME_ATTRIBUTE=sAMAccountName
|
|
LDAP_EMAIL_ATTRIBUTE=mail
|
|
LDAP_DISPLAY_NAME_ATTRIBUTE=displayName
|
|
```
|
|
|
|
All LDAP attributes and filters can still be overridden explicitly. By default TLS certificates are verified. For a trusted internal or test server using a self-signed certificate, `LDAP_TLS_VERIFY=false` keeps LDAPS/StartTLS encryption enabled without requiring a custom CA file. Do not disable verification on untrusted networks.
|
|
|
|
Additional directory options:
|
|
|
|
```env
|
|
LDAP_EXTERNAL_ID_ATTRIBUTE=entryUUID
|
|
LDAP_EMAIL_REQUIRED=true
|
|
LDAP_LINK_EXISTING_BY_EMAIL=false
|
|
LDAP_TLS_VERIFY=true
|
|
LDAP_CONNECT_TIMEOUT_SECONDS=5
|
|
LDAP_OPERATION_TIMEOUT_SECONDS=10
|
|
```
|
|
|
|
For Active Directory, the default external identifier is `objectGUID`. Set `LDAP_LINK_EXISTING_BY_EMAIL=true` only during an intentional migration of existing local or legacy LDAP accounts; otherwise an e-mail collision is rejected.
|
|
|
|
### Test LDAP on 10.87.2.6
|
|
|
|
```bash
|
|
cd docker/ldap
|
|
docker compose up -d
|
|
```
|
|
|
|
Test users:
|
|
|
|
- `admin` / `test1234`
|
|
- `user` / `test1234`
|
|
|
|
phpLDAPadmin: `http://10.0.0.1:8088`
|
|
|
|
Administrator: `cn=admin,dc=example,dc=org` / `admin`
|
|
|
|
|
|
## CLI and YAML configuration
|
|
|
|
RustPad reads `.env` as before and can additionally load a YAML file. Environment variables have higher priority than YAML values.
|
|
|
|
```bash
|
|
rustpad --version
|
|
rustpad --help
|
|
rustpad --config /etc/rustpad/rustpad.yaml check-config
|
|
rustpad --config /etc/rustpad/rustpad.yaml migrate
|
|
rustpad --config /etc/rustpad/rustpad.yaml
|
|
```
|
|
|
|
`check-config` validates YAML syntax, supported keys, value types, required LDAP/S3/SMTP fields, database URL scheme, paths and dependent settings. It does not connect to the database or LDAP server. Example deployment files are in `systemd/`.
|
|
|
|
### Database query layout
|
|
|
|
SQL is selected explicitly by database engine. Application code uses logical query identifiers from `src/queries/mod.rs`; complete engine-specific statements live in:
|
|
|
|
- `src/queries/sqlite.rs`
|
|
- `src/queries/postgres.rs`
|
|
- `src/queries/mysql.rs`
|
|
|
|
PostgreSQL statements use native `$1`, `$2`, ... placeholders. Query text is not rewritten at runtime, and result-shape casts are defined independently for each engine.
|