### Setup FXA Development Launcher

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/tools/setup-test-client.md

This snippet outlines the steps to set up and run the FXA development launcher. It involves copying the launcher directory, configuring profiles, and setting environment variables like FXA_ENV, FXA_DESKTOP_CONTEXT, and FIREFOX_BIN. The command `npm run start` is used to launch the development environment.

```bash
npm run start
```

--------------------------------

### Manage Docker Compose Services with Bash

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

This guide outlines essential Docker Compose commands for managing the FxA service stack. It covers starting all services in detached mode (`up -d`), checking the status of running services (`ps`), viewing logs (`logs`), restarting individual services after configuration changes, and reloading the NGINX configuration after certificate renewals.

```bash
# Navigate to deployment directory
cd dest

# Start all services
docker compose up -d

# Check service health
docker compose ps
docker compose logs --tail=50 -f

# Restart specific service after config change
docker compose restart fxa-auth-server

# Reload NGINX after certificate renewal
docker compose exec nginx nginx -s reload

```

--------------------------------

### Database Operations: Show Databases

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

Executes a command within the MySQL container to display all available databases. This is useful for verifying database setup and connectivity.

```bash
docker compose exec mysqldb mysql -e "SHOW DATABASES;"
```

--------------------------------

### Configure Channel Server Pairing

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

This snippet defines the configuration for channel server pairing, including the WebSocket URI for the pairing server and a list of authorized client IDs. This setup is essential for enabling secure device pairing within the Firefox Accounts ecosystem.

```javascript
pairingChannelServerUri: "wss://channelserver.services.mozilla.com",
pairingClients: [ "3c49430b43dfba77", "a2270f727f45f648", "1b1a3e44c54fbb58" ],
pairing: {
  clients: {
    default: [
      '3c49430b43dfba77', // Reference browser
      'a2270f727f45f648', // Fenix
      '1b1a3e44c54fbb58', // Firefox for iOS
    ],
    doc:
      'OAuth Client IDs that are allowed to pair. Remove all clients from this list to disable pairing.',
    env: 'PAIRING_CLIENTS',
    format: Array,
  },
  server_base_uri: {
    default: 'wss://channelserver.services.mozilla.com`1',
    doc: 'The url of the Pairing channel server.',
    env: 'PAIRING_SERVER_BASE_URI',
  },
},

```

--------------------------------

### Configure and Use Local Mail Helper with Bash

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

This section details how to configure the FxA local mail helper in `config.yml` for development environments. It explains how to capture verification emails sent during testing by checking Docker logs or using the provided HTTP API endpoints to retrieve, or delete, stored emails. The example shows how to extract a verification code from a sample email format.

```bash
# Configure local mail helper in config.yml
mail:
  type: "localhelper"
  localhelper:
    web: "127.0.0.1:9001"

# After docker-compose up, check verification codes:

# Method 1: View logs
docker compose logs fxa-auth-local-mail-helper | grep -i code

# Method 2: HTTP API - Get mail for user (blocks until mail arrives)
curl http://127.0.0.1:9001/mail/username
# Response: JSON with email content including verification code

# Method 3: Delete stored mail
curl -X DELETE http://127.0.0.1:9001/mail/username

# Example verification code extraction:
# Email format: "Your verification code: 123456"

```

--------------------------------

### Initialize Docker Compose Configuration

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

This script generates the `docker-compose.yml` and other necessary configuration files for deploying the self-hosted Firefox Accounts server. It requires `config.yml` to be edited with specific domain and certificate information. The output destination can be customized using the `DEST` environment variable.

```bash
./init.sh
# or with a custom destination folder:
DEST=somefolder ./init.sh
```

--------------------------------

### Optional Firefox about:config Optimization Settings

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

These settings can be applied to Firefox's `about:config` to optimize synchronization behavior. They adjust intervals and thresholds for various sync services, potentially improving performance and responsiveness.

```ini
webextensions.storage.sync.enabled:true
services.sync.extension-storage.skipPercentageChance = 0
services.sync.scheduler.activeInterval = 10
services.sync.scheduler.fxa.singleDeviceInterval = 10
services.sync.scheduler.idleInterval = 10
services.sync.scheduler.idleTime = 10
services.sync.scheduler.immediateInterval = 10
services.sync.syncInterval = 60
services.sync.syncThreshold = 10
```

--------------------------------

### Automate ROOT CA Certificate Update with inotifywait and certutil

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/tools/setup-test-client.md

This code snippet demonstrates how to automatically update the ROOT CA certificate for a self-signed certificate in Firefox. It uses `inotifywait` to monitor for new profile creation events and `certutil` to add the root certificate to the Firefox trust store. A `sleep` command is included to ensure the profile is fully created before attempting to add the certificate.

```bash
inotifywait -m -e create . |  while read a b file; do echo "output"  $a  $b $file ; sleep 2 && certutil -A  -d  $file  -n fxaroot -t "C,,," -i <Path_to_rootCA.crt> ; done
```

--------------------------------

### Configure Android FxaClientModule Constants

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

This snippet details the constants used in the Android FxA client module. It specifies the client ID and configuration URLs for connecting to Firefox Accounts services. These values are crucial for the Android application's authentication and synchronization processes.

```java
private static final String CLIENT_ID = "7f368c6886429f19";
private static final String CONFIG_URL = "https://accounts.firefox.com";

