Bichon 2.2.0

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, choose your Region, and select Launch through EC2.

Choose m5.large, your key pair, a security group as described above, and a subnet. The AMI comes with an 8 GiB root volume, and the archive lives on it (/var/lib/bichon). 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.

To launch with the AWS CLI instead, replace the values in angle brackets. This command 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}]'

Version SSH user

Bichon 2.2.0 on Ubuntu 24.04 ubuntu

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

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

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 two port 53 listeners are Ubuntu's local DNS resolver. Verify the listeners:

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

Query the status endpoint to read the Bichon version:

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 it failed, in which case the site is never published. Check systemctl status bichon-firstboot and journalctl -u bichon-firstboot.

Read the credentials file:

sudo cat /root/bichon-credentials.txt

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

# Bichon on Ubuntu 24.04 (sac AWS Marketplace image) - this instance's administrator sign-in. # Generated on this instance at first boot; unique to it and not known to sac 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>

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

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.

Once mail arrives, the dashboard shows your accounts, message and attachment counts, storage use and the busiest senders.

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.

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, such as Gmail and Outlook. Then choose the sign-in method:

• Password. Enter your IMAP password, or an app password where the provider requires one (Gmail and iCloud with two-step verification, for example).
• OAuth2. First create an OAuth2 configuration in Bichon, with the client ID from your Google Cloud or Microsoft Entra application. 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 that you import from files instead of from 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.

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.

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.

Point a DNS record at the instance. An Elastic IP keeps the address across stop and start. Then tell the instance its name:

sudo bichon-set-hostname archive.example.com

This command mints a new self-signed certificate for that name. It also 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 it keeps the name across reboots.

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 replaces them with a new self-signed pair.

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. Confirm that the services are enabled:

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, follow these steps:

• Read the release notes first, because a new release may migrate the archive format.
• Download bichon-server-<version>-x86_64-unknown-linux-gnu.tar.gz from the Bichon releases page and 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.

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.