Installation Guide - striae-org/striae GitHub Wiki

This guide provides a single deployment path for Striae on Cloudflare.

Table of Contents

Prerequisites

Before starting installation and deployment, make sure you have:

  1. A Cloudflare account with a registered domain name.
  2. A Firebase project with Authentication enabled.
  3. Node.js version 20.0.0 or higher.
  4. Git.
  5. A Bash-compatible shell (Linux, macOS, WSL, or Git Bash on Windows).

Cloudflare services required:

  • Cloudflare Pages (frontend hosting)
  • Cloudflare Workers (backend microservices)
  • Cloudflare Browser Rendering (PDF generation)
  • Cloudflare KV (user database)
  • Cloudflare R2 (data, audit, and encrypted file/image storage)

Step 1: Cloudflare Service Configuration

1.1 File and Image Service Setup

  1. Record your Cloudflare account identifier: ACCOUNT_ID.
  2. Create a Cloudflare API token with Browser Rendering - Edit permission.
  3. Store that token as BROWSER_API_TOKEN for the PDF Worker.

1.2 Cloudflare KV Setup

  1. Create a KV namespace for user data (commonly named USER_DB).
  2. Record the namespace ID (UUID format) for KV_STORE_ID.
  3. Keep the namespace ID available for guided configuration in Step 2.
  4. Confirm bindings later use ID, not the namespace display name.

Important: the Namespace ID is different from the namespace name. You need the UUID-format ID, not the name USER_DB.

1.3 Cloudflare R2 Setup

  1. Create three R2 buckets: one for case data (DATA_BUCKET_NAME), one for audit logs (AUDIT_BUCKET_NAME), and one for encrypted files/images (FILES_BUCKET_NAME).

