From 91e4258d81d4267a420e061623b17f5b31a08a0d Mon Sep 17 00:00:00 2001
From: Masaki Yatsu <yatsu@yatsu.info>
Date: Mon, 24 Nov 2025 11:14:08 +0900
Subject: [PATCH] docs: add troubleshooting doc

---
 README.md               | 14 +++++++
 docs/troubleshooting.md | 82 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 docs/troubleshooting.md

diff --git a/README.md b/README.md
index 0a7d67b..4a531bf 100644
--- a/README.md
+++ b/README.md
@@ -527,6 +527,20 @@ Key technologies: Next.js, Payload CMS, dlt, dbt, Iceberg, Lakekeeper, Trino, Su
 
 Both projects demonstrate the medallion architecture (raw → staging → marts) and showcase how buun-stack components work together for production data workflows.
 
+## Documentation
+
+### Troubleshooting
+
+Having issues? Check the [Troubleshooting Guide](./docs/troubleshooting.md) for solutions to common problems:
+
+### Resource Management
+
+See [Resource Management Guide](./docs/resource-management.md) for configuring CPU and memory:
+
+- QoS classes (Guaranteed vs Burstable)
+- Using Goldilocks for recommendations
+- Best practices and examples
+
 ## License
 
 MIT License - See LICENSE file for details
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..cdf8406
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,82 @@
+# Troubleshooting
+
+This document provides solutions to common issues encountered when working with buun-stack.
+
+## Table of Contents
+
+- [Vault Issues](#vault-issues)
+
+## Vault Issues
+
+### Vault is Sealed
+
+#### Symptom
+
+When running `just vault::get` or other Vault-related recipes, you encounter this error:
+
+```plain
+Error authenticating: Error making API request.
+
+URL: PUT https://vault.example.com/v1/auth/oidc/oidc/auth_url
+Code: 503. Errors:
+
+* Vault is sealed
+```
+
+#### Cause
+
+Vault automatically seals itself when:
+
+- The Vault pod is restarted
+- The node where Vault is running is restarted
+- Vault encounters certain error conditions
+
+When sealed, Vault cannot decrypt its data and all operations are blocked.
+
+#### Solution
+
+Unseal Vault using your unseal key:
+
+**Option 1: Using the Web UI**
+
+1. Navigate to your Vault host (e.g., `https://vault.example.com`)
+2. Enter your unseal key in the web interface
+3. Click "Unseal"
+
+**Option 2: Using kubectl**
+
+```bash
+# Get the unseal key from your secure storage
+UNSEAL_KEY="your-unseal-key-here"
+
+# Unseal Vault
+kubectl exec -n vault vault-0 -- vault operator unseal "${UNSEAL_KEY}"
+```
+
+#### Prevention
+
+**Important**: Store your Vault unseal key and root token securely. You will need them whenever Vault is sealed.
+
+Recommended storage locations:
+
+- Password manager (1Password, Bitwarden, etc.)
+- Secure note in your organization's secret management system
+- Encrypted file on secure storage
+
+**Never commit unseal keys to version control.**
+
+#### Verification
+
+After unsealing, verify Vault is operational:
+
+```bash
+# Check Vault status
+kubectl exec -n vault vault-0 -- vault status
+
+# Test secret access
+just vault::get test/path field
+```
+
+## References
+
+- [Vault Documentation](https://developer.hashicorp.com/vault/docs)