How to setup Bitwarden Secrets Manager for Docker Stacks

This guide covers the end-to-end setup for securing Docker stacks on a Raspberry Pi using Bitwarden Secrets Manager (BWS).

Phase 1: Bitwarden Cloud Configuration

Perform these steps in the Bitwarden Web Vault.

1. Create a Project

Projects act as the security boundary for your secrets.

Go to Secrets Manager > Projects > New Project.
Naming Convention: Use the same name as your folder in /opt/stacks (e.g., proxy-manager).

2. Create a Machine Account

This is the "Bot" identity your Raspberry Pi uses.

Go to Machine Accounts > New Machine Account.
Name: Raspberry-Pi-Dockge.
Important: Copy the Access Token immediately. You will not see it again.

3. Link Machine to Project

A Machine Account cannot see a Project unless you explicitly grant access.

Open your Project > Machine Accounts tab.
Click Add Machine Account and select Raspberry-Pi-Dockge.
Set permissions to Read Only.

4. Add Secrets

Inside the Project, click New Secret.
Key: Use uppercase (e.g., DB_PASSWORD). This is what you will use in your Docker Compose.
Value: The actual password or API key.

Phase 2: Raspberry Pi CLI Setup

Perform these steps once per Raspberry Pi.

1. Install the CLI & Dependencies

wget https://github.com/bitwarden/sdk/releases/download/bws-v1.0.0/bws-aarch64-unknown-linux-gnu-1.0.0.zip
unzip bws-aarch64-unknown-linux-gnu-1.0.0.zip
sudo mv bws /usr/local/bin/
chmod +x /usr/local/bin/bws

Bash
# Install jq (required to process Bitwarden data)
sudo apt update && sudo apt install jq unzip -y

# Download and move the BWS binary (Example for ARM64)
wget https://github.com/bitwarden/sdk/releases/download/bws-v1.0.0/bws-aarch64-unknown-linux-gnu-1.0.0.zip
unzip bws-aarch64-unknown-linux-gnu-1.0.0.zip
sudo mv bws /usr/local/bin/ && chmod +x /usr/local/bin/bws

2. Authenticate the CLI

To avoid "Missing Access Token" errors, save your token in the system profile.

nano ~/.bashrc
Add this line at the bottom: export BWS_ACCESS_TOKEN="YOUR_TOKEN_HERE"
Save/Exit (Ctrl+O, Enter, Ctrl+X) and run source ~/.bashrc.

Phase 3: Dockge & Docker Compose Configuration

Perform these steps for every new stack.

1. Update the Compose File

In the Dockge UI, replace hardcoded passwords with variables.

YAML
services:
  app:
    image: example:latest
    environment:
      PASSWORD: ${MY_SECRET_KEY} # Variable name must match Bitwarden Key

2. Find the Project ID

Run this to see which ID corresponds to your project:

bws project list

3. Generate the .env File

bws secret list<<project ID goes here>> | jq -r '.[] | "\(.key)=\(.value)"' > .env

Bash

cd /opt/stacks/your-stack-folder
bws secret list <PROJECT_ID> | jq -r '.[] | "\(.key)=\(.value)"' > .env

Phase 4: Troubleshooting & Maintenance

How to verify the setup

Hidden Files: Use ls -la to see the .env file. If you don't see it, the > redirection failed.
Empty Variables: Use cat .env. If it's empty, ensure your Machine Account has permissions to the Project in the Bitwarden Web UI.
Dockge Warnings: If Dockge says "Variable not set," it means the .env file is either in the wrong folder or named incorrectly. It must be exactly .env inside the stack folder.

Common CLI Commands

Action	Command
List Projects	`bws project list`
List Secrets	`bws secret list <PROJECT_ID>`
Check Token	`echo $BWS_ACCESS_TOKEN`

Phase 5: The "Master Sync" (Automation)

5.1. Create the Master Sync Script

We will place this script in your home directory for easy access.

Create the file:
```
nano ~/sync-stacks.sh
```

Paste the following code:

#!/bin/bash

# --- CONFIGURATION ---
# Define your stacks and their corresponding Bitwarden Project IDs
# Syntax: ["FOLDER_NAME"]="PROJECT_UUID"
declare -A STACKS=(
    ["proxy-manager"]="44444444-7778-..."
    ["home-assistant"]="YOUR-HA-PROJECT-ID"
    ["nextcloud"]="YOUR-NEXTCLOUD-PROJECT-ID"
)

# Path where Dockge stores your stacks
BASE_DIR="/opt/stacks"

echo "🔐 Starting Bitwarden Secrets Sync..."

# --- EXECUTION ---
for STACK in "${!STACKS[@]}"; do
    TARGET_DIR="$BASE_DIR/$STACK"
    PROJECT_ID="${STACKS[$STACK]}"

    if [ -d "$TARGET_DIR" ]; then
        echo "🔄 Syncing: $STACK (Project: $PROJECT_ID)"

        # Pull secrets, format to ENV, and overwrite the .env file
        bws secret list "$PROJECT_ID" | jq -r '.[] | "\(.key)=\(.value)"' > "$TARGET_DIR/.env"

        # Set secure permissions (Owner read/write only)
        chmod 600 "$TARGET_DIR/.env"

        echo "✅ Done: $STACK"
    else
        echo "⚠️  Warning: Directory $TARGET_DIR not found. Skipping."
    fi
done

echo "✨ All stacks updated successfully!"

Make it executable:
```
chmod +x ~/sync-stacks.sh
```

5.2. Running the Automation

Whenever you update a secret in the Bitwarden Web UI or add a new stack, simply run: