Skip to content

App Setup Checklist#

Overview#

Before going live, every application should meet the following requirements regardless of its tech stack or purpose. This checklist ensures a baseline of quality, operability, and maintainability across all our products.

Required#

Automated CI#

Every repository must run automated checks on every merge request:

  • Static code analysis (linting, type checking) — catches issues before human review
  • Automated tests — prevents regressions and validates behaviour

Why: Manual checks are inconsistent and slow. CI enforces standards at every change automatically and can check we did not introduce regressions. See our language-specific standards for tooling choices (e.g., Python style guide, Node.js repo guidelines, PHP/WordPress standards).

Automated Deployments#

  • At minimum, a production and a staging environment must exist. Ideally, one or multiple test environments are also available.
  • Deployments to production and staging environments must be triggered automatically (e.g., on merge to the corresponding branch).
  • Developers must be able to deploy any branch/commit to any staging and test environments, through a manual operation (using a Slack command, changing a value in a configuration file, etc.).

Why: Manual deployments introduce human error and slow down delivery. Staging allows validation before production. Automated pipelines also make deployments auditable and repeatable.

Local Development#

  • The app must be runnable locally, typically via Docker Compose
  • Instructions for running it locally must be documented (in README.md or the docs/ folder)

Why: If a developer cannot run the app locally, onboarding is slow and debugging is harder. Docker removes environment inconsistency across machines.

Error Monitoring#

  • Integrate Sentry or our self-hosted GlitchTip using the Sentry SDK
  • All unhandled exceptions and critical errors in production must be captured and routed to the owning team, through Slack alerts for instance.

Why: Without error monitoring, production issues are discovered by end users. Studies show that it takes about 25 users to see an issue before one reports it. Proactive error visibility allows the team to fix issues before they escalate.

Agentic AI Instructions#

  • Include a project instructions file (CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md) in the repository root
  • This file should describe the app's architecture, conventions, and key context for AI tools

Why: Persistent project context allows AI coding tools to produce more consistent, project-aware output. See AI for Engineering and the project instructions template.

Uptime Monitoring#

  • Expose a dedicated health endpoint (e.g., /health or /ping)
  • Register the endpoint with an uptime monitoring tool such as updown.io
  • Configure the uptime monitoring tool to send alerts to Slack.

Why: Uptime monitoring provides immediate alerting when a service goes down, independent of internal observability systems. A dedicated endpoint avoids false positives from business logic errors.

Documentation Structure#

  • The repository must contain a docs/ folder
  • At minimum, document: what the app does, how to run it locally, and how to deploy it

Why: Documentation is part of the product. It reduces onboarding friction, supports knowledge sharing across teams, and is especially important when AI tools are used on the codebase.

Optional (Nice to Have)#

Product Analytics#

  • Integration with MixPanel for tracking user behaviour and product usage

Metrics & Observability#

  • Integration with Prometheus for technical metrics (latency, throughput, error rates, resource usage)

BI & data-based Alerting#

  • All SQL databases synced to Metabase to enable business intelligence dashboards and data-driven alerts