RustChan

A self-hosted imageboard that is easy to run, fun to manage, and built for real communities.

One binary. One data folder. Zero required runtime dependencies.
Built with Rust, powered by SQLite, and designed for people who want their own corner of the web.

What Is RustChan? · Why People Like It · New In 1.1.4 · Quick Start · Feature Tour · Setup · ChanNet · Changelog

What Is RustChan?

RustChan is self-hosted imageboard software. It lets you run your own site with boards like /b/, /tech/, or /music/, where people can post threads, reply, upload media, vote in polls, and build a community.

RustChan keeps the moving parts small. You do not need Docker, Postgres, Redis, or a stack of extra services to get a board online:

• one Rust binary
• one SQLite database
• one rustchan-data/ folder for the site's state
• one web admin panel for the day-to-day stuff

It is a compact, self-contained setup that is easy to host and easy to move.

Why People Like It

If you want...	RustChan gives you...
Something simple to host	A single binary with SQLite and bundled dependencies
Something easy to manage	A proper admin panel for boards, moderation, backups, themes, and maintenance
Something with personality	Built-in themes, custom themes, custom favicons, and board-by-board defaults
Something media-friendly	Images, video, audio, image+audio combo posts, embeds, thumbnails, and waveforms
Something resilient	Full-site backups, board backups, restore tools, scheduled saved backups, and repair tooling
Something private by default	Raw IPs are not stored or logged; hashed IPs are used instead
Something that works on small machines	Good fit for a VPS, local box, homelab, or Raspberry Pi
Something that still has toys	Polls, spoiler tags, dice, sage, poster IDs, hover previews, mobile reply tools, and more

RustChan runs as a single program and can be managed from the browser.

New In 1.1.4

Version 1.1.4 adds a full banner system:

• Global rotating board banners: upload multiple board-header banners from the admin panel, rotate them on each refresh by default, or enforce a time-based rotation interval.
• Per-board banner overrides: each board can inherit the global pool, disable banners entirely, or use one fixed board-specific override.
• Clickable banner destinations: banners can point at internal boards or internal paths directly, and optional external links are gated behind an on-site warning page.
• Home page MOTD/news banner: the home page now has its own separate banner box for announcements or important updates.
• Clean media handling: uploaded banner art is validated to the exact 468x60 aspect ratio, converted to WebP, and documented with a minimum 468x60 / recommended 936x120 workflow.

The full release history lives in CHANGELOG.md. This release focuses on polish, reliability, and day-to-day usability.

Five-Minute Quick Start

If you are building from source, the binary ends up at ./target/release/rustchan-cli.

git clone https://github.com/csd113/RustChan.git
cd RustChan
cargo build --release

./target/release/rustchan-cli admin create-admin admin "ChangeThisPasswordNow"
./target/release/rustchan-cli admin create-board b "Random" "General discussion"
./target/release/rustchan-cli admin create-board tech "Technology" "Programming and hardware"

./target/release/rustchan-cli

Then open:

• http://localhost:8080
• admin panel: http://localhost:8080/admin

On first run, RustChan creates rustchan-data/settings.toml, rustchan-data/logs/, the database, backup folders, and the rest of its runtime layout automatically.

A few helpful notes:

• HTTPS is enabled by default on https://localhost:8443 with a self-signed development certificate. Your browser will warn about it locally, which is normal.
• If you are on Windows, the binary is target/release/rustchan-cli.exe.
• If you just want to run the server on another port, use --port, like ./target/release/rustchan-cli --port 9090.

Feature Tour

Boards, posts, and community tools

• Multiple boards with per-board settings, limits, themes, and moderation controls.
• Threaded replies with globally unique post numbers.
• Catalog, archive, pagination, and full-text search.
• Polls, spoiler tags, dice rolls, sage, tripcodes, and user-editable posts.
• Draft autosave, "(You)" tracking, and cross-board quote links with hover previews.
• Optional poster IDs, greentext collapsing, video embeds, and PoW CAPTCHA on a per-board basis.
• Mobile-friendly board, thread, and reply flows with layouts that hold up well on phones.

Media

• Images: JPEG, PNG, GIF, WebP, BMP, TIFF, and SVG.
• Video: MP4 and WebM.
• Audio: MP3, OGG, FLAC, WAV, M4A, and AAC.
• Image+audio combo posts for cover-art-style music threads.
• Streaming uploads with in-flight validation so large uploads do not get buffered into RAM.
• Client-side auto-compression for oversized media before upload.
• Automatic thumbnails, audio waveforms, and video poster frames when ffmpeg is available.
• If ffmpeg is unavailable, RustChan still runs and falls back to simpler media handling.

Admin tools

• Create, delete, and reorder boards from the browser.
• Set board-level rules for media, editing, archiving, poster IDs, themes, cooldowns, and access protection.
• Upload and manage global rotating board banners, per-board banner overrides, and a dedicated home-page MOTD/news banner.
• Moderate posts, review reports, process ban appeals, ban by post, and inspect IP history.
• Manage site settings, favicons, built-in themes, and custom themes from the admin panel.
• Run full-site backups and per-board backups from the admin panel.
• Restore from uploaded backup files or from backup files already on the server.
• Schedule saved full-site backups automatically and keep only the latest copies you want.
• Run integrity checks, repair tools, and database maintenance from the admin panel.

Privacy and safety

• Argon2id password hashing for admin accounts.
• HttpOnly and SameSite=Strict sessions.
• CSRF protection with constant-time token comparison.
• Security headers, no inline JavaScript, and CSP-friendly page behavior.
• Raw IPs are never stored or logged. RustChan uses an HMAC-keyed hash instead.
• Rate limiting for reads and writes, plus replay protection for PoW nonces.
• File validation uses content type and magic bytes rather than extensions alone.
• Restore protections against zip bombs, oversized uploads, path traversal, and malformed data.

