GitHub - rustmailer/bichon: Bichon – A lightweight, high-performance Rust email archiver with WebUI (original) (raw)

A self-hosted email archiving server built in Rust. Download emails from IMAP accounts, builds a full-text search index, and serves a REST API with an embedded WebUI. Purpose-built for long-term preservation, unified cross-account search, and programmatic access to archived email.

▶ Click to watch the demo

Note

Bichon is an archiver, not an email client. It does not send, compose, forward, or reply to emails. Its optional SMTP server is for receiving emails only.

Contents

• Features
• Quick Start
  • Docker (Recommended)
  • Docker Compose
  • Binary Installation
  • Build from Source
• Configuration Reference
  • Required Settings
  • Server & Networking
  • Logging
  • CORS
  • TLS & HTTPS
  • SMTP Server
  • Storage Paths
  • Performance Tuning
• Authentication & RBAC
• CLI Tools
• API Reference
• Import & Export
• Architecture
• Storage & Backup
• Internationalization
• Data Migration (v0.x → v1.0)
• FAQ
• Roadmap
• Contributing
• Tech Stack
• License

Features

• Multi-Account IMAP Download: Download multi-account concurrently. Supports password (PLAIN/LOGIN) and OAuth 2.0 (SASL XOAUTH2) with automatic token refresh and PKCE. SSL/TLS, STARTTLS, or plain connections with optional self-signed certificate acceptance.
• Incremental Download: UID-based delta fetching downloads only new messages after the initial download. UIDVALIDITY changes are detected and trigger automatic cache rebuilds.
• Fetch Scoping: Filter download by date range, mailbox folder limit, or specific folder names. Configurable per-account SOCKS5 proxy routing.
• Auto-Configuration: Discover IMAP server settings automatically from an email domain.
• Full-Text Search: Search across subject, body, sender, recipients, attachment properties, and more. Optimized for European languages.
• Advanced Filters: Date range, size range, attachment presence, file type, content category, and facet-based tag combinations.
• Thread Grouping: Reconstruct and view complete conversation threads across folders.
• Attachment Search: Browse and filter attachments by sender, file type, size, and other attachment properties.
• Faceted Tags: Add, remove, or overwrite tags on messages and attachments. Filter by tag combinations with real-time count updates.
• Contacts View: Extracted and deduplicated sender/recipient address book across all authorized accounts.
• Three-Layer Storage: Tantivy for full-text indexing (Zstd compression), Fjall with LZ4 for compressed blob storage, and memdb for relational metadata. All embedded — zero external dependencies.
• Content Deduplication: Identical email bodies and attachments stored once via BLAKE3 content hashing. Folder moves update metadata only.
• Dashboard Analytics: Email volume trends, top senders, storage usage breakdown, attachment statistics, and per-account activity. Scoped by user permissions.
• OpenAPI 3.0: Interactive API documentation at /api-docs (Swagger UI, ReDoc, Scalar). All endpoints documented with request/response schemas.
• Multi-User RBAC: 5 built-in roles (Admin, Manager, Member, AccountManager, AccountViewer) plus custom roles with 22 granular permissions.
• Account-Level Isolation: Grant users access to specific accounts with scoped roles. Permissions enforced at the API layer.
• CLI Import Tools: Import from EML directories, MBOX files (including Gmail variants), Thunderbird profiles, and Outlook PST files.
• CLI Export: Download account data as MBOX via bichon-cli.
• Bulk Restore: Restore emails in bulk back to their original IMAP accounts.
• Embedded SMTP Server: Receive emails directly at the gateway level. STARTTLS or TLS encryption. AUTH PLAIN/LOGIN with API token authentication.
• Admin Tooling: Password reset for locked-out admins. Non-destructive v0.3.7 to v1.0 data migration.
• API Token Management: Create, list, and revoke long-lived API tokens for programmatic access.
• SOCKS5 Proxy Management: Configure and manage proxy profiles for routing IMAP traffic per account.
• Scheduled Download: Configure per-account download schedules using cron expressions. Run syncs at specific times or intervals — for example, nightly-only or business-hours-only archiving.
• Remote Content Blocking: External images and tracking pixels embedded in emails are blocked by default. Users can selectively allow remote content to load on a per-message basis from the WebUI.
• Async Index Deduplication: Duplicate detection in the search index is performed asynchronously, reducing write latency during high-throughput ingestion.

Quick Start

Docker (Recommended)

Pull the image

docker pull rustmailer/bichon:latest

Create data directory

mkdir -p ./bichon-data

Run container

docker run -d
--name bichon
-p 15630:15630
-v $(pwd)/bichon-data:/data
--user 1000:1000
-e BICHON_ROOT_DIR=/data
-e BICHON_ENCRYPT_PASSWORD=your-secure-password-here
rustmailer/bichon:latest

Open http://localhost:15630 in your browser.

