Bichon 2.2.0 on AWS User Guide

Overview

This guide covers launching and using the Bichon 2.2.0 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg file sharing and sync listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

Bichon is an open source email archiving server written in Rust. It connects to your mailboxes over IMAP (password or OAuth2 sign in), downloads and keeps a compressed copy of every message and attachment, and gives you a web interface with full text search across subjects, bodies, participants and attachments, filters, conversation threads, contacts and a dashboard. You can also import EML, MBOX, Thunderbird and PST files, export to MBOX, and restore messages back to an IMAP server. It is an archiver, not a mail client: it never sends mail. Several users can share one server, each with roles and per account permissions.

The cloudimg image locks Bichon down:

• HTTPS from the first boot. nginx serves Bichon on port 443 with a certificate generated on your instance's first boot. Port 80 redirects to HTTPS, and requests for a host name the instance does not serve are dropped.
• No default password, ever. Upstream Bichon creates an administrator with a published default password the first time it starts. On this image, first boot starts Bichon on a private loopback port, changes that administrator's password to a random one unique to your instance, checks that the default no longer works, and only then publishes the site. The password is in /root/bichon-credentials.txt (root only).
• An encryption key unique to your instance. Bichon encrypts the IMAP passwords and OAuth tokens it stores with a key generated at first boot (/etc/bichon/encrypt.key). The image ships with no key, no database and no certificate.
• Bichon stays on localhost. The server listens on 127.0.0.1:15630 only, as an unprivileged bichon account that can write nothing but its own archive, and it is blocked at the kernel level from reaching the EC2 instance metadata service. It keeps normal outbound access, because it has to reach your mail servers.
• Hardened web front. nginx sets the client address itself (a forged X-Forwarded-For header is ignored), strips cross origin (CORS) headers, keeps query strings (which can carry an API token) out of its access log, and refuses cross site requests to the two pages that make Bichon contact another server.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: Bichon 2.2.0 (bichon-server, bichon-cli and bichon-admin in /usr/local/bin, the official release binaries, AGPL-3.0, community edition), nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. The licence and the exact source link are in /usr/share/doc/cloudimg/bichon/.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (Bichon must reach your IMAP servers on port 993 or 143).
• A security group that allows TCP 22 (SSH), TCP 443 (the web interface) and TCP 80 (redirects to HTTPS) from your own networks only.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick Bichon 2.2.0 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large, your key pair, a security group as above, and a subnet. The AMI brings an 8 GiB root volume and the archive lives on it (/var/lib/bichon), so raise the root volume under Configure storage to fit the mail you plan to keep: as a rough guide, allow the size of the mailboxes you archive plus a third for the search index.

With the AWS CLI (replace the values in angle brackets; this sets the root volume to 100 GiB):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=100,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=bichon}]'

Step 2: Connect to your instance

ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

First boot generates the certificate, the encryption key and the administrator password, then publishes the site. It takes about ten seconds:

systemctl is-active bichon-firstboot bichon nginx

active
active
active

Only SSH (22) and nginx (80, 443) listen on the network. Bichon (15630) listens on loopback, and the other two are Ubuntu's local DNS resolver:

sudo ss -lntp | awk 'NR>1 {print $4}' | sort -u

0.0.0.0:22
0.0.0.0:443
0.0.0.0:80
127.0.0.1:15630
127.0.0.53%lo:53
127.0.0.54:53
[::]:22
[::]:443
[::]:80

Bichon reports its version on its status endpoint:

curl -sk https://127.0.0.1/api/status | python3 -c 'import json,sys; print(json.load(sys.stdin)["version"])'

2.2.0

If nginx serves nothing, first boot has not finished (or failed, in which case the site is never published). Check systemctl status bichon-firstboot and journalctl -u bichon-firstboot.

Step 4: Get your URL and password

sudo cat /root/bichon-credentials.txt

The file is readable by root only and holds the address and this instance's administrator sign in:

# Bichon on Ubuntu 24.04 (cloudimg AWS Marketplace image) - this instance's administrator sign-in.
# Generated on this instance at first boot; unique to it and not known to cloudimg or the Bichon project.
...
BICHON_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/
bichon.admin.username=admin
bichon.admin.password=<BICHON_ADMIN_PASSWORD>

You can confirm the sign in from the instance itself. The helper signs in through nginx, checks that a wrong password and the upstream default are refused, and prints BICHON_ROUNDTRIP_OK:

sudo /usr/local/sbin/bichon-verify.sh | tail -1

BICHON_ROUNDTRIP_OK

Step 5: Sign in

Open the BICHON_URL address in your browser. The certificate is self signed until you install your own (Step 9), so the browser asks you to accept it once. Sign in as admin with the password from Step 4.

The dashboard shows your accounts, message and attachment counts, storage use and the busiest senders once mail arrives:

Change the administrator password now: open Settings, then Profile, and set a password of your own. The password in /root/bichon-credentials.txt stops working after that, so delete the file once you have stored the new password safely.

Bichon limits sign in attempts per client address: after 10 attempts it accepts one more every 10 minutes, and answers "Too many login attempts" in between. If you lock yourself out while testing, wait, or sign in from another address.

Step 6: Archive a mailbox