Banner Artwork

RustChan 1.1.4 includes banner slots for board pages and the home page.

• Board banners render centered under the board name/description.
• On board index pages, the banner sits above [Index] [Catalog] [Archive].
• On catalog pages, the banner sits above Sort By: and Show OP Comment:.
• Board banners never render on thread pages, archive pages, or search pages.
• The home page has its own separate banner box for MOTD/news-style announcements.

Banner upload rules:

• exact 468x60 aspect ratio
• minimum size: 468x60
• recommended size: 936x120
• uploaded banner images are converted to WebP automatically

Banner links can point to:

• internal boards such as /out/
• internal paths such as /tech/catalog
• external URLs, if enabled in site settings

When external banner links are enabled, RustChan routes users through a warning page before sending them off-site.

Built-In Themes

RustChan ships with a stack of built-in looks, and admins can add custom themes too.

Theme	Vibe
fluorogrid	Bright retro-futurist grid with loud accent colors. This is the current default.
terminal	Green CRT glow for the "I want my forum to boot up like a mainframe" crowd.
aero	Glossy blue Frutiger Aero nostalgia.
dorfic	Warm amber sci-fi terminal energy.
forest	Earthy woodland palette with calmer contrast.
chanclassic	Beige, maroon, and classic imageboard DNA.
neoncubicle	Soft office-futurist magenta and gray.

Theme selection is user-facing, site defaults are admin-controlled, and boards can have their own defaults too.

Setup And Operations

RustChan is straightforward to start and includes the tools needed for longer-term operation.

Helpful settings

settings.toml is generated automatically at rustchan-data/settings.toml. A small sample:

forum_name = "RustChan"
site_subtitle = "select board to proceed"
default_theme = "fluorogrid"

port = 8080
enable_tor_support = true
require_ffmpeg = false

auto_full_backup_interval_hours = 24
auto_full_backup_copies_to_keep = 3

[tls]
enabled = true
port = 8443

Some especially useful settings:

• default_theme: the default look for new visitors.
• enable_tor_support: built-in onion service support via Arti.
• require_ffmpeg: refuse startup if ffmpeg is missing.
• auto_full_backup_interval_hours: how often RustChan creates saved full-site backups automatically.
• auto_full_backup_copies_to_keep: how many saved full backups stay on disk after rotation.

cookie_secret is generated for you on first run. Do not casually change it later unless you intentionally want to invalidate sessions, CSRF tokens, and IP hashes.

Optional extras

• ffmpeg: strongly recommended if you want video thumbnails, WebM transcodes, and audio waveforms. See SETUP.md#install-ffmpeg.
• Tor onion service: built in via Arti. No separate tor service required. See SETUP.md#tor-onion-service.
• HTTPS / TLS: enabled locally by default with a self-signed dev cert. For production, use a manual cert or build with --features tls-acme for Let's Encrypt support. See SETUP.md#https-and-tls.
• Linux service deployment: there is a full service and reverse-proxy walkthrough in SETUP.md.

Common commands

# Start the server
./target/release/rustchan-cli

# Start the server on a different port
./target/release/rustchan-cli --port 9090

# Create and manage admins
./target/release/rustchan-cli admin create-admin admin "StrongPassword"
./target/release/rustchan-cli admin reset-password admin "NewStrongPassword"
./target/release/rustchan-cli admin list-admins

# Create and inspect boards
./target/release/rustchan-cli admin create-board b "Random" "General discussion"
./target/release/rustchan-cli admin create-board tech "Technology" "Programming and hardware"
./target/release/rustchan-cli admin list-boards

# Ban management
./target/release/rustchan-cli admin list-bans

Where the data lives

By default, RustChan keeps its runtime state in rustchan-data/ next to the binary:

rustchan-data/
├── settings.toml
├── chan.db
├── logs/
├── backups/
│   ├── full/
│   └── boards/
├── runtime/
│   ├── tls/
│   ├── tor/
│   ├── favicon/
│   └── tmp/
└── boards/

The data layout is compact and easy to back up. Copy the folder, and you have most of what matters.

ChanNet And RustWave (Optional)

Most installs will not need this section.

RustChan can also expose an optional second listener for text-only federation and RustWave integration. It is not enabled by default. Start the server with:

./target/release/rustchan-cli --chan-net

By default, that listener binds to 127.0.0.1:7070.

What it does:

• /chan/export: export posts as a ZIP snapshot
• /chan/import: import a ZIP snapshot
• /chan/refresh: pull from a remote peer
• /chan/poll: fetch only new content since a timestamp
• /chan/command: typed JSON command gateway for RustWave

Important details:

• ChanNet is text-only by design. No images or other media cross this interface.
• Payloads are ZIP archives containing structured text.
• If you are running a public instance and you do not need federation, keep the listener off or firewall it appropriately.

Under The Hood

For the technically curious, RustChan currently looks like this:

Layer	What RustChan uses
Web framework	Axum 0.8
Runtime	Tokio
Database	SQLite via rusqlite
Rendering	Rust templates in src/templates/
Media	image, EXIF handling, optional ffmpeg and ffprobe
TLS	rustls, self-signed dev certs, optional ACME or manual certs
Tor	Arti
Logging	tracing with daily file rotation
Background work	In-process worker queue

The architecture stays compact and self-contained.

Deep Dives

• SETUP.md: installation, ffmpeg, Tor, TLS, Linux service setup, reverse proxy notes, and troubleshooting
• CHANGELOG.md: full release history
• LICENSE: MIT

---

RustChan is for people who want to run their own little corner of the internet with a manageable amount of overhead.