Important

Default login: username admin, password admin@bichon. Change this immediately via Settings → Profile.

Docker Compose

services: bichon: image: rustmailer/bichon:latest container_name: bichon ports: - "15630:15630" volumes: - ./bichon-data:/data user: "1000:1000" environment: BICHON_ROOT_DIR: /data BICHON_ENCRYPT_PASSWORD: your-secure-password-here BICHON_LOG_LEVEL: info

Binary Installation

Download from the Releases page:

Linux / macOS

./bichon --bichon-root-dir /path/to/data --bichon-encrypt-password your-password

Windows

.\bichon.exe --bichon-root-dir E:\bichon-data --bichon-encrypt-password your-password

--bichon-root-dir must be an absolute path. All Bichon data lives under this directory.

Build from Source

Prerequisites: Rust (latest stable), Node.js 20+, pnpm

git clone https://github.com/rustmailer/bichon.git cd bichon

Build the WebUI (required before building the server)

cd web && pnpm install && pnpm run build && cd ..

Build and run

export BICHON_ENCRYPT_PASSWORD=dev-password cargo run -- --bichon-root-dir /tmp/bichon-data

For frontend development:

cd web && pnpm run dev # Vite dev server with API proxy to Rust backend

Tip

The WebUI must be built at least once (pnpm run build) for the server to serve the frontend. In dev mode (pnpm run dev), Vite proxies API calls to the Rust server automatically.

Configuration Reference

All settings accept both CLI flags (--bichon-http-port) and environment variables (BICHON_HTTP_PORT). CLI flags take precedence over environment variables.

Required Settings

Note

If both password options are set, the direct value takes precedence over the file.

Server & Networking

Logging

CORS

Warning

If BICHON_CORS_ORIGINS is not set, all origins are allowed. If you set it, only exact matches pass. Wildcards (*) are not supported. Do not add trailing slashes. When using Docker, avoid wrapping the value in quotes.

TLS & HTTPS

SMTP Server

Storage Paths

Tip

Place BICHON_INDEX_DIR on fast SSD storage for responsive search, and BICHON_DATA_DIR on high-capacity HDD for cost-effective blob storage.

Important

Bichon does NOT support writing data directly to a network file system (NFS, CIFS/SMB, etc.). All directories — BICHON_ROOT_DIR, BICHON_DATA_DIR, and BICHON_INDEX_DIR — must reside on a local file system; otherwise, data corruption may occur.

Performance Tuning

Authentication & RBAC

Authentication