```

--------------------------------

### Configure Android FxaClientModule Constants (JavaScript)

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

This snippet shows the JavaScript constants for the Android FxA client module, defining server URLs and client IDs for Firefox Accounts services. These are used for authentication and synchronization within the Android application.

```javascript
export const KINTO_SERVER_URL = 'https://testpilot.settings.services.mozilla.com/v1';
export const FXA_PROFILE_SERVER = 'https://profile.accounts.firefox.com/v1';
export const FXA_CONTENT_SERVER = 'https://accounts.firefox.com';
export const FXA_OAUTH_SERVER = 'https://oauth.accounts.firefox.com/v1';
export const FXA_OAUTH_CLIENT_ID = '7f368c6886429f19';

```

--------------------------------

### Modify WebExtension Background Script for Self-Hosting

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

This snippet shows modifications to the `background.js` file for a Firefox Accounts web extension. It updates server URLs and client IDs to point to a self-hosted instance, enabling custom FxA and Kinto server configurations. Dependencies include the `fxaCryptoRelier` library.

```diff
diff --git a/src/background.js b/src/background.js
index 85da9e2..0aa878e 100644
--- a/src/background.js
+++ b/src/background.js
@@ -1,8 +1,12 @@
-const KINTO_SERVER = 'https://testpilot.settings.services.mozilla.com/v1';
+var KINTO_SERVER = 'https://kinto.<your_server>/v1/';
+
+// const KINTO_SERVER = 'https://testpilot.settings.services.mozilla.com/v1';
 // XXX: Read this from Kinto fxa-params
-const FXA_CLIENT_ID = 'a3dbd8c5a6fd93e2';
-const FXA_OAUTH_SERVER = 'https://oauth.accounts.firefox.com/v1';
-const FXA_PROFILE_SERVER = 'https://profile.accounts.firefox.com/v1';
+var FXA_CLIENT_ID = 'a3dbd8c5a6fd93e2'; 
+var FXA_OAUTH_SERVER = 'https://oauth.<your_server>/v1';
+var FXA_CONTENT_SERVER = 'https://www.<your_server>';
+var FXA_PROFILE_SERVER = 'https://profile.<your_server>/v1';
+
 const FXA_SCOPES = ['profile', 'https://identity.mozilla.com/apps/notes'];
 let isEditorReady = false;
 let editorConnectedDeferred;
