Thunderbird Accounts

Important

Thunderbird Accounts is still in active development and is not ready for any active use.

There is codebase documentation available at https://pro-services-docs.thunderbird.net/en/latest.

This project uses uv.

Thunderbird Accounts is a Django 5.2 application. Please read up on Django before diving in.

Docker is the recommended way to run the server.

Services & Ports used

During development it's great to have these handy!

Service	Exposed Port	Remarks
postgres	5433	Accounts DB
kcpostgres	5434	Keycloak DB
redis	6380	Redis
redis	8071	Redis Insights
accounts	8087	Accounts Web
flower	5555	Celery task monitoring
vite-dev	5173	Used on Account's frontend for hot-reloading.
mailpit	8025	Mailpit Web
mailpit	1025	Mailpit SMTP
stalwart	443	Stalwart Admin
stawart	8080	Stalwart Admin
stalwart	8081	Stalwart JMAP
stalwart	143	Stalwart IMAP
stalwart	993	Stalwart IMAP TLS
stalwart	25	Stalwart SMTP
stalwart	465	Stalwart SMTP TLS

Before you begin

Make sure you have uv up and running.

Getting Started

Ensure you have uv setup and the project bootstrapped by running:

uv sync
uv run bootstrap.py

This will create a virtual environment if needed and sync the latest project dependencies to your local environment.

The project comes with some optional dependencies such as cli tools, tools for building the docs, and tools for working with our Subscription app powered by Paddle.

These can be installed be appending --extra <optional dependency> like so:

uv sync --extra cli --extra docs --extra subscription

Re-bootstrapping the project

If you find your environment in a troubled state (it happens) you can add the option --from-scratch to bootstrap like so:

uv run bootstrap.py --from-scratch

This will overwrite your local .env with the contents of .env.example, copy over a fresh copy of the stalwart config from config.toml.example to mail/etc/config.toml and delete your stalwart's internal db mail/data.

Additionally, you'll want to remove the volumes for both postgres and kcpostgres to clear accounts and keycloak's database.

OIDC / Authentication

Accounts integrates mozilla-django-oidc. Included in this repo is a basic development config for keycloak, and a keycloak environment defined in docker-compose.yml. There's nothing stopping you from using a different OIDC provider. Please refer to the package documentation and your local .env file for settings you may need to change.

Running

Once you have the project bootstrapped you'll want to actually run the project via docker:

docker compose up --build -V

(Note: If you're not attached to the docker group you may need to add sudo before the above command.)

The first boot may take a while as:

• Keycloak imports realm / user information from keycloak/data/import
• Accounts runs the required database migrations
• Accounts pulls the latest Paddle product and subscription information (if you have the Paddle setup.)

Please wait until the containers are fully booted before continuing.

Logging in

A variety of basic development admin accounts are provided to help folks boot the project and start working.

Accounts / Thunderbird Pro Dashboard

You can access the login / dashboard at http://localhost:8087/. If you are not logged in you will be taken to a keycloak login screen. You can use the following credentials to proceed:

Username: admin@example.org
Password: admin

From here you can create an email account.

The default admin user is also setup you use Django's admin panel available at http://localhost:8087/admin/.

Stalwart

Stalwart is located at http://localhost:8080/. Currently, there is a bug preventing instances connected to an external OIDC directory server from logging into the admin panel.

If you need to access the admin panel you can modify your mail/etc/config.toml and edit [storage].directory from kc to internal, and restart the docker container.

From there you can login with the following credentials:

Username: admin
Password: accounts

You generally won't need to connect to Stalwart's admin panel unless you need to verify account status or debug api calls. Make sure to change the [storage].directory key back to kc and restart the docker container when you're finished.

Keycloak

Keycloak is the auth/OIDC provider that is setup by default. Two realms are imported the default master realm and the tbpro realm.

If you like to login to Keycloak's admin interface you can access that at http://keycloak:8999/admin/master/console/ with the following credentials:

Username: admin
Password: admin

From there you can switch to the tbpro realm and access settings that will affect Account's and Stalwart's login.

Additionally, you can access a simple user management portal under the tbpro realm available at http://keycloak:8999/realms/tbpro/account. Since this within the tbpro realm you can login to any account you created for accounts including admin@example.org.

Creating additional apps

Apps are feature of django we can use to create re-usable modules with. We mostly just use them to separate out and organize components. Apps can depend on and/or require other internal apps, there's no hard rule here.

Ensure to nest all internal apps inside src/thunderbird_accounts by appending the destination path after the command:

mkdir -p src/thunderbird_accounts/<app name> && ./manage.py startapp <app name> src/thunderbird_accounts/<app name>

Once the app is created go to src/thunderbird_accounts/<app name>/apps.py and prepend thunderbird_accounts. to AuthConfig.name so it looks like thunderbird_accounts.<app name>.

Building documentation locally

Ensure you have the requirements in docs installed and run the following command in the project's root folder:

sphinx-build docs build

Running tests

Make sure that the containers are already running.

To run all tests:

docker compose exec backend uv run python manage.py test

To run tests for a specific module:

docker compose exec backend uv run manage.py test thunderbird_accounts.client.tests

Running the E2E tests

Please see the E2E tests README.

Accessing the Flower Web Interface

We run Flower to surface information about Celery tasks. This service exposes a web interface on port 5555. In development, you can access this at http://localhost:5555 after bringing services online with docker-compose. In Thunderbird's live (protected) environments, we have to create an SSH proxy through a bastion.

How to build a bastion is documented in the Pulumi config files themselves. Once you have one that allows traffic from your IP, you'll need to gather some info:

• Your bastion's public IP address ($BASTION_IP)
• The DNS address for the Flower load balancer in the environment ($FLOWER_LB_DBS)
• An available local port to forward through, let's say 8443.

Open an SSH proxy to the bastion server:

ssh -L 8443:$FLOWER_LB_DNS:443 ec2-user@$BASTION_IP

Our live environments all use TLS, so you will need to browse to https://localhost:8443/. You will have to push past an SSL certificate hostname mismatch alert, but then you will find yourself at the Flower landing page, listing Celery workers on the network.