1. POST /api/login with username + password returns a JWT access token
2. All /api/v1/* endpoints require Authorization: Bearer <token>
3. Tokens expire after the configured duration (BICHON_WEBUI_TOKEN_EXPIRATION_HOURS, default 7 days)
4. Long-lived API tokens can be created via WebUI or API for programmatic access

Default Admin Account

On first start, Bichon creates a built-in admin user:

• Username: admin
• Password: admin@bichon

Important

Change the password immediately via WebUI: Settings → Profile. If locked out, use the bichon-admin CLI tool to reset it.

Built-in Roles

Permission Reference

Global permissions:

Account-scoped permissions (require ACL assignment):

Tip

Built-in role permissions are immutable. Create custom roles via WebUI (/users/roles) or API for any combination of the permissions above.

CLI Tools

bichon-cli — Import & Export

./bichon-cli --config config.toml

Creates a config.toml on first run with your server URL and API token.

All imports are processed server-side — the server handles MIME parsing, indexing, deduplication, and storage.

bichon-admin — Administration

Interactive menu with two operations:

API Reference

Interactive API documentation is available at:

All /api/v1/* endpoints require Authorization: Bearer <token>.

Import & Export

Supported Formats

All imports flow through the Bichon REST API. The server parses MIME, extracts metadata, indexes content into Tantivy, deduplicates by BLAKE3 content hash, and stores raw blobs in Fjall.

Architecture

Workspace Crates

bichon/
├── crates/
│   ├── memdb/         Embedded key-value database layer (WAL, transactions)
│   ├── core/          Library — IMAP sync, search, storage, auth, models
│   ├── server/        Binary — Poem web server + embedded WebUI (rust-embed)
│   ├── cli/           Binary — bichon-cli import/export CLI
│   └── admin/         Binary — bichon-admin password reset & migration
└── web/               React + TypeScript + Vite + ShadCN UI frontend

Three-Layer Storage

Request Layer
    REST API (Poem)  │  WebUI (React)
─────────────────────┼────────────────────
Storage Layer         │
                      │
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │    memdb     │  │   Tantivy    │  │    Fjall     │
  │  (metadata)  │  │  (full-text) │  │   (blobs)    │
  │              │  │              │  │              │
  │ • accounts   │  │ • envelope   │  │ • raw emails │
  │ • users      │  │ • attachment │  │ • attachments│
  │ • roles      │  │ • tags       │  │   LZ4 compr. │
  │ • config     │  │ • contacts   │  │              │
  │ • proxies    │  │   Zstd compr.│  │ BLAKE3 hash  │
  └──────────────┘  └──────────────┘  └──────────────┘

• memdb: Key-value metadata store. Houses accounts, users, roles, OAuth2 configs, proxy settings, and system configuration.
• Tantivy: Full-text search indices with Zstd compression support. Two separate indices: envelope (email metadata + body text) and attachment (file metadata + extracted text). Batch-committed every 1,000 documents or 60 seconds.
• Fjall: LZ4-compressed LSM tree key-value store. Two keyspaces — email_keyspace and attachments_keyspace. Content-hash addressed (BLAKE3) with insert-time deduplication. Values larger than 1 KB stored as separate files (KV separation).

IMAP Download Pipeline

Schedule tick (every 10s)
        │
        ▼
  reconcile_mailboxes()
  Compare local vs. remote
        │
   ┌────┴────┐
   ▼         ▼
UID OK    UID changed / new
(incremental)  (full rebuild)
   │         │
   ▼         ▼
fetch new   fetch all
(max+1:*)   (1:* batched)
   │         │
   └────┬────┘
        ▼
extract_envelope_and_store_it()
        │
   ┌────┼────┐
   ▼    ▼    ▼
Tantivy Fjall memdb

• Per-account background tasks managed by a global download-task singleton
• Concurrency controlled by semaphore (default: num_cpus × 2)
• Manual sync via POST /api/v1/accounts/:id/start-download; cancel with cancel-download
• Busy-check prevents overlapping manual and automatic syncs on the same account

Content Deduplication & Attachment Storage

                     ┌──────────────────────────────────────────┐
                     │              Raw EML bytes               │
                     └────────────────┬─────────────────────────┘
                                      │
                                      ▼
                     ┌──────────────────────────────────────────┐
                     │         BLAKE3 → email_content_hash      │
                     └────────────────┬─────────────────────────┘
                                      │
                                      ▼
                     ┌──────────────────────────────────────────┐
                     │          MIME parse → Message            │
                     └───────┬──────────────────┬──────────────┘
                             │                  │
                             │     ┌────────────┘
                             │     │  detach attachments
                             │     │
                             ▼     ▼
               ┌─────────────────┐   ┌──────────────────────────────┐
               │  EMAIL BODY     │   │  EACH ATTACHMENT             │
               │                 │   │                              │
               │  Replace raw    │   │  BLAKE3(decoded content)     │
               │  attachment     │   │  → attachment_content_hash   │
               │  bytes with     │   │                              │
               │  placeholder:   │   │  Store raw undecoded bytes   │
               │                 │   │  in Fjall attachments_ks     │
               │  <<BICHON_      │   │  (skip if hash exists)       │
               │   DETACH_HASH:  │   │                              │
               │   xxx>>         │   │  Extract text for indexing   │
               │                 │   │  (PDF, DOCX, etc.)           │
               └───────┬─────────┘   └──────────────┬───────────────┘
                       │                            │
                       ▼                            │
               ┌──────────────────────────────┐     │
               │  Stripped EML stored in      │     │
               │  Fjall email_keyspace        │     │
               │  keyed by email_content_hash │     │
               │  (skip if hash exists)       │     │
               └──────────────┬───────────────┘     │
                              │                     │
                              ▼                     ▼
               ┌─────────────────────────────────────────────────┐
               │           Tantivy full-text index               │
               │  envelope index · attachment index              │
               └─────────────────────────────────────────────────┘

   ═══════════════════════════════════════════════════════════════

   Dedup layers
   ┌─────────────────────────────────────────────────────────────────┐
   │ Fjall (insert-time)                                             │
   │   contains_key(hash)? → skip : store with LZ4 compression       │
   │                                                                 │
   │ Tantivy (periodic, every 12 h)                                  │
   │   Group by (account, mailbox, content_hash)                     │
   │   Keep latest ingest_at → soft-delete older copies              │
   │   Cascade-delete orphaned attachment index entries              │
   └─────────────────────────────────────────────────────────────────┘

   Reconstruction
   ┌─────────────────────────────────────────────────────────────────┐
   │ Fetch stripped EML by content_hash from Fjall                  │
   │ Find <<BICHON_DETACH_HASH:xxx>> placeholders                    │
   │ Replace each with raw attachment blob from Fjall                │
   │ Result → byte-identical original EML                            │
   └─────────────────────────────────────────────────────────────────┘

Every ingested email is hashed with BLAKE3. Attachments are detached from the MIME tree, hashed independently (decoded content), and stored as raw undecoded bytes in Fjall's attachments_keyspace. The email body is patched with hash-based placeholders and stored in email_keyspace. Both keyspaces check for existing hashes before writing — identical content is never stored twice, regardless of which account or folder it arrives in. A periodic index dedup task (every 12 hours) scans Tantivy for duplicate (account, mailbox, content_hash) tuples, keeps the most recently ingested copy, and cascade-deletes orphaned attachment entries so UID-based incremental sync remains accurate. The original EML reconstructs byte-for-byte by swapping placeholders back with their attachment blobs.

Storage & Backup

Data Directory Layout

{root}/
├── bichon-indices/         Tantivy full-text index (envelope + attachment)
├── bichon-storage/         Fjall LZ4-compressed blob store
├── memdb/                  Metadata database (accounts, users, roles, config)
├── logs/                   Server logs (when BICHON_LOG_TO_FILE=true)

Backup

Back up the entire BICHON_ROOT_DIR (and BICHON_INDEX_DIR / BICHON_DATA_DIR if overridden). All three layers must be backed up together for consistency.

Warning

Do not place BICHON_ROOT_DIR or index/data directories directly on network-mounted storage (NFS, SMB, etc.). This can cause index corruption and data loss. Always run Bichon on local storage and use rsync or similar tools to sync to remote destinations.

Example with rsync

rsync -avz /path/to/bichon-data/ backup-server:/backups/bichon/

Encryption

Stored credentials (IMAP passwords, OAuth tokens) are encrypted with AES-256-GCM via ring. The encryption key is derived from BICHON_ENCRYPT_PASSWORD.

Note

Re-encrypting stored secrets after a password change is not yet supported. If this is a required feature for your use case, please open an issue.

Internationalization

The WebUI is available in 18 languages:

Language preference and UI theme are saved to your user profile and can be changed anytime from the WebUI settings.

Data Migration (v0.3.7 → v1.x)

Bichon v1.x introduced a redesigned storage architecture:

If you ran Bichon prior to v1.x, migrate your data:

./bichon-admin

Select "Migrate Legacy v0.3.7 Storage to v1.x"

Note

The migration is non-destructive — original v0.3.7 files remain in place and are not modified. You can safely remove them manually after verifying the migration was successful.

FAQ

CORS errors when accessing the WebUI

1. Enable debug logging: BICHON_LOG_LEVEL=debug
2. Check the server logs for the incoming Origin header and configured origins
3. Ensure the browser's exact origin matches an entry in BICHON_CORS_ORIGINS (no trailing slash, no wildcards)
4. In Docker, do not quote the value: -e BICHON_CORS_ORIGINS=http://192.168.1.16:15630

"Legacy data layout detected" error on startup

Your data was created by Bichon v0.3.7 and must be migrated. Run ./bichon-admin and select the migration option.

How do I run Bichon behind a reverse proxy?

Set BICHON_BASE_URL=/bichon (or your sub-path) and configure your proxy:

nginx example

location /bichon/ { proxy_pass http://127.0.0.1:15630/; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }

Can Bichon send emails?

No. Bichon is an archiver, not an email client. The optional SMTP server receives emails only — it cannot send, forward, or reply.

What hardware does Bichon need?

• Recommended: 4+ CPU cores, 2+ GB RAM (sufficient for 10+ accounts and 200+ GB of archived data)
• Filesystem: use a mainstream Linux filesystem such as ext4 or XFS; avoid network / virtual filesystems (NFS, VirtIO-FS) for all data directories
• Indices benefit from SSD storage; blob storage can use HDD

How do I reset the admin password?

./bichon-admin

Select "Reset Admin Password"

Where can I get help?

• GitHub Issues
• Discord
• Wiki

Roadmap

• Multi-account IMAP Download (Password + OAuth2)
• Full-text search with faceted tags
• Multi-user support with RBAC and custom roles
• WebUI in 18 languages with dark/light themes
• Dashboard with analytics
• CLI import: EML, MBOX, Thunderbird, PST
• CLI export: MBOX
• Embedded SMTP server
• Data migration tooling (v0.3.7 → v1.0)
• On-demand manual download controls
• Post-download server cleanup (free remote mailbox space)
• Account-to-account email merge / migration
• MCP Server for LLM-powered email search and analysis
• S3-compatible storage backend
• Enterprise SSO (OIDC / SAML)

Contributing

Contributions of all kinds are welcome — code, bug reports, documentation, or feature suggestions.

git clone https://github.com/rustmailer/bichon.git cd bichon

Build WebUI

cd web && pnpm install && pnpm run build && cd ..

Build backend

cargo build

Run tests

cargo test

Important

Before implementing a new feature or making significant changes, please open an issue first to discuss your idea with the maintainer and ensure it aligns with the project's scope.

Feel free to open an Issue or join the Discord to discuss ideas.

Tech Stack

License

Bichon is licensed under the GNU Affero General Public License v3.0. Copyright © 2025–2026 rustmailer.com