@@ -26,7 +30,10 @@ function fetchProfile(credentials) {
 }
 
 function authenticate() {
-  const fxaKeysUtil = new fxaCryptoRelier.OAuthUtils();
+  const fxaKeysUtil = new fxaCryptoRelier.OAuthUtils({
+    oauthServer:FXA_OAUTH_SERVER,
+    contentServer:FXA_CONTENT_SERVER
+  });
     chrome.runtime.sendMessage({
       action: 'sync-opening'
     });

```

--------------------------------

### Fenix Content Server Old Sync Redirect URI Configuration

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

Configuration for Fenix to correctly interact with the content server's old sync redirect URI. This is done by editing `contentserver-prod.json` to specify the `oauth/success/a2270f727f45f648` redirect URI.

```json
{
  "oldsync": {
    "redirecturi": "oauth/success/a2270f727f45f648"
  }
}
```

--------------------------------

### Fenix OAuth Redirect URI and Scope Configuration

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/README.md

Configuration for Fenix (Firefox for Android) to use with the self-hosted Firefox Accounts server. This involves editing `oauthserver-prod.json` to include the correct redirect URI and scope for Fenix's OAuth flow.

```json
{
  "scope": "https://identity.mozilla.com/tokens/session"
}
```

--------------------------------

### Bash Script for FxA Docker Compose Initialization (init.sh)

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

This script generates Docker Compose deployment files from templates using YTT. It should be run after any configuration changes in `config.yml`. The output is placed in the `./dest` directory.

```bash
# Basic usage - generates files in ./dest directory
./init.sh

# Custom destination directory
DEST=/path/to/deployment ./init.sh

# Output structure after running init.sh:
# dest/
# 	├── docker-compose.yml      # Generated compose file
# 	├── config.yml              # Copy of configuration
# 	└── _init/
# 	    ├── auth/
# 	    │   └── oauthserver-prod.json
# 	    ├── content/
# 	    │   └── contentserver-prod.json
# 	    ├── mysql/
# 	    │   └── init.sql
# 	    └── nginx/
# 	        └── fxa.conf

# Start the services
cd dest
docker compose up -d

# Check service status
docker compose ps

# View logs for specific service
docker compose logs fxa-auth-server
docker compose logs fxa-content-server

```

--------------------------------

### Full Cleanup Including Volumes

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

Stops all services and removes associated containers, networks, images, and volumes. Use this command for a complete reset of the FxA server environment, including persistent data.

```bash
docker compose down -v
```

--------------------------------

### Configure Custom OAuth Clients with YAML

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

This YAML configuration demonstrates how to register custom OAuth clients within the FxA `config.yml` file. It includes settings for client ID, hashed secret (generated from a plain secret using SHA256), client name, image URI, redirect URI generation, and scope permissions. Pre-configured client IDs for various Firefox clients are also provided as reference.

```yaml
# config.yml - Add custom OAuth clients
oauth:
  clients:
    - id: deadbeafdeadbeaf
      # Hex secret must be hashed with SHA256 for hashedSecret
      # Plain secret: 0b2b91549678167e4870d76e2b94024b2954cb8605e4a2e8179ab80ecf40b287
      hashedSecret: b88d5613f75ed5362ecb8c263be5b918aafbb23aac39f817eac44cbe4df7cda3
      name: SyncManager
      imageUri: ''
      # Auto-generate redirect URI from content server
      generate_redirectUri: true
      trusted: true
      canGrant: true
      publicClient: true
      # Space-separated OAuth scopes
      allowedScopes: https://identity.mozilla.com/apps/oldsync

# Pre-configured client IDs:
# Fenix (Firefox Android): a2270f727f45f648
# Firefox iOS: 1b1a3e44c54fbb58
# Reference Browser: 3c49430b43dfba77
# Firefox Desktop Sync: 5882386c6d801776
# Firefox Notes: a3dbd8c5a6fd93e2

```

--------------------------------

### View Resource Usage

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

Displays real-time resource usage (CPU, memory) for all services managed by Docker Compose. This command is helpful for monitoring performance and identifying potential bottlenecks.

```bash
docker compose stats
```

--------------------------------

### Generate Self-Signed Wildcard SSL Certificates with Bash

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

This script generates a Root Certificate Authority (CA) and a wildcard SSL certificate for *.fxa.example.local using OpenSSL. It's suitable for development or internal use where trusted certificates are not required from a public CA. The script creates a private key and a certificate signing request (CSR) with Subject Alternative Names (SAN), then signs it with the Root CA.

```bash
#!/bin/bash
# generate-cert.sh - Create self-signed certificates

# Generate Root CA
openssl genrsa -out rootCA.key 4096
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 7300 \
  -subj "/C=US/O=FxA SelfHosting/CN=FxA SelfHosting Root CA" \
  -out rootCA.crt

# Generate wildcard certificate key
openssl genrsa 2048 > wild.fxa.example.local.key

# Create certificate signing request with SAN
CNF_PATH=$(openssl version -d | sed -r "s/.*\"(.*?)\".*/\1/")
openssl req -new -sha256 \
  -key wild.fxa.example.local.key \
  -subj "/C=US/O=FxA Hosting/CN=*.fxa.example.local" \
  -reqexts SAN \
  -config <(cat $CNF_PATH/openssl.cnf \
    <(printf "\n[SAN]\nsubjectAltName=DNS:*.fxa.example.local")) \
  -out wild.fxa.example.local.csr

# Sign certificate with Root CA
openssl x509 -req \
  -extfile <(printf "subjectAltName=DNS:*.fxa.example.local") \
  -in wild.fxa.example.local.csr -sha256 -days 3650 \
  -CA rootCA.crt -CAkey rootCA.key -CAcreateserial \
  -out wild.fxa.example.local.cer

# Install rootCA.crt in browsers and system trust store

```

--------------------------------

### YAML Configuration for FxA Server (config.yml)

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

The primary configuration file for the FxA deployment. It controls domain names, SSL certificates, mail settings, and optional features like Firefox Sync and device pairing.

```yaml
# config.yml - Core configuration example
persistencepath: .

# FxA version to deploy (latest tested version)
fxa_version: "v1.316.4"

# Domain configuration - all services share base domain
domain:
  name: "fxa.example.local"
  content: "www"          # content server: www.fxa.example.local
  auth: "api"             # auth server: api.fxa.example.local
  oauth: "oauth"          # oauth server: oauth.fxa.example.local
  profile: "profile"      # profile server: profile.fxa.example.local
  sync: "token"           # sync server: token.fxa.example.local
  graphql: "graphql"      # graphql api: graphql.fxa.example.local
  channelserver: "channelserver"  # device pairing

# SSL/TLS configuration
nginx:
  listener: "443"
  ssl: true
  certs:
    wild:
      cert: "./cert/wild.cer"
      key: "./cert/wild.key"

# Email configuration
mail:
  type: "3rd"             # Options: "localhelper", "localrelay", "3rd"
  smtp_host: "smtp.example.com"
  smtp_port: 587
  smtp_user: "user@example.com"
  smtp_pass: "password"
  smtp_secure: true

# Optional features
option:
  sync:
    neverexpire: false    # Set true to keep sync items forever
  channelserver:
    enable: true          # Device pairing support
  send:
    enable: false         # Firefox Send (EOL)
  notes:
    enable: false         # Firefox Notes with Kinto

```

--------------------------------

### Upgrade FxA Version

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

Steps to upgrade the Firefox Accounts server to a new version after updating the configuration. This involves navigating to the project directory, running an initialization script, changing to the destination directory, and restarting the services.

```bash
cd /path/to/project
./init.sh
cd dest
docker compose up -d
```

--------------------------------

### Stop All Services

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

Shuts down all services defined in the Docker Compose configuration. This is a standard way to stop the FxA server environment.

```bash
docker compose down
```

--------------------------------

### Configure NGINX as a Reverse Proxy with Bash

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

This NGINX configuration sets up a reverse proxy to handle incoming SSL traffic on port 443 and forward it to the FxA internal services listening on port 8443. It includes separate server blocks for different subdomains (www, api, channelserver) and configures SSL termination using the generated wildcard certificate. WebSocket support is included for the channel server.

```nginx
# reverse_proxy.conf - NGINX reverse proxy configuration
# Assumes FxA internal nginx listens on port 8443

# Content Server
server {
    listen 443 ssl http2;
    server_name www.fxa.example.local;

    ssl_certificate /etc/ssl/wild.fxa.example.local.cer;
    ssl_certificate_key /etc/ssl/wild.fxa.example.local.key;

    location / {
        proxy_pass https://127.0.0.1:8443/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

# Auth Server
server {
    listen 443 ssl http2;
    server_name api.fxa.example.local;

    ssl_certificate /etc/ssl/wild.fxa.example.local.cer;
    ssl_certificate_key /etc/ssl/wild.fxa.example.local.key;

    location / {
        proxy_pass https://127.0.0.1:8443/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

# Channel Server (WebSocket support for device pairing)
server {
    listen 443 ssl http2;
    server_name channelserver.fxa.example.local;

    ssl_certificate /etc/ssl/wild.fxa.example.local.cer;
    ssl_certificate_key /etc/ssl/wild.fxa.example.local.key;

    location = /v1/ws/ {
        proxy_pass https://127.0.0.1:8443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

```

--------------------------------

### Firefox Browser `about:config` Settings for Self-Hosted FxA

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

These JavaScript objects represent the required and optional settings to configure the Firefox browser to use a self-hosted Firefox Accounts server. They can be applied individually or via an autoconfig URL.

```javascript
// Required Firefox about:config settings
{
  "identity.fxaccounts.auth.uri": "https://api.fxa.example.local/v1",
  "identity.fxaccounts.remote.root": "https://www.fxa.example.local/",
  "identity.fxaccounts.remote.oauth.uri": "https://oauth.fxa.example.local/v1",
  "identity.fxaccounts.remote.profile.uri": "https://profile.fxa.example.local/v1",
  "identity.sync.tokenserver.uri": "https://token.fxa.example.local/token/1.0/sync/1.5",
  "identity.fxaccounts.remote.pairing.uri": "wss://channelserver.fxa.example.local"
}

// Alternative: Use autoconfig URL (replaces all above)
{
  "identity.fxaccounts.autoconfig.uri": "https://www.fxa.example.local/"
}

// Required for webchannel communication
// Add to existing whitelist (don't replace)
{
  "webchannel.allowObject.urlWhitelist": "https://www.fxa.example.local https://accounts.firefox.com"
}

// Optional: Optimize sync frequency
{
  "webextensions.storage.sync.enabled": true,
  "services.sync.extension-storage.skipPercentageChance": 0,
  "services.sync.scheduler.activeInterval": 10,
  "services.sync.scheduler.idleInterval": 10,
  "services.sync.syncInterval": 60
}

```

--------------------------------

### Mitigate Channelserver Restart with Docker Pull

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/FAQ.md

This command pulls a specific version of the channelserver Docker image using its SHA256 hash. This is a mitigation strategy for channelserver restarts caused by glibc mismatches between the Rust version and the Debian version.

```bash
docker pull mozilla/channelserver@sha256:01f9251637cc3679b8cf31493569a79a27b41f952d4eb3d5306e1ee8d9d3feea
```

--------------------------------

### Debug and Development Settings (config.yml)

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

Configuration options within `config.yml` to enable various debug features. These settings are primarily for development and troubleshooting and should be disabled in production environments.

```yaml
debug:
  # Allow pre-verified account registration (disable in production!)
  auth_server_preverifed: false

  # Enable verbose logging for dependencies
  deps_logs: false

  # Enable end-to-end test compose file generation
  e2e_test:
    enable: false
    root_cert: /path/to/rootCA.crt

  # Required for self-signed certificates with GraphQL API
  full_self_sign_workaround: true

  # Use Python3 syncserver alternative
  use_syncserver3: false

  # Backward compatibility for older docker-compose
  keep_compose_file_version_property: false
```

--------------------------------

### Fenix (Firefox Android) Custom Server Configuration

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

Instructions for configuring Firefox for Android (Fenix) to use a self-hosted Firefox Accounts server. This is done through the 'Secret Menu' accessible via the browser's settings.

```text
# Enable Secret Menu in Fenix:
1. Settings → About Firefox
2. Tap Firefox logo 5 times
3. Return to Settings

# Configure custom servers:
Custom Firefox Account server: https://www.fxa.example.local
Custom Sync server: https://token.fxa.example.local/token/1.0/sync/1.5

```

--------------------------------

### Firefox Notes Extension Configuration

Source: https://context7.com/jackyzy823/fxa-selfhosting/llms.txt

JavaScript code snippet and YAML configuration for integrating the Firefox Notes extension with a self-hosted Kinto server. It defines server endpoints and client IDs, and enables the Notes feature in `config.yml`.

```javascript
// src/background.js - Patch for self-hosted Notes
var KINTO_SERVER = 'https://kinto.fxa.example.local/v1/';
var FXA_CLIENT_ID = 'a3dbd8c5a6fd93e2';
var FXA_OAUTH_SERVER = 'https://oauth.fxa.example.local/v1';
var FXA_CONTENT_SERVER = 'https://www.fxa.example.local';
var FXA_PROFILE_SERVER = 'https://profile.fxa.example.local/v1';
const FXA_SCOPES = ['profile', 'https://identity.mozilla.org/apps/notes'];

// Enable in config.yml
option:
  notes:
    enable: true
    settings:
      client_id:
        webext: "a3dbd8c5a6fd93e2"
        android: "7f368c6886429f19"
```

--------------------------------

### Fix Send Tabs MySQL AUTO_INCREMENT Issue

Source: https://github.com/jackyzy823/fxa-selfhosting/blob/master/FAQ.md

This snippet provides SQL commands to temporarily fix the 'Send Tabs' functionality when it fails due to MySQL's AUTO_INCREMENT not persisting after restarts. It involves updating the 'idx' column and resetting the AUTO_INCREMENT value. This is a workaround for MySQL 5.7 bugs.

```sql
UPDATE pushboxv1 SET idx = idx + <offset>;
ALTER TABLE pushboxv1 AUTO_INCREMENT = <max_id>;

-- To calculate offset:
-- SELECT <required_id> - MIN(id) FROM pushboxv1;

-- To calculate max_id:
-- SELECT MAX(id) + 1 FROM pushboxv1;
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.