Skip to content

Commit 6d2be49

Browse files
hacker-cbhacker-cb
authored
Migrate to cursor, add ESP-IDF (#4)
* Remove .replit configuration and replit.md documentation files * Update .gitignore to include .vscode and .pio directories * Complete README overhaul for Cursor migration - Restructure root README for multi-image project architecture - Complete rewrite of PlatformIO image README from scratch - Remove misleading claims about pre-cached toolchains - Add comprehensive usage examples (CI/CD, local dev) - Include detailed troubleshooting section - Document design decisions and rationale - Clarify that toolchains download on first build - Add version information table - Improve structure and readability throughout * Add Cursor AI rules for project consistency - project-structure.mdc: Always-applied rule defining multi-image architecture - documentation-standards.mdc: Guidelines for README files (root and image-specific) - dockerfile-standards.mdc: Conventions for Dockerfile creation and optimization - adding-new-images.mdc: Complete checklist for adding new Docker images - commit-conventions.mdc: Git commit message standards and best practices These rules ensure consistency across the project and guide future development. * Add emoji icons to GitHub Actions workflow - Add 🐳 Docker whale to workflow name for better visibility - Add step icons for improved readability: - 📥 Checkout repository - 🔧 Set up Docker Buildx - 🔐 Log in to Registry - 🏷️ Extract metadata - 🎯 Generate tags - 💾 Determine cache strategy - 🐳 Build and push Docker image - 📝 Install Cosign - ✍️ Sign Docker image Improves visual scanning and gives workflow a modern, professional appearance. * Add GitHub Actions workflow standards rule - Define emoji icon conventions for workflow names - Provide comprehensive icon reference for common step types - Include practical examples and benefits - Ensure consistency across all workflow files - Auto-applies to all .yml/.yaml files in .github/workflows/ This rule will help maintain visual consistency and readability in GitHub Actions workflows as the project grows. * Add AI/Cursor commit policy to prevent auto-commits - Explicitly disallow AI from committing changes automatically - AI can suggest commit messages but requires user confirmation - AI can propose what to commit but user must approve - Ensures developer maintains full control over commit history * Update adding-new-images rule to enforce workflow order - Emphasize Dockerfile-first approach - Require local build before documentation - Add warning to never document before successful build - Restructure as step-by-step workflow * Refactor adding-new-images guidelines for clarity and structure - Simplify workflow steps for adding new Docker images - Emphasize the importance of building the image before documentation - Update README requirements to include essential sections - Streamline Dockerfile and README creation guidelines - Enhance testing and verification checklist for new images * Update rules to always apply for consistency across project documentation - Set 'alwaysApply: true' for guidelines on adding new images, commit conventions, Dockerfile standards, documentation standards, and GitHub Actions standards - Ensures uniform application of rules across relevant files * Add reusable workflow and improve project documentation - Create reusable Docker build workflow for all images - Refactor platformio.yml to use reusable workflow (141 -> 45 lines) - Support custom_tags (plural) with comma-separated values - Add .actrc configuration for local workflow testing - Update .gitignore with act-related files and better organization - Update Cursor rules to document reusable workflow pattern - Add local testing guidelines with act to documentation standards * Revise documentation standards and README for clarity - Remove sections on Troubleshooting and Design Decisions from documentation standards to maintain focus on usage. - Update PlatformIO README to eliminate troubleshooting content, emphasizing reliance on upstream documentation. - Streamline version information presentation for improved clarity. * Add build_args input to reusable Docker build workflow - Introduced a new input parameter 'build_args' for specifying build arguments in the reusable Docker build workflow. - This allows users to pass multiple build arguments in a newline-separated format, enhancing flexibility in Docker image builds. * Add ESP-IDF development image and workflow - Introduced a new Docker image for ESP-IDF 5.4.1, including QEMU support and comprehensive testing tools. - Created a GitHub Actions workflow for building the ESP-IDF Docker image, allowing for automated builds on push and pull request events. - Updated README with detailed usage instructions, supported chips, and quick start guide for the ESP-IDF image. - Added Dockerfile for the ESP-IDF image, including necessary dependencies and configuration for testing and code quality tools. * Remove clang-format and clang-tidy from Dockerfile and README for a streamlined ESP-IDF development environment. * Update cache configuration in reusable Docker build workflow to include image scope for better caching management * Update ESP-IDF workflow to conditionally add version tag only on master branch - Modify the logic for adding the ESP-IDF version tag to ensure it is only included when the workflow is triggered on the master branch. - Adjust handling of custom tags to maintain flexibility in tagging based on branch context.
1 parent 58bdab9 commit 6d2be49

17 files changed

+1304
-297
lines changed

‎.actrc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# act configuration for local workflow testing
2+
# Usage: act -j build-and-push
3+
4+
# Use medium Ubuntu runner image for better compatibility
5+
-P ubuntu-latest=catthehacker/ubuntu:act-latest
6+
7+
# Enable verbose output
8+
--verbose
9+
10+
# Container options
11+
--container-options "--platform linux/amd64"
12+

‎.cursor/rules/adding-new-images.mdc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
alwaysApply: true
3+
---
4+
# Adding New Docker Images
5+
6+
## Workflow
7+
8+
1. **Create Dockerfile** - Write and refine the Dockerfile
9+
2. **Build Locally** - Build and test the image thoroughly
10+
3. **Create Workflow** - Add GitHub Actions workflow for CI/CD
11+
4. **Generate Documentation** - Only after successful build, create README
12+
13+
## Directory Structure
14+
15+
Create new directory: `images/<image-name>/` containing:
16+
- `Dockerfile` - Image definition
17+
- `README.md` - Comprehensive documentation
18+
- Supporting files as needed
19+
20+
## Dockerfile Requirements
21+
22+
- Base image with version
23+
- Build arguments for version pinning
24+
- Environment variables for tool paths
25+
- Working directory `/workspace`
26+
- Verification step
27+
- Layer optimization (combine RUN commands, cleanup)
28+
29+
## README Requirements
30+
31+
Image README must include:
32+
- Overview and description
33+
- What's Inside (specific versions)
34+
- Quick Start (pull, build, run)
35+
- Usage Examples
36+
- CI/CD Integration examples
37+
- Environment Variables
38+
- Building the Image
39+
40+
- Version Information table
41+
42+
## Update Root README
43+
44+
Add new image to the table in root README. Keep it minimal - just image name, brief description, and link.
45+
46+
## Registry Naming
47+
48+
Images published as: `ghcr.io/jethome-iot/jethome-dev-<image-name>`
49+
50+
## GitHub Actions Workflow
51+
52+
Create `.github/workflows/<image-name>.yml`:
53+
- Use reusable workflow: `.github/workflows/reusable-docker-build.yml`
54+
- Set triggers for image directory and workflow file changes
55+
- Pass `image_name` and `context_path` parameters
56+
- Include manual trigger and monthly rebuild schedule
57+
- Test locally with `act -j build -W .github/workflows/<image-name>.yml --dryrun`
58+
59+
## Testing
60+
61+
Before committing:
62+
- Build Docker image locally and verify functionality
63+
- Test workflow with `act` in dry-run mode
64+
- Test all README examples
65+
- Check image size is reasonable

‎.cursor/rules/commit-conventions.mdc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
alwaysApply: true
3+
---
4+
# Git Commit Conventions
5+
6+
## Commit Message Format
7+
8+
Use clear, descriptive commit messages that explain **what** and **why**.
9+
10+
```
11+
<Brief summary line>
12+
13+
- Detailed point 1
14+
- Detailed point 2
15+
- Detailed point 3
16+
```
17+
18+
Good: `Add new development image` with detailed list
19+
Bad: `Update files`, `Fix`, `WIP`, `changes`
20+
21+
## AI/Cursor Commit Policy
22+
23+
**🚫 NEVER AUTO-COMMIT**
24+
25+
- AI assistants must NEVER commit changes automatically
26+
- AI assistants must NEVER use `git commit` without explicit user confirmation
27+
- Only the USER decides when to commit
28+
- USER must review and approve all commits
29+
30+
## Branch Strategy
31+
32+
- **dev** - Development work, testing
33+
- **master** - Stable releases only
34+
- Feature branches - For experimental work
35+
36+
## Commit Grouping
37+
38+
Group related changes in single commit:
39+
- Dockerfile + README for same feature
40+
- All files needed for new image
41+
42+
Keep separate:
43+
- Don't mix unrelated changes
44+
- Don't combine feature + bugfix
45+
- Don't combine multiple images in one commit

‎.cursor/rules/dockerfile-standards.mdc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
alwaysApply: true
3+
---
4+
# Dockerfile Standards
5+
6+
## General Guidelines
7+
8+
### Base Image
9+
- Use slim variants to minimize image size
10+
- Pin versions
11+
- Document base image choice in README
12+
13+
### Build Arguments
14+
- Use `ARG` for version pinning
15+
- Provide sensible defaults
16+
- Document all build args in README
17+
18+
### Environment Variables
19+
- Centralize tool directories
20+
- Set all relevant `ENV` variables at image level
21+
- Document in README
22+
23+
### Layer Optimization
24+
- Combine `RUN` commands where logical
25+
- Clean up in same layer (`apt-get clean`, `rm -rf`)
26+
- Use `--no-cache-dir` for pip installs
27+
28+
### Working Directory
29+
- Set to `/workspace` for user projects
30+
- Mount user code here as volume
31+
32+
### Verification
33+
- Add verification `RUN` at end to check installations
34+
35+
### CI/CD Focus
36+
- Optimize for automated builds
37+
- Keep images small - don't pre-download large toolchains unless necessary
38+
- Let frameworks download on first build (toolchains cache in volumes)

‎.cursor/rules/documentation-standards.mdc‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
alwaysApply: true
3+
---
4+
# Documentation Standards
5+
6+
## Root README
7+
8+
Must be:
9+
- **Generic**: Suitable for multi-image architecture
10+
- **Minimal**: Brief overview, not detailed
11+
- **Scalable**: Easy to add new images
12+
13+
Structure:
14+
1. Brief project description
15+
2. Table of current images with links
16+
3. Generic quick start
17+
4. Project structure diagram
18+
5. Registry information
19+
6. License
20+
21+
## Image READMEs
22+
23+
Must be:
24+
- **Comprehensive**: All details about the image
25+
- **Accurate**: No misleading claims
26+
- **Practical**: Real-world usage examples
27+
28+
Required sections:
29+
1. Overview
30+
2. What's Inside (specific versions)
31+
3. Quick Start
32+
4. Usage Examples
33+
5. Environment Variables
34+
6. Building the Image
35+
7. Version Information table
36+
37+
Sections to AVOID:
38+
- Troubleshooting (users can refer to upstream documentation)
39+
- Design Decisions (keep documentation focused on usage)
40+
41+
## Accuracy Rules
42+
43+
- Only document what's actually in the Dockerfile
44+
- Clearly state what downloads at runtime vs pre-installed
45+
- Include actual version numbers
46+
- Never claim features that aren't implemented

‎.cursor/rules/github-actions-standards.mdc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
alwaysApply: true
3+
---
4+
# GitHub Actions Standards
5+
6+
## Workflow Naming
7+
8+
Use emoji icons for better visibility:
9+
10+
```yaml
11+
name: 🐳 Docker Build Workflow
12+
```
13+
14+
Common icons:
15+
- 🐳 Docker builds
16+
- 🔧 Build/compile
17+
- 🧪 Testing
18+
- 📦 Package/release
19+
- 🚀 Deployment
20+
21+
## Step Icons
22+
23+
Add emoji to step names for readability:
24+
25+
- 📥 Checkout code
26+
- 🔧 Setup/configure tools
27+
- 🔐 Authentication
28+
- 🐳 Docker operations
29+
- 🧪 Run tests
30+
- 🚀 Deploy
31+
32+
## Per-Image Workflows
33+
34+
Each image should have its own workflow file:
35+
- Naming: `.github/workflows/<image-name>.yml`
36+
- Trigger on relevant file changes only
37+
- Use branch-based tagging (dev, latest, stable)
38+
- Use reusable workflow: `.github/workflows/reusable-docker-build.yml`
39+
40+
## Local Testing
41+
42+
Test workflows locally using `act`:
43+
- Configuration in `.actrc`
44+
- Test specific job: `act -j build`
45+
- Use `.secrets` file for local secrets (gitignored)

‎.cursor/rules/project-structure.mdc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
alwaysApply: true
3+
---
4+
# JetHome Development Environment - Project Structure
5+
6+
Multi-image Docker project providing development environments for embedded systems.
7+
8+
## Repository Structure
9+
10+
```
11+
jethome-dev/
12+
├── images/
13+
│ └── <image-name>/ # Each image in its own directory
14+
│ ├── Dockerfile # Image definition
15+
│ ├── README.md # Detailed image documentation
16+
│ └── ... # Supporting files
17+
├── .cursor/rules/ # Cursor AI rules
18+
├── LICENSE # MIT License
19+
└── README.md # Root README (minimal, generic)
20+
```
21+
22+
## Key Principles
23+
24+
1. **Root README**: Keep minimal and generic - overview for multiple images
25+
2. **Image READMEs**: Comprehensive and detailed - all specifics go here
26+
3. **One image per directory**: Each in `images/<image-name>/`
27+
4. **Self-contained**: Each image directory contains everything needed to build it
28+
29+
## Registry
30+
31+
Images published to GitHub Container Registry (GHCR):
32+
- Format: `ghcr.io/jethome-iot/jethome-dev-<image-name>`
33+
34+
## Branch Strategy
35+
36+
- `dev` - Development branch
37+
- `master` - Stable releases

‎.github/workflows/esp-idf.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# ESP-IDF Docker Build Workflow
2+
name: 🐳 ESP-IDF Docker Image
3+
4+
env:
5+
ESP_IDF_VERSION: v5.4.1
6+
7+
on:
8+
push:
9+
branches: [master, dev]
10+
paths:
11+
- '.github/workflows/esp-idf.yml'
12+
- '.github/workflows/reusable-docker-build.yml'
13+
- 'images/esp-idf/**'
14+
pull_request:
15+
branches: [master, dev]
16+
paths:
17+
- '.github/workflows/esp-idf.yml'
18+
- '.github/workflows/reusable-docker-build.yml'
19+
- 'images/esp-idf/**'
20+
# Manual trigger
21+
workflow_dispatch:
22+
inputs:
23+
esp_idf_version:
24+
description: 'ESP-IDF version (e.g., v5.4.1, v5.3.1)'
25+
required: false
26+
default: 'v5.4.1'
27+
type: string
28+
force_rebuild:
29+
description: 'Force rebuild without cache'
30+
required: false
31+
default: false
32+
type: boolean
33+
custom_tags:
34+
description: 'Additional custom tags (comma-separated, optional)'
35+
required: false
36+
default: ''
37+
type: string
38+
39+
jobs:
40+
prepare:
41+
runs-on: ubuntu-latest
42+
outputs:
43+
esp_idf_version: ${{ steps.prepare.outputs.esp_idf_version }}
44+
custom_tags: ${{ steps.prepare.outputs.custom_tags }}
45+
steps:
46+
- name: 🏷️ Prepare ESP-IDF version and tags
47+
id: prepare
48+
run: |
49+
ESP_IDF_VERSION="${{ github.event.inputs.esp_idf_version || env.ESP_IDF_VERSION }}"
50+
CUSTOM_TAGS="${{ github.event.inputs.custom_tags || '' }}"
51+
52+
# Add ESP-IDF version tag only on master branch
53+
if [ "${{ github.ref_name }}" == "master" ]; then
54+
if [ -n "$CUSTOM_TAGS" ]; then
55+
TAGS="${CUSTOM_TAGS},${ESP_IDF_VERSION}"
56+
else
57+
TAGS="${ESP_IDF_VERSION}"
58+
fi
59+
else
60+
TAGS="${CUSTOM_TAGS}"
61+
fi
62+
63+
echo "esp_idf_version=${ESP_IDF_VERSION}" >> $GITHUB_OUTPUT
64+
echo "custom_tags=${TAGS}" >> $GITHUB_OUTPUT
65+
66+
build:
67+
needs: prepare
68+
uses: ./.github/workflows/reusable-docker-build.yml
69+
permissions:
70+
contents: read
71+
packages: write
72+
id-token: write
73+
with:
74+
image_name: jethome-dev-esp-idf
75+
context_path: images/esp-idf
76+
force_rebuild: ${{ github.event.inputs.force_rebuild || false }}
77+
custom_tags: ${{ needs.prepare.outputs.custom_tags }}
78+
build_args: |
79+
ESP_IDF_VERSION=${{ needs.prepare.outputs.esp_idf_version }}
80+

0 commit comments

Comments
 (0)