Skip to content

full-stack-setup.md

Latest commit

 

History

History
267 lines (215 loc) · 7.31 KB

full-stack-setup.md

File metadata and controls

267 lines (215 loc) · 7.31 KB

Full Stack Setup

Complete integration of all toolkit services for a production application.

Architecture Overview

┌────────────────────────────────────────────────────────────┐
│                    Your Application                        │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │ Appwrite │ │ DevCycle │ │  Sentry  │ │Honeybadger│      │
│  │ Backend  │ │  Flags   │ │ Errors   │ │  Uptime  │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
│                                                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │CodeScene │ │Requestly │ │ Polypane │ │   Zyte   │      │
│  │ Quality  │ │  Debug   │ │   Test   │ │  Scrape  │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
│                                                            │
└────────────────────────────────────────────────────────────┘

Tool Purposes

Tool Phase Purpose
Appwrite Development Backend services
Requestly Development API mocking/debugging
Polypane Development Responsive testing
CodeScene CI/CD Code quality gates
DevCycle Production Feature flags
Sentry Production Error & performance
Honeybadger Production Uptime & alerts
Zyte As needed Data collection

Complete Setup

1. Project Initialization

# Initialize toolkit in your project
./templates/init-toolkit.sh /path/to/project

# Or with Claude Code
/toolkit-init

2. Environment Configuration

# .env.example - Copy to .env and fill in values

# Appwrite (Backend)
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID=
APPWRITE_API_KEY=

# DevCycle (Feature Flags)
DEVCYCLE_SERVER_SDK_KEY=
DEVCYCLE_CLIENT_SDK_KEY=

# Sentry (Errors)
SENTRY_DSN=
SENTRY_AUTH_TOKEN=
SENTRY_ORG=
SENTRY_PROJECT=

# Honeybadger (Uptime)
HONEYBADGER_API_KEY=

# CodeScene (Quality)
CODESCENE_API_TOKEN=
CODESCENE_PROJECT_ID=

# Zyte (Scraping)
ZYTE_API_KEY=

3. Application Bootstrap

// lib/services.js
import { Client as AppwriteClient } from 'appwrite';
import { initializeDevCycle } from '@devcycle/nodejs-server-sdk';
import * as Sentry from '@sentry/node';
import Honeybadger from '@honeybadger-io/js';

export async function initServices() {
  // Initialize Sentry first (catches init errors)
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV,
    tracesSampleRate: 0.1,
  });

  // Initialize Honeybadger
  Honeybadger.configure({
    apiKey: process.env.HONEYBADGER_API_KEY,
    environment: process.env.NODE_ENV,
  });

  // Initialize Appwrite
  const appwrite = new AppwriteClient()
    .setEndpoint(process.env.APPWRITE_ENDPOINT)
    .setProject(process.env.APPWRITE_PROJECT_ID);

  // Initialize DevCycle
  const devcycle = await initializeDevCycle(
    process.env.DEVCYCLE_SERVER_SDK_KEY
  );

  return { appwrite, devcycle };
}

4. React/Frontend Setup

// App.jsx
import { DevCycleProvider } from '@devcycle/react-client-sdk';
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: process.env.REACT_APP_SENTRY_DSN,
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
  tracesSampleRate: 0.1,
  replaysSessionSampleRate: 0.1,
});

function App() {
  return (
    <Sentry.ErrorBoundary fallback={<ErrorPage />}>
      <DevCycleProvider
        sdkKey={process.env.REACT_APP_DEVCYCLE_CLIENT_SDK_KEY}
        user={{ user_id: getUserId() }}
      >
        <Router />
      </DevCycleProvider>
    </Sentry.ErrorBoundary>
  );
}

5. GitHub Actions Pipeline

# .github/workflows/full-pipeline.yml
name: Full CI/CD Pipeline

on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: CodeScene Analysis
        uses: codescene/codescene-ci-cd@v1
        with:
          api-token: ${{ secrets.CODESCENE_API_TOKEN }}
          project-id: ${{ vars.CODESCENE_PROJECT_ID }}

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm test

  deploy:
    needs: [quality, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy
        run: npm run deploy

      - name: Sentry Release
        uses: getsentry/action-release@v1
        env:
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ vars.SENTRY_ORG }}
          SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}

      - name: DevCycle Sync
        uses: DevCycleHQ/feature-flag-code-refs@v1
        with:
          client-id: ${{ secrets.DEVCYCLE_CLIENT_ID }}
          client-secret: ${{ secrets.DEVCYCLE_CLIENT_SECRET }}

6. Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Run CodeScene check
if command -v codescene-cli &> /dev/null; then
  codescene-cli analyze --staged
  if [ $? -ne 0 ]; then
    echo "CodeScene: Quality issues detected"
    exit 1
  fi
fi

# Run linter
npm run lint --quiet

Development Workflow

Daily Development

  1. Use Requestly to mock APIs during frontend work
  2. Use Polypane to test responsive layouts
  3. Write code with CodeScene IDE extension feedback

Before Commit

  1. Pre-commit hook runs CodeScene checks
  2. Fix any code health issues

Before Merge

  1. CodeScene analyzes PR
  2. All tests pass
  3. Review and merge

After Deploy

  1. Sentry release created automatically
  2. DevCycle flags updated
  3. Honeybadger monitors uptime

New Feature Rollout

  1. Wrap in DevCycle flag
  2. Deploy to production (flag off)
  3. Enable for 5% of users
  4. Monitor Sentry for errors
  5. Gradually increase to 100%

Monitoring Checklist

  • Honeybadger uptime checks configured
  • Sentry alerts for new issues
  • DevCycle environments set up (dev, staging, prod)
  • CodeScene PR analysis enabled
  • GitHub Actions pipeline working

Best Practices

  1. Initialize monitoring first: Catch init errors
  2. Use feature flags for risky changes: Easy rollback
  3. Gate PRs on code quality: Maintain code health
  4. Set up uptime monitoring: Know before users report
  5. Configure alerts: Don't rely on checking dashboards