No CORS configuration is required on the R2 buckets. All browser traffic goes through the same-origin Pages proxy (/api/*); the buckets are accessed exclusively via worker bindings and are never reached directly by the browser.

1.4 Cloudflare Pages Project and Domain Setup

  1. Create a Cloudflare Pages project for Striae before running deployment scripts.
  2. Set the project name you want to use for PAGES_PROJECT_NAME.
  3. Add your custom domain in Cloudflare Pages and complete verification.
  4. Use the verified bare domain as PAGES_CUSTOM_DOMAIN (for example, striae.org, without https://).
  5. Confirm the custom domain status is Active and HTTPS is enabled.
  6. Set the Cloudflare Pages Production branch to your repository default branch (typically main or master), and ensure the name matches exactly.

Important: npm run deploy:all assumes the Pages project exists, the custom domain is verified, and the Production branch name matches your repo default branch (main or master).

Firebase Authentication Setup

Set Up Firebase Authentication Project

  1. Create (or select) a Firebase project for your Striae deployment.
  2. Enable Firebase Authentication for the project.
  3. Enable the sign-in provider(s) used by your deployment (at minimum, Email/Password).
  4. Add your application domains to authorized domains (production and development).

Configure MFA

  1. Enable multi-factor authentication in Firebase Authentication.
  2. Enable SMS/phone and/or TOTP as MFA factors.
  3. Confirm reCAPTCHA protections are enabled for phone verification.
  4. For non-production testing, configure test phone numbers and verification codes.
  5. To enable the TOTP MFA provider for your Firebase project, run the following script after app/config/admin-service.json is populated:
npm run enable-totp-mfa

This is a one-time operation. The script calls the Firebase Admin SDK to activate TOTP and configures it with adjacentIntervals: 0.

Configure Email Actions

  1. Configure Firebase email action templates for password reset and email verification.
  2. Set the action URL to your deployed Striae auth route:
https://your-domain.com/auth
  1. Ensure authorized domains include every domain used for auth flows.
  2. Validate continue URLs resolve to same-origin or relative routes.

Generate admin-service JSON

  1. Create a Firebase service account key (JSON) for Admin SDK access.
  2. Create the local credential file from the template:
mkdir -p app/config
cp -f app/config-example/admin-service.json app/config/admin-service.json
  1. Replace app/config/admin-service.json contents with your downloaded service account JSON.
  2. Verify these required fields are present: project_id, client_email, and private_key.
  3. Keep app/config/admin-service.json private and never commit it.

Note:

  • deploy-config.sh and deploy-worker-secrets.sh both require app/config/admin-service.json.

Step 2: npm Package, Installation, and Full Deployment

Complete Step 1 and Firebase Authentication Setup first. The Pages project, custom domain, and Production branch setting from Step 1.4 must already be configured before running deploy:all.

Striae Package Links

  1. Install the latest package:
npm i @striae-org/striae
  1. Copy the package scaffold into the project root:
cp -R node_modules/@striae-org/striae/. .
  1. Reinstall using Striae's own package.json (includes dev deps like wrangler/react-router):
rm -rf node_modules package-lock.json
npm install
  1. Prepare Firebase admin credentials (required before deploy-config can pass):
mkdir -p app/config
cp -f app/config-example/admin-service.json app/config/admin-service.json

  1. Replace app/config/admin-service.json with your actual Firebase service account JSON.

  2. Enable TOTP MFA on the Firebase project (one-time, requires populated admin-service.json):

npm run enable-totp-mfa
  1. Authenticate Cloudflare CLI:
npx wrangler login
  1. Run guided config + full deployment:
npm run deploy:all

Step 3: Deployment Flow Reference

The deploy:all command runs these steps in order:

  1. deploy-config.sh
  2. install-workers.sh
  3. Worker deployments (npm run deploy-workers)
  4. deploy-worker-secrets.sh
  5. deploy-pages-secrets.sh
  6. deploy-pages.sh

Notes:

  • deploy-config imports PROJECT_ID, FIREBASE_SERVICE_ACCOUNT_EMAIL, and FIREBASE_SERVICE_ACCOUNT_PRIVATE_KEY from app/config/admin-service.json.
  • deploy-pages-secrets is available as npm run deploy-pages:secrets and supports --production-only and --preview-only flags.
  • deploy-pages and deploy-pages-secrets require an existing Pages project and verified custom domain matching PAGES_PROJECT_NAME and PAGES_CUSTOM_DOMAIN.
  • Worker routing uses Cloudflare Service Bindings defined in wrangler.toml; no *_WORKER_DOMAIN secrets are required.
  • Optional PrimerShear PDF routing setup: use wrangler kv key put --remote --namespace-id=<STRIAE_LISTS_KV_ID> "primershear" "[email protected]" (or POST /primershear via the lists-worker HTTP API with Authorization: Bearer $LISTS_ADMIN_SECRET) to populate the primershear allowlist. The lists-worker resolves format server-side on each PDF request.
  • Optional registration gateway setup: use wrangler kv key put --remote --namespace-id=<STRIAE_LISTS_KV_ID> "allow" "[email protected],@domain.com" (or POST /members via the lists-worker HTTP API) to populate the registration allowlist. Supports exact emails and @domain.com wildcards. When the list is empty, registration is unrestricted.

Step 4: Testing and Verification

4.1 Test Authentication Flow

  1. Navigate to your deployed application.
  2. Test user authentication (login/registration).
  3. Test user login.
  4. Test multi-factor authentication (MFA).
  5. Test password reset functionality.

4.1.1 Configure Firebase Email Action Handler URL

Striae uses a custom Firebase email action handler on /auth for password resets and email verification.

  1. Open Firebase Console -> Authentication -> Email Templates.
  2. Edit the action URL for templates that trigger user actions and enable Customize action URL.
  3. Set the action URL to your deployed auth route:
https://your-domain.com/auth
  1. Save the template changes.
  2. Open Firebase Console -> Authentication -> Settings -> Authorized domains.
  3. Add each domain you use for Striae auth flows.

Notes:

  • Striae custom handler currently supports resetPassword and verifyEmail actions.
  • recoverEmail (email change recovery) is intentionally not supported because users cannot change their own email address.
  • Continue URLs are validated by Striae to same-origin or relative paths before redirecting.

4.2 Test Core Features

  1. Image upload.
  2. Data save and retrieval.
  3. PDF export.

4.3 Test Public API Endpoints

Verify public API routes through Pages Functions (same-origin):

  • GET/PUT/DELETE /api/user/{uid}
  • GET/PUT/DELETE/POST /api/data/*
  • GET/POST/DELETE /api/image/*
  • GET/POST /api/audit/audit/?userId={uid}
  • POST /api/pdf/

Notes:

  • Browser clients should call /api/* routes, not worker domains directly.
  • /api/* requests must include Firebase bearer auth.
  • Keys Worker is internal and is not exposed through a public /api/keys route.

Step 5: Security Checklist

  • All environment variables are set correctly.
  • Firebase authentication is working.
  • HTTPS is enforced.
  • Required Pages and worker secrets are configured.
  • Export encryption keys are configured for mandatory case, archive, and confirmation package encryption workflows.
  • Worker authentication tokens are unique and secure.
  • Data-at-rest encryption keys are configured for Data, Audit, and Image workers.

For data-at-rest encryption configuration details, see Data-at-Rest Encryption and Environment Variables Setup.

Troubleshooting

Common Issues

  1. Authentication failures: verify Firebase configuration and worker tokens.
  2. Image upload issues: verify Images worker variables and API token values.
  3. Worker errors: verify required variables and bindings are configured.
  4. JSON parse error "Unexpected token '<'": inspect the failing /api/* response body/status for non-JSON upstream errors (for example 401/403/502 HTML/text responses).

KV Namespace Configuration Issues

Error: KV namespace USER_DB is not valid [code: 10042]

This error occurs when KV configuration uses a name instead of the UUID-format ID.

  1. Open workers/user-worker/wrangler.jsonc.
  2. Confirm the id value is a UUID, not USER_DB.
  3. In Cloudflare Dashboard -> Storage & Databases -> KV, copy the Namespace ID.
  4. Update workers/user-worker/wrangler.jsonc with the correct UUID.
  5. Redeploy the user worker.

Useful Commands

wrangler whoami
wrangler tail [worker-name]
wrangler pages deployment list
npm run dev

Related Documentation