obsidian-multi-env-setup

Obsidian Multi-Environment Setup

Overview

Configure separate development, testing, and production vaults for Obsidian plugin work. Covers vault templates for team onboarding, environment-specific plugin settings, sync strategies, and .obsidian/ directory management across environments.

Prerequisites

• Obsidian desktop app installed
• Node.js 18+ and npm/pnpm for plugin builds
• Git for version control (recommended)
• Basic understanding of symlinks and file system operations

Instructions

Step 1: Create the Environment Structure

Set up three isolated vaults -- dev, test, and prod:

# Base directory for all environments
mkdir -p ~/obsidian-envs/{dev,test,prod}

# Dev vault: your working vault with symlinked plugin source
mkdir -p ~/obsidian-envs/dev/.obsidian/plugins/your-plugin
mkdir -p ~/obsidian-envs/dev/sandbox  # scratch notes for testing

# Test vault: clean environment for QA
mkdir -p ~/obsidian-envs/test/.obsidian/plugins/your-plugin
mkdir -p ~/obsidian-envs/test/test-data

# Prod vault: mirrors real user setup
mkdir -p ~/obsidian-envs/prod/.obsidian/plugins/your-plugin

Step 2: Symlink Plugin Source for Development

In the dev vault, symlink your plugin's build output so changes appear immediately:

# Remove the empty plugin directory in dev
rm -rf ~/obsidian-envs/dev/.obsidian/plugins/your-plugin

# Symlink to your plugin's repo (contains manifest.json, main.js, styles.css)
ln -s /path/to/your-plugin ~/obsidian-envs/dev/.obsidian/plugins/your-plugin

For hot reload during development, use the Hot Reload plugin:

# Clone hot-reload into dev vault's plugins
git clone https://github.com/pjeby/hot-reload.git \
  ~/obsidian-envs/dev/.obsidian/plugins/hot-reload

Then enable both your plugin and hot-reload in .obsidian/community-plugins.json:

["your-plugin", "hot-reload"]

Step 3: Environment-Specific Plugin Settings

Each vault gets its own data.json for your plugin. Create a config factory:

// config/environments.ts
interface PluginConfig {
  debugMode: boolean;
  logLevel: 'debug' | 'info' | 'warn' | 'error';
  apiEndpoint: string;
  featureFlags: Record<string, boolean>;
}

const ENV_CONFIGS: Record<string, Partial<PluginConfig>> = {
  dev: {
    debugMode: true,
    logLevel: 'debug',
    apiEndpoint: 'http://localhost:3000',
    featureFlags: { experimentalEditor: true, betaSync: true },
  },
  test: {
    debugMode: true,
    logLevel: 'info',
    apiEndpoint: 'https://staging.api.example.com',
    featureFlags: { experimentalEditor: true, betaSync: false },
  },
  prod: {
    debugMode: false,
    logLevel: 'error',
    apiEndpoint: 'https://api.example.com',
    featureFlags: {},
  },
};

export function detectEnvironment(vaultPath: string): string {
  if (vaultPath.includes('obsidian-envs/dev')) return 'dev';
  if (vaultPath.includes('obsidian-envs/test')) return 'test';
  return 'prod';
}

export function getConfig(env: string): PluginConfig {
  const defaults: PluginConfig = {
    debugMode: false,
    logLevel: 'error',
    apiEndpoint: '',
    featureFlags: {},
  };
  return { ...defaults, ...ENV_CONFIGS[env] };
}

Use it in your plugin's onload():

async onload() {
  const vaultPath = (this.app.vault.adapter as any).basePath;
  const env = detectEnvironment(vaultPath);
  const config = getConfig(env);
  console.log(`[your-plugin] Running in ${env} mode`);

  if (config.debugMode) {
    // Register debug commands only in dev/test
    this.addCommand({
      id: 'dump-state',
      name: 'Dump Plugin State (debug)',
      callback: () => console.log(JSON.stringify(this.settings, null, 2)),
    });
  }
}

Step 4: Vault Templates for Team Onboarding

Create a template vault that new team members clone:

vault-template/
  .obsidian/
    app.json              # Standard app settings
    appearance.json       # Theme and font settings
    hotkeys.json          # Team-standard keybindings
    community-plugins.json  # Approved plugin list
    plugins/              # Pre-configured plugin data.json files
      dataview/data.json
      templater-obsidian/data.json
  templates/              # Note templates (daily, meeting, project)
    daily.md
    meeting.md
    project-kickoff.md
  README.md               # Vault orientation guide

Script to provision a new team member's vault:

#!/bin/bash
# provision-vault.sh <username> <role>
USERNAME=$1
ROLE=${2:-editor}

VAULT_DIR=~/obsidian-team-vaults/$USERNAME
cp -r vault-template "$VAULT_DIR"

# Inject user-specific settings
cat > "$VAULT_DIR/.obsidian/plugins/rbac-plugin/data.json" <<EOF
{
  "userEmail": "${USERNAME}@company.com",
  "role": "${ROLE}"
}
EOF

echo "Vault provisioned at $VAULT_DIR for $USERNAME ($ROLE)"

Step 5: Sync Strategies

Choose based on your team's needs:

Git sync (best for plugin developers):

cd ~/obsidian-envs/prod
git init
cat > .gitignore <<'EOF'
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/cache
.trash/
EOF
git add -A && git commit -m "Initial vault state"

Pair with the Obsidian Git plugin for auto-commit/push on a schedule.

Obsidian Sync (best for non-technical teams): Configure in Settings > Sync. Selective sync lets you exclude .obsidian/plugins/ on certain devices to prevent config conflicts.

iCloud/Dropbox (simplest, most fragile): Place the vault inside the sync folder. Avoid editing on multiple devices simultaneously. .obsidian/ conflicts are common -- keep a backup.

Step 6: Managing .obsidian/ Across Environments

The .obsidian/ directory holds all configuration. Key files and their sync behavior:

Script to sync safe configs from prod to other environments:

#!/bin/bash
# sync-config.sh -- copy safe configs from prod to dev/test
SAFE_FILES="app.json appearance.json hotkeys.json"
SRC=~/obsidian-envs/prod/.obsidian

for env in dev test; do
  DST=~/obsidian-envs/$env/.obsidian
  for f in $SAFE_FILES; do
    cp "$SRC/$f" "$DST/$f" 2>/dev/null && echo "Synced $f to $env"
  done
done

Output

• Three isolated vaults (dev/test/prod) with independent plugin configurations
• Symlinked plugin source in dev vault with hot reload
• Environment detection and config switching in plugin code
• Vault template and provisioning script for team onboarding
• Sync strategy configured (Git, Obsidian Sync, or cloud)
• .obsidian/ management scripts for consistent cross-env config

Error Handling

Examples

Solo developer workflow: Dev vault symlinked to plugin repo with hot reload. Test vault gets npm run build output copied in manually for final QA. Prod vault is your daily-driver vault with the released version from BRAT or community plugins.

Team onboarding: Run provision-vault.sh alice editor to create Alice's vault from the team template. She opens it in Obsidian, and all approved plugins with team-standard settings are pre-configured.

CI testing across Obsidian versions: Create a headless test vault with your plugin installed. Use obsidian-cli or Electron automation to open the vault, run plugin commands, and verify output. Repeat for each Obsidian version in your support matrix.

Resources

• Obsidian URI Protocol
• BRAT for Beta Testing
• Hot Reload Plugin
• Obsidian Git Plugin

Next Steps

For monitoring and logging across environments, see obsidian-observability. For access control on shared vaults, see obsidian-enterprise-rbac.