Self-Hosted Community Edition: deployment manual

This operator guide deploys Community Edition into your AWS account. It does not apply to VaultGuard Sync (Cloud).

Responsibilities and prerequisites

You need:

• an AWS account with permission to create the documented IAM, Cognito, DynamoDB, S3, Lambda, API Gateway, CloudWatch, KMS, SES, WAF, and optional DNS resources;
• AWS CLI v2;
• Terraform 1.6 or newer;
• Node.js 20, npm, and Git;
• an email identity you can verify in AWS SES; and
• an operator-owned process for Terraform state, backups, upgrades, monitoring, and incident response.

Never commit AWS credentials, populated .tfvars, Terraform state, saved plans, recovery material, or generated secrets.

1. Clone the public repository

git clone https://github.com/peter70700/vaultguard-obsidian.git
cd vaultguard-obsidian
npm install

The public monorepo places the server under packages/server/.

2. Build the server bundles

cd packages/server/infrastructure
npm install
npm run build:lambdas

Rebuild the bundles after pulling server source changes and before planning an upgrade.

3. Create the Community Edition variables file

cd ../terraform
cp environments/ce.tfvars.example environments/ce.tfvars

Review every value. At minimum, set the stage, operator alert email, and SES sender information. Keep:

vaultguard_edition = "community"

Leave public signup disabled for normal single-tenant use after bootstrap. A custom domain is optional; the AWS-provided endpoints work without one.

4. Plan before applying

terraform init
export TF_VAR_turnstile_secret_arn=""
terraform plan -input=false -var="stage=dev" -var-file=environments/ce.tfvars

Review the plan carefully. Use an operator-managed remote state backend for a real shared deployment; the state can contain sensitive infrastructure data.

Apply only the reviewed configuration:

terraform apply -var="stage=dev" -var-file=environments/ce.tfvars

Record the non-secret outputs required for the plugin, including the API URL, Cognito user-pool ID, Cognito client ID, and vault bucket name.

5. Bootstrap the first organization

Do not create only a Cognito user with admin-create-user. That leaves the VaultGuard organization, vault membership, and default permission records missing.

Bootstrap the first organization through the deployment's signup endpoint:

API_URL=$(terraform output -raw api_url)

curl -X POST "$API_URL/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "orgName": "Acme Corp",
    "orgSlug": "acme-corp",
    "email": "you@example.com",
    "password": "replace-with-a-unique-compliant-password",
    "displayName": "Your Name"
  }'

Run this from a private operator shell. Do not paste a real password into an issue, shared transcript, note, or screenshot.

The successful bootstrap creates the first user, organization, default vault, vault-admin membership, and default permission rule. Normal Community Edition single-tenant mode then refuses additional public organization signups.

6. Verify transactional email

Open AWS SES in the deployment region and verify the configured sender. If the account remains in the SES sandbox, recipients may also need verification. Invitation and password-reset workflows depend on this operator-owned email configuration.

7. Install and connect the Obsidian plugin

1. In Obsidian, open Settings → Community plugins → Browse.
2. Search for VaultGuard Sync, install it, and enable it.
3. Open VaultGuard settings → Connection.
4. Switch from the default Cloud target to manual/self-hosted configuration.
5. Paste the server configuration URL:

<api_url>/.well-known/vaultguard.json

6. Apply the configuration and sign in with the bootstrap administrator.
7. Bind the local folder to the default server vault.

Use the advanced API and Cognito fields only when automatic server-config discovery is unavailable.

8. Verify with disposable content

1. Sign in as the bootstrap administrator.
2. Create and sync a non-sensitive test note.
3. Confirm the object stored in the vault bucket is ciphertext rather than readable Markdown.
4. Invite a test user from the in-Obsidian organization admin modal.
5. Grant narrow vault access and verify an allowed and a denied action.
6. Review the basic audit event.
7. Test a restore path and your operator-owned backup procedure before adding production knowledge.

Do not use the hosted Cloud admin panel for this verification. Community Edition administration is entirely in Obsidian.

Upgrade workflow

1. Read the release notes and security notices.
2. Back up state and data through your approved operator process.
3. Pull the intended release and rebuild the Lambda bundles.
4. Run a Terraform plan with the same explicit stage and Community variables file.
5. Review the plan, apply it, and repeat the disposable-note smoke test.
6. Update VaultGuard Sync through Obsidian's Community plugins flow.

Common deployment problems

Problem	Operator response
API connection fails	Verify the API URL, stage, Cognito IDs, certificate, and Lambda health.
Invitations do not arrive	Verify the SES sender, sandbox status, recipient, and email Lambda logs.
Public signup is refused	This is expected after the first organization in normal single-tenant mode. Sign in as the existing admin.
A Cloud-only button appears	Confirm the server advertises edition: community and the plugin refreshed configuration after login.
Terraform state is locked	Follow your state-backend recovery process; do not delete or replace state blindly.
A Pro endpoint returns not found	Share links, hosted web administration, billing, and advanced audit are intentionally unavailable in Community Edition.