Open Accounts in the left bar and choose IMAP account:

Enter the email address; Bichon looks up the IMAP server settings for well known providers automatically (Gmail, Outlook and many others). Choose the sign in method:

• Password: your IMAP password, or an app password where the provider requires one (Gmail and iCloud with two step verification, for example).
• OAuth2: create an OAuth2 configuration in Bichon first, with the client ID from your Google Cloud or Microsoft Entra application, and register https://<your-host>/oauth2/callback as its redirect address. The host is the BICHON_URL name, so set your own name first (Step 9) if you want a stable address.

Pick the folders to archive and save. Bichon downloads the existing mail in the background and then keeps fetching new messages. Progress shows on the account and on the dashboard. Local accounts hold mail you import from files instead of a server: use Import to load EML, MBOX, Thunderbird or PST files from your computer (up to about 2 GB per upload through the browser).

Step 7: Search your archive

Open Search to find messages by text, sender, recipient, date, folder, tag or attachment, open a message to read it with its attachments, or download the original .eml. Use Export to produce MBOX files, and Restore to copy messages back to an IMAP account.

For scripts and integrations, create an API token in Bichon and call the REST API with Authorization: Bearer <token>; the interactive API reference is at https://<your-host>/api-docs/scalar.

Step 8: Add users

Open Users (the people icon in the left bar) to create accounts for colleagues. Bichon has built in roles and per mail account access, so you decide who can see which archives. Each user signs in with the password you set and can change it under Profile.

Step 9: Use your own host name and certificate

Point a DNS record at the instance (an Elastic IP keeps the address across stop and start), then tell the instance its name. This mints a new self signed certificate for that name, updates the nginx host rule, the cross site guard, Bichon's public address (used for OAuth2 redirects) and the address in the credentials file, and keeps the name across reboots:

sudo bichon-set-hostname archive.example.com

To use a certificate from a public authority instead, replace /etc/ssl/bichon/bichon.crt (full chain) and /etc/ssl/bichon/bichon.key (mode 0600, owned by root) with your own and run sudo systemctl reload nginx. Running bichon-set-hostname again later would replace them with a new self signed pair.

Step 10: Check persistence and updates

Every service is enabled, so Bichon returns after a reboot or a stop and start, and carries on downloading where it left off. If the public address changes, the next boot re-issues the certificate and the address for the new name (unless you set your own name in Step 9). Unattended security upgrades keep the operating system and nginx patched:

systemctl is-enabled bichon bichon-set-host nginx unattended-upgrades

enabled
enabled
enabled
enabled

Bichon itself is the official release from the project. To move to a newer release later, download bichon-server-<version>-x86_64-unknown-linux-gnu.tar.gz from the Bichon releases page, check it against the release's SHA256SUMS.txt, back up first (Step 11), replace the three files in /usr/local/bin and run sudo systemctl restart bichon. Read the release notes first: a new release may migrate the archive format.

Step 11: Back up your archive

Everything Bichon keeps is under /var/lib/bichon (metadata, search index and the compressed mail store). Back up /etc/bichon/encrypt.key with it: without that key the stored IMAP passwords and OAuth tokens cannot be decrypted. An EBS snapshot of the root volume (or AWS Backup on the instance) captures both. For a file level copy, stop Bichon briefly:

sudo systemctl stop bichon
sudo tar czf bichon-backup.tar.gz -C / var/lib/bichon etc/bichon/encrypt.key
sudo systemctl start bichon

Bichon also has its own backup and restore to S3 compatible storage or a local directory, described in the Bichon documentation.

Security notes

• No shared secret ships in the image. No password, database, encryption key or TLS key exists until your instance's first boot generates them, and the site is not published until the upstream default administrator password has been replaced and proven dead.
• Fail closed. If first boot cannot complete, nothing is published: nginx has nothing to serve and Bichon does not start.
• Bichon is confined. It listens on 127.0.0.1 only, runs as an unprivileged account that can write only /var/lib/bichon, holds no Linux capabilities, writes no core dumps and cannot read the TLS key or root's files. It is blocked from the EC2 instance metadata service, as are nginx and the first boot service.
• Cross site requests are refused for the two pages that make Bichon contact another server (the mail server autoconfiguration lookup and a live mailbox listing), so another website cannot make your browser trigger them. Bichon signs requests with a token rather than a cookie, so other pages cannot act as you either.
• Third party library advisories. Bichon 2.2.0 bundles rustls 0.23.45 and webpki-roots 1.0.9, which have low and medium severity advisories (RUSTSEC-2026-0346 to 0349, and the emSign root distrust RUSTSEC-2026-0381 to 0383) affecting outbound TLS to your mail servers. No newer Bichon release exists yet; cloudimg will publish an updated version when one does. The bundled quick-xml, zip and zstd advisories concern code paths Bichon does not use.
• Restrict 22/tcp to your management network, and 80/443 to the networks that use the archive.

Architecture summary

Support

cloudimg images come with 24/7 support. Email support@cloudimg.co.uk with your AWS account ID and the instance ID. For Bichon itself, see the Bichon project on GitHub.

Bichon is an open source project of rustmailer. cloudimg is not affiliated with or endorsed by the Bichon project or rustmailer.