Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Local Development Setup process is designed to enable any developer to get the application running locally in minutes by following a structured and "absurdly thorough" documentation approach. This setup serves as the primary gateway for contributors to understand the system architecture, configure dependencies, and establish a functional environment for feature development and testing.
The scope of this setup covers deep codebase exploration, identifying deployment targets, configuring environment variables, and executing the necessary scripts to initialize databases and start development servers.
Sources: bundled-skills/readme/SKILL.md:21-25, bundled-skills/wiki-onboarding/SKILL.md:57-61
Development Environment Initialization
Setting up the local environment requires a systematic approach to dependency management and configuration. Developers must first identify the primary framework and language by examining root configuration files such as package.json, Gemfile, or requirements.txt.
1. Prerequisites and Dependencies
Before starting, specific system-level tools must be installed based on the project's tech stack. Common requirements include runtimes (Node.js, Ruby, Python), database engines (PostgreSQL, Redis), and package managers (pnpm, yarn, bundle).
Sources: bundled-skills/readme/SKILL.md:41-45, bundled-skills/readme/SKILL.md:124-129
2. Configuration Workflow
The setup process follows a linear progression from cloning the repository to launching the services.
The diagram above illustrates the standard sequence of operations required to transition a fresh environment into a functional development state.
Sources: bundled-skills/readme/SKILL.md:135-195, bundled-skills/wiki-onboarding/SKILL.md:65-68
Configuration and Secrets Management
Local development relies heavily on environment variables to manage sensitive data and service connection strings without hardcoding them into the source.
Environment Variable Reference
Variables are typically managed via a .env file, cloned from a provided .env.example.
| Variable | Description | Example/Source |
|---|---|---|
DATABASE_URL | Connection string for the primary database | postgresql://localhost/dev_db |
SECRET_KEY_BASE | Key for session encryption/cookies | bin/rails secret |
REDIS_URL | Connection for background jobs/caching | redis://localhost:6379/0 |
RAILS_MASTER_KEY | Key for decrypting credentials | config/master.key |
Sources: bundled-skills/readme/SKILL.md:150-165, bundled-skills/readme/SKILL.md:255-275
Credentials and Security
For sensitive values that must remain encrypted even in development, projects may use a credentials system (e.g., Rails encrypted credentials). These are edited via specific CLI commands that open an encrypted file in the default system editor.
Sources: bundled-skills/readme/SKILL.md:280-295, bundled-skills/codebase-audit-pre-push/SKILL.md:55-60
Database and Data Layer Setup
Initializing the data layer involves creating the schema, running migrations, and seeding the database with initial development data.
Database Operations
Common commands for managing the local data state:
db:create: Initializes the local database instance.db:migrate: Applies schema changes from migration files.db:seed: Populates the database with sample records for development.db:setup: A combined command that executes create, load, and seed.
Sources: bundled-skills/readme/SKILL.md:175-185, bundled-skills/readme/SKILL.md:315-322
The sequence diagram shows the interaction between the developer, the task runner, and the database engine during a schema update.
Sources: bundled-skills/readme/SKILL.md:180-185, bundled-skills/readme/SKILL.md:315-325
Development Workflows and Scripts
Once configured, the application is managed through a series of scripts defined in the project's task runner (e.g., package.json scripts or bin/ directory).
Core Development Commands
| Command | Description | Context |
|---|---|---|
bin/dev | Launches both backend and frontend servers | Integrated Dev |
bin/rails console | Opens an interactive REPL with app context | Debugging/Data Ops |
bin/rails test | Executes the test suite (Minitest/RSpec) | Verification |
yarn lint | Runs linters for JS/TS code | Quality Control |
Sources: bundled-skills/readme/SKILL.md:312-327, bundled-skills/tutorial-engineer/SKILL.md:258-262
Pre-Push Audit
Before contributing, developers should perform a local audit to ensure the environment is clean of junk files (.DS_Store, logs) and that no secrets are being accidentally committed to version control.
Sources: bundled-skills/codebase-audit-pre-push/SKILL.md:25-45
Summary
The local development setup provides a standardized foundation for contributors, ensuring that environment variables, database states, and service dependencies are correctly configured. By following the "Zero-to-Hero" path, new team members can progress from initial repository cloning to active feature development while adhering to the project's architectural and security standards.
Sources: bundled-skills/wiki-onboarding/SKILL.md:52-55, bundled-skills/wiki-architect/SKILL.md:32-35