Release Process

This guide covers the complete release workflow for the C_AI Platform, from pre-release validation through post-deployment verification and emergency procedures.

Pre-Release Checklist

Before cutting a release, complete all verification steps:

1. Documentation Lint

Run the documentation linter to ensure all docs pass validation:

cd docs-site && yarn lint

This command (from docs-site/package.json line 14) runs:

• yarn lint:terms - Custom terminology validation
• yarn lint:md - Markdown/MDX linting via markdownlint-cli2
• yarn lint:spell - Spell checking via cspell
• yarn build - Full Docusaurus build to catch broken links

All checks must pass before proceeding.

2. Database Schema Sync

Push any pending schema changes to the database:

npm run db:push

This command (from package.json line 12) runs drizzle-kit push which:

• Compares shared/schema.ts against the live database
• Applies schema differences directly
• Requires DATABASE_URL environment variable to be set

See Database Migrations for rollback guidance.

3. Application Startup Verification

Verify the application starts correctly:

npm run dev

This command (from package.json line 8) runs NODE_ENV=development tsx server/index.ts which:

• Starts the Express backend server
• Initializes database connections
• Sets up Vite middleware for frontend development (server/index.ts:118-119)
• Listens on port 5000 (server/index.ts:126)

Confirm no startup errors appear in the console.

4. Tracing Verification

Verify OpenTelemetry traces are flowing to Phoenix:

1. Start the Phoenix server (if not already running):

   python scripts/phoenix_server.py

2. Open Phoenix UI at http://localhost:6006

3. Verify traces appear by running a sample operation

The tracing configuration is defined in server/lib/tracing.ts:

• OTLP endpoint: process.env.PHOENIX_OTLP_ENDPOINT or http://localhost:6006/v1/traces
• Service name: c-ai-backend (line 56)
• Service version: 1.0.0 (line 57)

Legacy identifier

Legacy (internal identifier): the current deployment uses wally-backend as the service name in tracing configuration.

How to Cut a Release

1. Ensure Type Checking Passes

Run TypeScript type checking:

npm run check

This command (from package.json line 11) runs tsc to verify type correctness.

If unit tests or E2E tests are configured, run them:

npx vitest run         # If vitest tests exist
npx playwright test    # If Playwright tests exist

Note: vitest and @playwright/test are installed as dependencies in package.json.

2. Update Version (If Needed)

Update the version in package.json (line 3) if making a version bump:

{
  "name": "rest-express",
  "version": "1.0.0",
  ...
}

Follow semantic versioning:

• MAJOR: Breaking changes to APIs or data model
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

3. Tag the Release Commit

Create a git tag for the release:

git tag -a v1.0.0 -m "Release v1.0.0"

4. Deploy via Replit Publish

Use Replit's built-in publish feature for deployment:

1. Open the Replit workspace
2. Click the Publish button in the top-right corner
3. Configure deployment settings as needed
4. Confirm the deployment

Replit handles:

• Building the production bundle (npm run build)
• Starting the production server (npm run start)
• SSL/TLS certificate provisioning
• Domain configuration

Post-Release Verification

After deployment, verify the release is functioning correctly:

1. Application Accessibility

Verify the application is accessible at the published URL:

• Navigate to the published domain
• Confirm the landing page loads without errors
• Check browser console for JavaScript errors

2. Database Connectivity

Verify database connectivity:

• Attempt to load data from the application
• Check for any database connection errors in logs
• Verify DATABASE_URL environment variable is correctly configured in production

3. Tracing Verification

Verify OpenTelemetry traces are flowing:

• Configure production to send traces to your Phoenix instance
• Verify spans appear in Phoenix UI
• Check for backend service traces (see legacy identifier note below)

Legacy identifier

Legacy (internal identifier): look for wally-backend service traces in the current deployment.

Trace attributes are defined in server/lib/tracing.ts lines 7-47 with an allowlist including:

• tenant.id, pack.id, run.id
• llm.tokens.in, llm.tokens.out, llm.cost.usd
• latency.ms, status

4. Sample Assessment Run

Test a complete assessment workflow:

1. Log in as an admin user
2. Select a tenant and pack
3. Trigger a new assessment run
4. Verify the run completes successfully
5. Check assessment results are generated

Break Glass Procedures

Emergency procedures for critical issues:

1. Rollback via Replit Checkpoints

Replit provides checkpoint-based rollback:

1. Open the Replit workspace
2. Access Version History from the file tree
3. Select a checkpoint from before the problematic deployment
4. Click Restore to rollback code and configuration

This restores:

• All source code files
• Configuration files
• Environment variable settings (non-secret)

2. Database Restore from Backup

For database-level issues:

1. Use Replit's database panel to access backup options

2. Or restore manually via pg_dump backup if available:

   psql $DATABASE_URL < backup.sql

See Database Migrations for manual rollback SQL patterns.

3. Disable Problematic Features via Environment Variables

Key environment variables for feature control:

Variable	Purpose	Effect when unset/false
OPENAI_API_KEY	LLM provider for embeddings	Embedding operations fail gracefully
ANTHROPIC_API_KEY	Alternative LLM provider	Falls back to other providers
PHOENIX_OTLP_ENDPOINT	Tracing destination	Traces disabled, no performance impact

To disable a feature temporarily:

1. Access Replit Secrets/Environment Variables
2. Remove or modify the relevant variable
3. Restart the application workflow

4. Escalation Contacts

For issues that cannot be resolved via self-service:

Issue Type	First Contact	Escalation
Application bugs	Development team	Engineering lead
Database issues	DBA / Platform team	Infrastructure lead
Security incidents	Security team	CISO
Deployment failures	DevOps / Platform team	SRE lead

Related Pages

• Environments & Configuration - Environment management and immutability rules
• Database Migrations - Schema change process and rollback guidance
• Architecture Overview - System layers and request flow
• Testing and Debugging - Test suite reference