Skip to content

Update Development Setup Documentation #46

Description

@ashmortar

Description

Add runner development setup to existing or new development documentation, showing how to run the control plane and runners locally for testing.

Scope

Create or update docs/development.md with local development setup instructions that include the runner architecture.

Content to Add:

1. Running Eph Locally

## Running Eph Locally

### Control Plane (ephd)

```bash
# Start PostgreSQL
docker run -d -p 5432:5432 \
  -e POSTGRES_PASSWORD=eph \
  -e POSTGRES_DB=eph \
  postgres:16

# Run migrations
go run ./cmd/migrate up

# Start ephd
go run ./cmd/ephd

Runner

# In another terminal
export EPH_TOKEN=dev-token
export EPH_CONTROL_PLANE=http://localhost:8080

go run ./cmd/eph-runner

Testing Full Flow

  1. Create a test repo with eph.yaml
  2. Open PR and add 'preview' label
  3. Watch runner logs for reconciliation
  4. Verify namespace created in cluster

#### 2. Environment Variables
Document all required environment variables for local development:
- `EPH_TOKEN` - Runner authentication token
- `EPH_CONTROL_PLANE` - Control plane URL
- `DATABASE_URL` - PostgreSQL connection string
- `GITHUB_APP_ID` - GitHub App ID
- `GITHUB_PRIVATE_KEY` - GitHub App private key

#### 3. Docker Compose Setup
```markdown
### Docker Compose (Alternative)

For a complete local setup:

```yaml
version: '3.8'
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: eph
      POSTGRES_DB: eph
    ports:
      - "5432:5432"
  
  ephd:
    build: .
    command: ./ephd
    environment:
      DATABASE_URL: postgres://postgres:eph@postgres:5432/eph
    ports:
      - "8080:8080"
    depends_on:
      - postgres

#### 4. Testing Configuration
Include instructions for:
- Creating test eph.yaml files
- Mocking GitHub webhook events
- Testing runner reconciliation
- Debugging common issues

#### 5. IDE Setup
Include VSCode/GoLand configuration for debugging both ephd and runners.

## Files to Create/Modify
- `docs/development.md` - Local development setup (create if doesn't exist)
- `docker-compose.dev.yml` - Optional development docker-compose file

## Acceptance Criteria
- [ ] Clear instructions for running ephd locally
- [ ] Runner development setup documented
- [ ] Environment variables clearly listed
- [ ] Docker Compose alternative provided
- [ ] Testing flow documented
- [ ] Common development issues addressed
- [ ] IDE debugging setup included

## Labels
`documentation`, `enhancement`

## Phase
1-Documentation

## Priority  
P1 (Medium)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions